Create a shared image gallery with the Azure CLI

A Shared Image Gallery simplifies custom image sharing across your organization. Custom images are like marketplace images, but you create them yourself. Custom images can be used to bootstrap configurations such as preloading applications, application configurations, and other OS configurations.

The Shared Image Gallery lets you share your custom VM images with others in your organization, within or across regions, within an AAD tenant. Choose which images you want to share, which regions you want to make them available in, and who you want to share them with. You can create multiple galleries so that you can logically group shared images.

The gallery is a top-level resource that provides full role-based access control (RBAC). Images can be versioned, and you can choose to replicate each image version to a different set of Azure regions. The gallery only works with Managed Images.

The Shared Image Gallery feature has multiple resource types. We will be using or building these in this article:

Resource Description
Managed image This is a basic image that can be used alone or used to create an image version in an image gallery. Managed images are created from generalized VMs. A managed image is a special type of VHD that can be used to make multiple VMs and can now be used to create shared image versions.
Image gallery Like the Azure Marketplace, an image gallery is a repository for managing and sharing images, but you control who has access.
Image definition Images are defined within a gallery and carry information about the image and requirements for using it internally. This includes whether the image is Windows or Linux, release notes, and minimum and maximum memory requirements. It is a definition of a type of image.
Image version An image version is what you use to create a VM when using a gallery. You can have multiple versions of an image as needed for your environment. Like a managed image, when you use an image version to create a VM, the image version is used to create new disks for the VM. Image versions can be used multiple times.

Before you begin

To complete the example in this article, you must have an existing managed image of a generalized VM. For more information, see Tutorial: Create a custom image of an Azure VM with the Azure CLI. If the managed image contains a data disk, the data disk size cannot be more than 1 TB.

Launch Azure Cloud Shell

The Azure Cloud Shell is a free interactive shell that you can use to run the steps in this article. It has common Azure tools preinstalled and configured to use with your account.

To open the Cloud Shell, just select Try it from the upper right corner of a code block. You can also launch Cloud Shell in a separate browser tab by going to Select Copy to copy the blocks of code, paste it into the Cloud Shell, and press enter to run it.

If you prefer to install and use the CLI locally, see Install Azure CLI.

An image gallery is the primary resource used for enabling image sharing. Allowed characters for Gallery name are uppercase or lowercase letters, digits, dots, and periods. The gallery name cannot contain dashes. Gallery names must be unique within your subscription.

Create an image gallery using az sig create. The following example creates a gallery named myGallery in myGalleryRG.

az group create --name myGalleryRG --location WestCentralUS
az sig create --resource-group myGalleryRG --gallery-name myGallery

Create an image definition

Image definitions create a logical grouping for images. They are used to manage information about the image versions that are created within them. Image definition names can be made up of uppercase or lowercase letters, digits, dots, dashes, and periods. For more information about the values you can specify for an image definition, see Image definitions.

Create an initial image definition in the gallery using az sig image-definition create.

az sig image-definition create \
   --resource-group myGalleryRG \
   --gallery-name myGallery \
   --gallery-image-definition myImageDefinition \
   --publisher myPublisher \
   --offer myOffer \
   --sku 16.04-LTS \
   --os-type Linux 

Create an image version

Create versions of the image as needed using az image gallery create-image-version. You will need to pass in the ID of the managed image to use as a baseline for creating the image version. You can use az image list to get information about images that are in a resource group.

Allowed characters for image version are numbers and periods. Numbers must be within the range of a 32-bit integer. Format: MajorVersion.MinorVersion.Patch.

In this example, the version of our image is 1.0.0 and we are going to create 2 replicas in the West Central US region, 1 replica in the South Central US region and 1 replica in the East US 2 region using zone-redundant storage.

az sig image-version create \
   --resource-group myGalleryRG \
   --gallery-name myGallery \
   --gallery-image-definition myImageDefinition \
   --gallery-image-version 1.0.0 \
   --target-regions "WestCentralUS" "SouthCentralUS=1" "EastUS2=1=Standard_ZRS" \
   --replica-count 2 \
   --managed-image "/subscriptions/<subscription ID>/resourceGroups/myResourceGroup/providers/Microsoft.Compute/images/myImage"


You need to wait for the image version to completely finish being built and replicated before you can use the same managed image to create another image version.

You can also store all of your image version replicas in Zone Redundant Storage by adding --storage-account-type standard_zrs when you create the image version.

We recommend that you share with other users at the gallery level. To get the object ID of your gallery, use az sig show.

az sig show \
   --resource-group myGalleryRG \
   --gallery-name myGallery \
   --query id

Use the object ID as a scope, along with an email address and az role assignment create to give a user access to the shared image gallery.

az role assignment create --role "Reader" --assignee <email address> --scope <gallery ID>

Create a VM

Create a VM from the latest image version using az vm create.

az vm create\
   --resource-group myGalleryRG \
   --name myVM \
   --image "/subscriptions/subscription ID where the gallery is located>/resourceGroups/myGalleryRG/providers/Microsoft.Compute/galleries/myGallery/images/myImageDefinition" \

You can also use a specific version by using the image version ID for the --image parameter. For example, to use image version 1.0.0 type: --image "/subscriptions/<subscription ID where the gallery is located>/resourceGroups/myGalleryRG/providers/Microsoft.Compute/galleries/myGallery/images/myImageDefinition/versions/1.0.0".

Using RBAC to share images

You can share images across subscriptions using Role-Based Access Control (RBAC). Any user that has read permissions to an image version, even across subscriptions, will be able to deploy a Virtual Machine using the image version.

For more information about how to share resources using RBAC, see Manage access using RBAC and Azure CLI.

List information

Get the location, status and other information about the available image galleries using az sig list.

az sig list -o table

List the image definitions in a gallery, including information about OS type and status, using az sig image-definition list.

az sig image-definition list --resource-group myGalleryRG --gallery-name myGallery -o table

List the shared image versions in a gallery, using az sig image-version list.

az sig image-version list --resource-group myGalleryRG --gallery-name myGallery --gallery-image-definition myImageDefinition -o table

Get the ID of an image version using az sig image-version show.

az sig image-version show \
   --resource-group myGalleryRG \
   --gallery-name myGallery \
   --gallery-image-definition myImageDefinition \
   --gallery-image-version 1.0.0 \
   --query "id"

Update resources

There are some limitations on what can be updated. The following items can be updated:

Shared image gallery:

  • Description

Image definition:

  • Recommended vCPUs
  • Recommended memory
  • Description
  • End of life date

Image version:

  • Regional replica count
  • Target regions
  • Exclusion from latest
  • End of life date

If you plan on adding replica regions, do not delete the source managed image. The source managed image is needed for replicating the image version to additional regions.

Update the description of a gallery using (az sig update.

az sig update \
   --gallery-name myGallery \
   --resource-group myGalleryRG \
   --set description="My updated description."

Update the description of an image definition using az sig image-definition update.

az sig image-definition update \
   --gallery-name myGallery\
   --resource-group myGalleryRG \
   --gallery-image-definition myImageDefinition \
   --set description="My updated description."

Update an image version to add a region to replicate to using az sig image-version update. This change will take a while as the image gets replicated to the new region.

az sig image-version update \
   --resource-group myGalleryRG \
   --gallery-name myGallery \
   --gallery-image-definition myImageDefinition \
   --gallery-image-version 1.0.0 \
   --add publishingProfile.targetRegions  name=eastus

Delete resources

You have to delete resources in reverse order, by deleting the image version first. After you delete all of the image versions, you can delete the image definition. After you delete all image definitions, you can delete the gallery.

Delete an image version using az sig image-version delete.

az sig image-version delete \
   --resource-group myGalleryRG \
   --gallery-name myGallery \
   --gallery-image-definition myImageDefinition \
   --gallery-image-version 1.0.0 

Delete an image definition using az sig image-definition delete.

az sig image-definition delete \
   --resource-group myGalleryRG \
   --gallery-name myGallery \
   --gallery-image-definition myImageDefinition

Delete an image gallery using az sig delete.

az sig delete \
   --resource-group myGalleryRG \
   --gallery-name myGallery

Next steps

Azure Image Builder (preview) can help automate image version creation, you can even use it to update and create a new image version from an existing image version.

You can also create Shared Image Gallery resources using templates. There are several Azure Quickstart Templates available:

For more information about Shared Image Galleries, see the Overview. If you run into issues, see Troubleshooting shared image galleries.