Create and use shared images for virtual machine scale sets with the Azure CLI 2.0

When you create a scale set, you specify an image to be used when the VM instances are deployed. Shared Image Galleries greatly 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.


This article walks through the process of using a generalized managed image. It is not supported to create a scale set from a specialized VM image.

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 scale set from the custom VM image

Create a scale set with az vmss create. Instead of a platform image, such as UbuntuLTS or CentOS, specify the name of your custom VM image. The following example creates a scale set named myScaleSet that uses the custom image named myImage from the previous step:

az vmss create \
  -g myGalleryRG \
  -n myScaleSet \
  --image "/subscriptions/<subscription ID>/resourceGroups/myGalleryRG/providers/Microsoft.Compute/galleries/myGallery/images/myImageDefinition/versions/1.0.0" \
  --admin-username azureuser \

It takes a few minutes to create and configure all the scale set resources and VMs.

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"

Clean up resources

To remove your scale set and additional resources, delete the resource group and all its resources with az group delete. The --no-wait parameter returns control to the prompt without waiting for the operation to complete. The --yes parameter confirms that you wish to delete the resources without an additional prompt to do so.

az group delete --name myResourceGroup --no-wait --yes

Next steps

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

If you run into any issues, you can troubleshoot shared image galleries.