Create a VM from a generalized image version

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

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

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 a VM using az vm create. To use the latest version of the image, set --image to the ID of the image definition.

This example is for creating a Linux VM secured with SSH. For Windows or to secure a Linux VM with a password, remove --generate-ssh-keys to be prompted for a password. If you want to supply a password directly, replace --generate-ssh-keys with --admin-password. Replace resource names as needed in this example.

imgDef="/subscriptions/<subscription ID where the gallery is located>/resourceGroups/myGalleryRG/providers/Microsoft.Compute/galleries/myGallery/images/myImageDefinition"
vmResourceGroup=myResourceGroup
location=eastus
vmName=myVM
adminUsername=azureuser

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

az vm create\
   --resource-group $vmResourceGroup \
   --name $vmName \
   --image $imgDef \
   --admin-username $adminUsername \
   --generate-ssh-keys

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".

RBAC - Shared 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 to the imageID of the image you want to use and you need to make sure it's replicated to the region where you want to create the VM.

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

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

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

az vm create\
   --resource-group $vmResourceGroup \
   --name $vmName \
   --image $imgDef \
   --admin-username $adminUsername \
   --generate-ssh-keys

RBAC - Shared from another tenant

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

You also need the imageID of the image you want to use and you need to make sure it's 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.

In this example, we're showing how to create a VM from a generalized image. If you're using a specialized image, see Create a VM using a specialized image version.

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
az login --tenant $tenant1
az account get-access-token

Create the VM. Replace the information in the example with your own. Before you create the VM, make sure that the image is replicated into the region where you want to create the VM.

imageid="<ID of the image that you want to use>"
resourcegroup="<name for the resource group>"
location="<location where the image is replicated>"
user='<username for the VM>'
name='<name for the VM>'

az group create --location $location --resource-group $resourcegroup
az vm create \
  --resource-group $resourcegroup \
  --name $name \
  --image $imageid \
  --admin-username $user \
  --generate-ssh-keys

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

Follow these instructions to get the list of Community images using CLI:

Step 1:  Show all 'Community images' in a specific location
az sig list-community --location westus2

Step 2: Once you have the public gallery name from Step 1, Get the Image definition (Name) of the image by running the following command
az sig image-definition list-community --public-gallery-name <<public gallery name>> --location westus2

Step 3: Finally, run the following command to list different image versions available for the specific image
az sig image-version list-community --public-gallery-name <<galleryname>> --gallery-image-definition <<image name>> --location westus2

To get the public name of a community gallery from portal. Go to Virtual machines > Create > Azure virtual machine > Image > See all images > Community Images > Public gallery name.

In this example, we're creating a VM from a Linux image and creating SSH keys for authentication.

imgDef="/CommunityGalleries/ContosoImages-1a2b3c4d-1234-abcd-1234-1a2b3c4d5e6f>/Images/myLinuxImage/Versions/latest"
vmResourceGroup=myResourceGroup
location=eastus
vmName=myVM
adminUsername=azureuser

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

az vm create\
   --resource-group $vmResourceGroup \
   --name $vmName \
   --image $imgDef \
   --admin-username $adminUsername \
   --generate-ssh-keys

When using a community image, you'll be prompted to accept the legal terms. The message looks 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 an image shared to your subscription or tenant, you need the unique 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 are 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 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 Generalized. If you want to use an image with the Specialized state, see Create a VM from a specialized image version.

Use the Id from the output, 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 a Linux image that is directly shared to us, and creating SSH keys for authentication.

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

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

az vm create\
   --resource-group $vmResourceGroup \
   --name $vmName \
   --image $imgDef \
   --admin-username $adminUsername \
   --generate-ssh-keys

Next steps