Shared Image Galleries overview
Shared Image Gallery is a service that helps you build structure and organization around your custom managed VM images. Shared Image Galleries provide:
- Managed global replication of images.
- Versioning and grouping of images for easier management.
- Make your images highly available with Zone Redundant Storage (ZRS) accounts in regions that support Availability Zones. ZRS offers better resilience against zonal failures.
- Sharing across subscriptions, and even between tenants, using RBAC.
Using a Shared Image Gallery you can share your images to different users, service principals, or AD groups within your organization. Shared images can be replicated to multiple regions, for quicker scaling of your deployments.
A managed image is a copy of either a full VM (including any attached data disks) or just the OS disk, depending on how you create the image. 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 managed image remains in storage and can be used over and over again to create new VMs.
If you have a large number of managed images that you need to maintain and would like to make them available throughout your company, you can use a Shared Image Gallery as a repository that makes it easy to share your images.
The Shared Image Gallery feature has multiple resource types:
|Managed image||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 within your organization. You can include information like whether the image is Windows or Linux, minimum and maximum memory requirements, and release notes. 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.|
Image definitions are a logical grouping for versions of an image. The image definition holds information about why the image was created, what OS it is for, and 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 version 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 versions that share one or two, but not all three values. For example, here are three image definitions and their values:
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 are other parameters that can be set on your image definition so that you can more easily track your resources:
- Operating system state - You can set the OS state to generalized or specialized, but only generalized is currently supported. Images must be created from VMs that have been generalized using Sysprep for Windows or
waagent -deprovisionfor Linux.
- Operating system - can be either Windows or Linux.
- 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 pre-installed.
- 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 - attach an end-of-life date to your image definition in order to be able to use automation to delete old image definitions.
- 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.
Source regions are listed in the table below. All public regions can be target regions, but to replicate to Australia Central and Australia Central 2 you need to have your subscription whitelisted. To request whitelisting, go to: https://www.microsoft.com/en-au/central-regions-eligibility/
|Australia Central||Central US EUAP||Korea Central||UK South 2|
|Australia Central 2||East Asia||Korea South||UK West|
|Australia East||East US||North Central US||West Central US|
|Australia Southeast||East US 2||North Europe||West Europe|
|Brazil South||East US 2 EUAP||South Central US||West India|
|Canada Central||France Central||South India||West US|
|Canada East||France South||Southeast Asia||West US|
|Central India||Japan East||UK North||West US 2|
|Central US||Japan West||UK South|
There are limits, per subscription, for deploying resources using Shared Image Galleries:
- 100 shared image galleries, per subscription, per region
- 1,000 image definitions, per subscription, per region
- 10,000 image versions, per subscription, per region
For more information, see Check resource usage against limits for examples on how to check your current usage.
Shared Image Gallery allows you to specify the number of replicas you want Azure to keep of the images. This helps in multi-VM deployment scenarios as the VM deployments can be spread to different replicas reducing the chance of instance creation processing being throttled due to overloading of a single replica.
Shared Image Gallery also allows you to replicate your images to other Azure regions automatically. Each Shared Image version can be replicated to different regions depending on what makes sense for your organization. One example is to always replicate the latest image in multi-regions while all older versions are only available in 1 region. This can help save on storage costs for Shared Image versions.
The regions a Shared Image version is replicated to can be updated after creation time. The time it takes to replicate to different regions depends on the amount of data being copied and the number of regions the version is replicated to. This can take a few hours in some cases. While the replication is happening, you can view the status of replication per region. Once the image replication is complete in a region, you can then deploy a VM or scale-set using that image version in the region.
As the Shared Image Gallery, Shared Image and Shared Image version are all resources, they can be shared using the built-in native Azure RBAC controls. Using RBAC you can share these resources to other users, service principals, and groups. You can even share access to individuals outside of the tenant they were created within. Once a user has access to the Shared Image version, they can deploy a VM or a Virtual Machine Scale Set. Here is the sharing matrix that helps understand what the user gets access to:
|Shared with User||Shared Image Gallery||Shared Image||Shared Image version|
|Shared Image Gallery||Yes||Yes||Yes|
|Shared Image version||No||No||Yes|
We recommend sharing at the Gallery level for the best experience. For more information about RBAC, see Manage access to Azure resources using RBAC.
Images can also be shared, at scale, across tenants using a multi-tenant app registration. For more information about sharing images across tenants, see Share gallery VM images across Azure tenants.
There is no extra charge for using the Shared Image Gallery service. You will be charged for the following resources:
- Storage costs of storing the Shared Image versions. Cost depends on the number of replicas of the image version and the number of regions the version is replicated to. For example, if you have 2 images and both are replicated to 3 regions, then you will be changed for 6 managed disks based on their size. For more information, see Managed Disks pricing.
- Network egress charges for replication of the first image version from the source region to the replicated regions. Subsequent replicas are handled within the region, so there are no additional charges.
Once created, you can make some changes to the image gallery resources. These are limited to:
Shared image gallery:
- Recommended vCPUs
- Recommended memory
- End of life date
- Regional replica count
- Target regions
- Exclusion from latest
- End of life date
The following SDKs support creating Shared Image Galleries:
You can create Shared Image Gallery resource using templates. There are several Azure Quickstart Templates available:
- Create a Shared Image Gallery
- Create an Image Definition in a Shared Image Gallery
- Create an Image Version in a Shared Image Gallery
- Create a VM from Image Version
Frequently asked questions
Q. How can I list all the Shared Image Gallery resources across subscriptions?
A. In order to list all the Shared Image Gallery resources across subscriptions that you have access to on the Azure portal, follow the steps below:
Open the Azure portal.
Go to All Resources.
Select all the subscriptions under which you’d like to list all the resources.
Look for resources of type Private gallery.
To see the image definitions and image versions, you should also select Show hidden types.
To list all the Shared Image 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
Q. Can I move my existing image to the shared image gallery?
A. Yes. There are 3 scenarios based on the types of images you may have.
Scenario 1: If you have a managed image, then you can create an image definition and image version from it.
Scenario 2: If you have an unmanaged generalized image, you can create a managed image from it, and then create an image definition and image version from it.
Scenario 3: If you have a VHD in your local file system, then you need to upload the VHD, create a managed image, then you can create and image definition and image version from it.
- If the VHD is of a Windows VM, see Upload a generalized VHD.
- If the VHD is for a Linux VM, see Upload a VHD
Q. Can I create an image version from a specialized disk?
A. No, we do not currently support specialized disks as images. If you have a specialized disk, you need to create a VM from the VHD by attaching the specialized disk to a new VM. Once you have a running VM, you need to follow the instructions to create a managed image from the Windows VM or Linux VM. Once you have a generalized managed image, you can start the process to create a shared image description and image version.
Q. Once created, can I move the Shared Image Gallery resource to a different subscription?
A. No, you cannot move the shared image gallery resource to a different subscription. However, you will be able to replicate the image versions in the gallery to other regions as required.
Q. Can I replicate my image versions across clouds – Azure China 21Vianet, Azure Germany and Azure Government Cloud?
A. No, you cannot replicate image versions across clouds.
Q. Can I replicate my image versions across subscriptions?
A. No, you may replicate the image versions across regions in a subscription and use it in other subscriptions through RBAC.
Q. Can I share image versions across Azure AD tenants?
Q. How long does it take to replicate image versions across the target regions?
A. The image version replication time is entirely dependent on the size of the image and the number of regions it is being replicated to. However, as a best practice, it is recommended that you keep the image small, and the source and target regions close for best results. You can check the status of the replication using the -ReplicationStatus flag.
Q. What is the difference between source region and target region?
A. Source region is the region in which your image version will be created, and target regions are the regions in which a copy of your image version will be stored. For each image version, you can only have one source region. Also, make sure that you pass the source region location as one of the target regions when you create an image version.
Q. How do I specify the source region while creating the image version?
A. While creating an image version, you can use the --location tag in CLI and the -Location tag in PowerShell to specify the source region. Please ensure the managed image that you are using as the base image to create the image version is in the same location as the location in which you intend to create the image version. Also, make sure that you pass the source region location as one of the target regions when you create an image version.
Q. How do I specify the number of image version replicas to be created in each region?
A. There are two ways you can specify the number of image version replicas to be created in each region:
- The regional replica count which specifies the number of replicas you want to create per region.
- The common replica count which is the default per region count in case regional replica count is not specified.
To specify the regional replica count, pass the location along with the number of replicas you want to create in that region: “South Central US=2”.
If regional replica count is not specified with each location, then the default number of replicas will be the common replica count that you specified.
To specify the common replica count in CLI, use the --replica-count argument in the
az sig image-version create command.
Q. Can I create the shared image gallery in a different location than the one where I want to create the image definition and image version?
A. Yes, it is possible. But, as a best practice, we encourage you to keep the resource group, shared image gallery, image definition, and image version in the same location.
Q. What are the charges for using the Shared Image Gallery?
A. There are no charges for using the Shared Image Gallery service, except the storage charges for storing the image versions and network egress charges for replicating the image versions from source region to target regions.
Q. What API version should I use to create Shared Image Gallery, Image Definition, Image Version, and VM/VMSS out of the Image Version?
A. For VM and Virtual Machine Scale Set deployments using an image version, we recommend you use API version 2018-04-01 or higher. To work with shared image galleries, image definitions, and image versions, we recommend you use API version 2018-06-01. Zone Redundant Storage (ZRS) requires version 2019-03-01 or later.
Learn how to deploy shared images.
Send feedback about: