Create a VM using a specialized image version

Applies to: ✔️ Linux VMs ✔️ Windows VMs

Create a VM from a specialized image version stored in an Azure Compute Gallery (formerly known as Shared Image Gallery). If you want to create a VM using a generalized image version, see Create a VM from a generalized image version.

This article shows how to create a VM from a specialized image:

Important

When you create a new VM from a specialized image, the new VM retains the computer name of the original VM. Other computer-specific information, like the CMID, is also kept. This duplicate information can cause issues. When copying a VM, be aware of what types of computer-specific information your applications rely on.

Create a VM from an internal gallery.

List the image definitions in a gallery using az sig image-definition list to see the name and ID of the definitions.

resourceGroup=myGalleryRG
gallery=myGallery
az sig image-definition list \
   --resource-group $resourceGroup \
   --gallery-name $gallery \
   --query "[].[name, id]" \
   --output tsv

Create the VM using az vm create using the --specialized parameter to indicate that the image is a specialized image.

Use the image definition ID for --image to create the VM from the latest version of the image that is available. You can also create the VM from a specific version by supplying the image version ID for --image.

In this example, we're creating a VM from the latest version of the myImageDefinition image.

az group create --name myResourceGroup --location eastus
az vm create --resource-group myResourceGroup \
    --name myVM \
    --image "/subscriptions/<Subscription ID>/resourceGroups/myGalleryRG/providers/Microsoft.Compute/galleries/myGallery/images/myImageDefinition" \
    --specialized

RBAC - within your organization

If the subscription where the gallery resides is within the same tenant, images shared through RBAC can be used to create VMs using the CLI and PowerShell.

You'll need the imageID of the image you want to use and make sure the image is replicated to the region where you want to create the VM.


image="/subscriptions/<Subscription ID>/resourceGroups/myGalleryRG/providers/Microsoft.Compute/galleries/myGallery/images/myImageDefinition"
vmResourceGroup='myResourceGroup'
location='westus'
vmName='myVM'

az group create --name $vmResourceGroup --location $location

az vm create\
   --resource-group $vmResourceGroup \
   --name $vmName \
   --image $image \
   --specialized

RBAC - from another tenant or organization

If the image you want to use is stored in a gallery that isn't in the same tenant (directory) then you will need to sign in to each tenant to verify you have access.

You'll need the imageID of the image you want to use and make sure the image is replicated to the region where you want to create the VM. You'll also need the tenantID for the source gallery and the tenantID for where you want to create the VM.

You need to sign in to the tenant where the image is stored, get an access token, then sign into the tenant where you want to create the VM. This is how Azure authenticates that you have access to the image.

tenant1='<ID for tenant 1>'
tenant2='<ID for tenant 2>'

az account clear
az login --tenant $tenant1
az account get-access-token 
az login --tenant $tenant2
az account get-access-token

Create the VM using az vm create using the --specialized parameter to indicate that the image is a specialized image.


imageid=""/subscriptions/<Subscription ID>/resourceGroups/myGalleryRG/providers/Microsoft.Compute/galleries/myGallery/images/myImageDefinition""
resourcegroup="myResourceGroup"
location="West US 3"
name='myVM'

az group create --name $resourcegroup --location $location
az vm create --resource-group $resourcegroup \
    --name $name \
    --image $image \
    --specialized

Important

Microsoft does not provide support for images in the community gallery.

Reporting issues with a community image

Using community-submitted virtual machine images has several risks. Images could contain malware, security vulnerabilities, or violate someone's intellectual property. To help create a secure and reliable experience for the community, you can report images when you see these issues.

The easiest way to report issues with a community gallery is to use the portal, which will pre-fill information for the report:

  • For issues with links or other information in the fields of an image definition, select Report community image.
  • If an image version contains malicious code or there are other issues with a specific version of an image, select Report under the Report version column in the table of image versions.

You can also use the following links to report issues, but the forms won't be pre-filled:

To create a VM using an image shared to a community gallery, use the unique ID of the image for the --image, which will be in the following format:

/CommunityGalleries/<community gallery name, like: ContosoImages-1a2b3c4d-1234-abcd-1234-1a2b3c4d5e6f>/Images/<image name>/Versions/latest

As an end user, to get the public name of a community gallery, you need to use the portal. Go to Virtual machines > Create > Azure virtual machine > Image > See all images > Community Images > Public gallery name.

List all of the image definitions that are available in a community gallery using az sig image-definition list-community. In this example, we list all of the images in the ContosoImage gallery in West US and by name, the unique ID that is needed to create a VM, OS and OS state.

 az sig image-definition list-community \
   --public-gallery-name "ContosoImages-1a2b3c4d-1234-abcd-1234-1a2b3c4d5e6f" \
   --location westus \
   --query [*]."{Name:name,ID:uniqueId,OS:osType,State:osState}" -o table

To create a VM from a generalized image in a community gallery, see Create a VM from a generalized image version.

Create the VM using az vm create using the --specialized parameter to indicate that the image is a specialized image.

In this example, we're creating a VM from the latest version of the myImageDefinition image.

az group create --name myResourceGroup --location eastus
az vm create --resource-group myResourceGroup \
    --name myVM \
    --image "/CommunityGalleries/ContosoImages-f61bb1d9-3c5a-4ad2-99b5-744030225de6/Images/LinuxSpecializedVersions/latest" \
    --specialized

When using a community image, you'll be prompted to accept the legal terms. The message will look like this:

To create the VM from community gallery image, you must accept the license agreement and privacy statement: http://contoso.com. (If you want to accept the legal terms by default, please use the option '--accept-term' when creating VM/VMSS) (Y/n): 

Important

Azure Compute Gallery – direct shared gallery is currently in PREVIEW and subject to the Preview Terms for Azure Compute Gallery.

To publish images to a direct shared gallery during the preview, you need to register at https://aka.ms/directsharedgallery-preview. Creating VMs from a direct shared gallery is open to all Azure users.

During the preview, you need to create a new gallery, with the property sharingProfile.permissions set to Groups. When using the CLI to create a gallery, use the --permissions groups parameter. You can't use an existing gallery, the property can't currently be updated.

To create a VM using the latest version of an image shared to your subscription or tenant, you need the ID of the image in the following format:

/SharedGalleries/<uniqueID>/Images/<image name>/Versions/latest

To find the uniqueID of a gallery that is shared with you, use az sig list-shared. In this example, we're looking for galleries in the West US region.

region=westus
az sig list-shared --location $region --query "[].name" -o tsv

Use the gallery name to find all of the images that are available. In this example, we list all of the images in West US and by name, the unique ID that is needed to create a VM, OS and OS state.

galleryName="1a2b3c4d-1234-abcd-1234-1a2b3c4d5e6f-myDirectShared"
 az sig image-definition list-shared \
   --gallery-unique-name $galleryName \
   --location $region \
   --query [*]."{Name:name,ID:uniqueId,OS:osType,State:osState}" -o table

Make sure the state of the image is Specialized. If you want to use an image with the Generalized state, see Create a VM from a generalized image version.

Create the VM using az vm create using the --specialized parameter to indicate that the image is a specialized image.

Use the Id, appended with /Versions/latest to use the latest version, as the value for `--image`` to create a VM.

In this example, we're creating a VM from the latest version of the myImageDefinition image.

imgDef="/SharedGalleries/1a2b3c4d-1234-abcd-1234-1a2b3c4d5e6f-MYDIRECTSHARED/Images/myDirectDefinition/Versions/latest"
vmResourceGroup=myResourceGroup
location=westus
vmName=myVM

az group create --name $vmResourceGroup --location $location

az vm create\
   --resource-group $vmResourceGroup \
   --name $vmName \
   --image $imgDef \
   --specialized

Next steps