Edit

Store and share images in an Azure Compute Gallery

  • Article

Applies to: ✔️ Linux VMs ✔️ Windows VMs ✔️ Flexible scale sets ✔️ Uniform scale sets

An image is a copy of either a full VM (including any attached data disks) or just the OS disk, depending on how it's created. When you create a VM from the image, a copy of the VHDs in the image are used to create the disks for the new VM. The image remains in storage and can be used over and over again to create new VMs.

If you have a large number of images that you need to maintain, and would like to make them available throughout your company, you can use an Azure Compute Gallery as a repository.

When you use a gallery to store images, multiple resource types are created:

Resource Description
Image source This is a resource that can be used to create an image version in a gallery. An image source can be an existing Azure VM that is either generalized or specialized, a managed image, a snapshot, a VHD or an image version in another gallery.
Gallery Like the Azure Marketplace, a gallery is a repository for managing and sharing images and other resources, but you control who has access.
Image definition Image definitions are created within a gallery and they carry information about the image and any requirements for using it to create VMs. This includes whether the image is Windows or Linux, release notes, and minimum and maximum memory requirements. It's 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.

Graphic showing how you can have multiple versions of an image in your gallery

Image definitions

Image definitions are a logical grouping for versions of an image. The image definition holds information about why the image was created and also contains Image metadata such as, what OS it is for, features it supports and other information about using the image. An image definition is like a plan for all of the details around creating a specific image. You don't deploy a VM from an image definition, but from the image versions created from the definition.

There are three parameters for each image definition that are used in combination - Publisher, Offer and SKU. These are used to find a specific image definition. You can have image definitions that share one or two, but not all three values. For example, here are three image definitions and their values:

Image Definition Publisher Offer Sku
myImage1 Contoso Finance Backend
myImage2 Contoso Finance Frontend
myImage3 Testing Finance Frontend

All three of these have unique sets of values. The format is similar to how you can currently specify publisher, offer, and SKU for Azure Marketplace images in Azure PowerShell to get the latest version of a Marketplace image. Each image definition needs to have a unique set of these values.

The following parameters determine which types of image versions they can contain:

  • Operating system state - You can set the OS state to generalized or specialized. This field is required.
  • Operating system - can be either Windows or Linux. This field is required.
  • Hyper-V generation - specify whether the image was created from a generation 1 or generation 2 Hyper-V VHD. Default is generation 1.

Image definitions contain metadata for the image to allow grouping of images that support the same features, plan, OS State, OS type and others. The following are other parameters that can be set on your image definition so that you can more easily track your resources:

  • Description - use description to give more detailed information on why the image definition exists. For example, you might have an image definition for your front-end server that has the application preinstalled.

  • EULA - can be used to point to an end-user license agreement specific to the image definition.

  • Privacy Statement and Release notes - store release notes and privacy statements in Azure storage and provide a URI for accessing them as part of the image definition.

  • End-of-life date - establish a default date after which the image shouldn't be used, for all image versions in the image definition. End-of-life dates are informational; users will still be able to create VMs from images and versions past the end-of-life date.

  • Tag - you can add tags when you create your image definition. For more information about tags, see Using tags to organize your resources

  • Minimum and maximum vCPU and memory recommendations - if your image has vCPU and memory recommendations, you can attach that information to your image definition.

  • Disallowed disk types - you can provide information about the storage needs for your VM. For example, if the image isn't suited for standard HDD disks, you add them to the disallow list.

  • Purchase plan information for Marketplace images - -PurchasePlanPublisher, -PurchasePlanName, and -PurchasePlanProduct. For more information about purchase plan information, see Find images in the Azure Marketplace and Supply Azure Marketplace purchase plan information when creating images.

  • Architecture

  • Features allow you to specify additional features and SecurityType(s) that are supported on the image, based on the type of gallery:

    Features Accepted Values Definition Supported in
    IsHibernateSupported True, False Create VMs with support for hibernation. Private, direct shared, community
    IsAcceleratedNetworkSupported True, False Create VMs with accelerated networking enabled. When set to True on Image definition, capturing VMs that don't support accelerated networking is not supported. Private, direct shared, community
    DiskControllerType ["SCSI", "NVMe"], ["SCSI"] Set this to use either SCSI or NVMe disk type. NVMe VMs and disks can only be captured in image definitions that are tagged to be supporting NVMe. Private, direct shared, community

    When you specify a SecurityType using the features parameter, it limits the security features that are enabled on the VM. Some types limited, based on the type of gallery that they are stored in:

    SecurityType Definition Supported in
    ConfidentialVMSupported It's a generic Gen2 image that does not contain VMGS blob. Gen2 VM or Confidential VM can be created from this image type Private, Direct shared, Community
    Confidential VM Only Confidential VMs can be created from this image type Private
    TrustedLaunchSupported It's a generic Gen2 image that does not contain the VMGS blob. Gen2 VM or TrustedLaunch VM can be created from this image type. Private, direct shared, community
    TrustedLaunch Only TrustedLaunch VM can be created from this image type Private
    TrustedLaunchAndConfidentialVmSupported It's a generic Gen2 image that does not contain the VMGS blob. Gen2 VM, TrustedLaunch VM, or a ConfidentialVM can be created from this image type. Private, direct shared, community

    For more information, see the CLI examples for adding image definition features and SecurityType or the PowerShell examples.

    **ConfidentialVM is only supported in the regions where it's available, You can find the supported regions here.

Image versions

An image version is what you use to create a VM. You can have multiple versions of an image as needed for your environment. 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.

The properties of an image version are:

  • Version number. This is used as the name of the image version. It is always in the format: MajorVersion.MinorVersion.Patch. When you specify to use latest when creating a VM, the latest image is chosen based on the highest MajorVersion, then MinorVersion, then Patch.
  • Source. The source can be a VM, managed disk, snapshot, managed image, or another image version.
  • End of life date. Indicate the end-of-life date for the image version. End-of-life dates are informational; users will still be able to create VMs from versions past the end-of-life date.

Generalized and specialized images

There are two operating system states supported by Azure Compute Gallery. Typically images require that the VM used to create the image has been generalized before taking the image. Generalizing is a process that removes machine and user specific information from the VM. For Linux, you can use waagent -deprovision or -deprovision+user parameters. For Windows, the Sysprep tool is used.

Specialized VMs haven't been through a process to remove machine specific information and accounts. Also, VMs created from specialized images don't have an osProfile associated with them. This means that specialized images will have some limitations in addition to some benefits.

  • VMs and scale sets created from specialized images can be up and running quicker. Because they're created from a source that has already been through first boot, VMs created from these images boot faster.
  • Accounts that could be used to log into the VM can also be used on any VM created using the specialized image that is created from that VM.
  • VMs will have the Computer name of the VM the image was taken from. You should change the computer name to avoid collisions.
  • The osProfile is how some sensitive information is passed to the VM, using secrets. This may cause issues using KeyVault, WinRM and other functionality that uses secrets in the osProfile. In some cases, you can use managed service identities (MSI) to work around these limitations.

Updating resources

Once created, you can make some changes to the gallery resources. These are limited to:

Azure Compute Gallery:

  • Description

Image definition:

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

Image version:

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

Sharing

There are three main ways to share images an Azure Compute Gallery, depending on who you want to share with:

Sharing with: People Groups Service Principal All users in a specific subscription (or) tenant Publicly with all users in Azure
RBAC Sharing Yes Yes Yes No No
RBAC + Direct shared gallery Yes Yes Yes Yes No
RBAC + Community gallery Yes Yes Yes No Yes

What RBAC Permissions are required to create an ACG Image:

ACG images can be created by users from various sources, including virtual machines, disks/snapshots, and VHDs. The section outlines the various user permissions necessary for creating an Azure Compute Gallery image. Identifies without the necessary permissions will not be able to create ACG images.

Source type Permissions Required
Virtual machine Write
Disk/snapshot Write
VHD Write (listKeys)
Managed Image Read
Gallery Image Read

Refer to our documentation for additional information regarding Azure built-in roles, for granting RBAC permissions

Shallow replication

When you create an image version, you can set the replication mode to shallow for development and test. Shallow replication skips copying the image, so the image version is ready faster. But, it also means you can't deploy a large number of VMs from that image version. This is similar to the way that the older managed images worked.

Shallow replication can also be useful if you have large images (up to 32 TB) that aren't frequently deployed. Because the source image isn't copied, larger disks can be used. But, they also can't be used for deploying large numbers of VMs concurrently.

To set an image for shallow replication, use --replication-mode Shallow with the Azure CLI.

SDK support

The following SDKs support creating Azure Compute Galleries:

Templates

You can create Azure Compute Gallery resource using templates. There are several quickstart templates available:

Frequently asked questions

To list all the Azure Compute Gallery resources across subscriptions that you have access to on the Azure portal, follow the steps below:

  1. Open the Azure portal.
  2. Scroll down the page and select All resources.
  3. Select all the subscriptions under which you'd like to list all the resources.
  4. Look for resources of the Azure Compute Gallery type.

To list all the Azure Compute Gallery resources, across subscriptions that you have permissions to, use the following command in the Azure CLI:

   az account list -otsv --query "[].id" | xargs -n 1 az sig list --subscription