az sig image-version

Manage shared gallery image version with VM.

Commands

az sig image-version create

Create a new image version.

az sig image-version delete

Delete a gallery image version.

az sig image-version list

List gallery image versions in a gallery image definition.

az sig image-version list-community

List VM Image Versions in a gallery community (preview).

az sig image-version list-shared

List VM Image Versions in a gallery shared directly to your subscription or tenant (preview).

az sig image-version show

Retrieves information about a gallery image version.

az sig image-version show-community

Get an image version in a gallery community (preview).

az sig image-version show-shared

Get an image version in a gallery shared directly to your subscription or tenant (preview).

az sig image-version update

Update a share image version.

az sig image-version wait

Wait for image version related operation.

az sig image-version create

Create a new image version.

This operation might take a long time depending on the replicate region number. Use "--no-wait" is advised.

az sig image-version create --gallery-image-definition
                            --gallery-image-version
                            --gallery-name
                            --resource-group
                            [--data-snapshot-luns]
                            [--data-snapshots]
                            [--data-vhds-luns]
                            [--data-vhds-sa]
                            [--data-vhds-uris]
                            [--end-of-life-date]
                            [--exclude-from-latest {false, true}]
                            [--location]
                            [--managed-image]
                            [--no-wait]
                            [--os-snapshot]
                            [--os-vhd-storage-account]
                            [--os-vhd-uri]
                            [--replica-count]
                            [--replication-mode {Full, Shallow}]
                            [--storage-account-type {Premium_LRS, Standard_LRS, Standard_ZRS}]
                            [--subscription]
                            [--tags]
                            [--target-region-encryption]
                            [--target-regions]

Examples

Add a new image version from a virtual machine

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--managed-image /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/virtualMachines/MyVM

Add a new image version from a managed image

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--managed-image /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/images/MyManagedImage

Add a new image version from another image version

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--managed-image /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/galleries/MyGallery/images/MyImageDefinition/versions/1.0.0

Add a new image version from a managed disk

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--os-snapshot /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/disks/MyOSDisk

Add a new image version from a managed disk and add additional data disks

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--os-snapshot /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/disks/MyOSDisk \
--data-snapshots /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/disks/MyDataDisk \
--data-snapshot-luns 0

Add a new image version from a snapshot of an OS disk.

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--os-snapshot /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/snapshots/MyOsDiskSnapshot

Add a new image version from a snapshot of an OS disk and add additional snapshots as data disks

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--os-snapshot /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/snapshots/MyOsDiskSnapshot \
--data-snapshots /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/snapshots/MyDiskSnapshot \
--data-snapshot-luns 0

Add a new image version from a VHD of an OS disk.

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--os-vhd-storage-account /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Storage/storageAccounts/mystorageaccount \
--os-vhd-uri https://mystorageaccount.blob.core.windows.net/container/path_to_vhd_file

Add a new image version from a VHD of an OS disk and add additional VHDs as data disks

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--os-vhd-storage-account /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Storage/storageAccounts/mystorageaccount \
--os-vhd-uri https://mystorageaccount.blob.core.windows.net/container/path_to_vhd_file \
--data-vhds-sa /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Storage/storageAccounts/myotherstorageaccount \
--data-vhds-uris https://myotherstorageaccount.blob.core.windows.net/container/path_to_vhd_file \
--data-vhds-luns 0

You can combine snapshots, managed disks, and VHDs to create a new image version. Add a new image version using a VHD as the OS disk and a managed disk and a snapshot as data disks.

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--os-vhd-storage-account /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Storage/storageAccounts/mystorageaccount \
--os-vhd-uri https://mystorageaccount.blob.core.windows.net/container/path_to_vhd_file \
--data-snapshots /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/disks/MyDataDisk subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/snapshots/MyDiskSnapshot \
--data-snapshot-luns 0 1

Add a new image version and copy it to additional regions. The home location for the source of the image version must be included in the list of target regions. For each additional region, you can specify a different replica count and storage account type. Otherwise, the region will inherit from the global. The default replica count is 1 and the default storage account type is Standard LRS. In this example, eastus2 will have one replica stored on Standard ZRS storage, ukwest will have 3 replicas stored on Standard ZRS storage, southindia will have one replica stored on Standard LRS storage, and brazilsouth will have 2 replicas stored on Standard LRS storage.

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 --replica-count 1 \
--storage-account-type Standard_ZRS --managed-image image-name \
--target-regions eastus2 ukwest=3 southindia=standard_lrs \
brazilsouth=2=standard_lrs

Add a new image version with encryption using a disk encryption set. Encryption is applied to each disk that is a part of the image version.

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--managed-image /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/virtualMachines/MyVM \
--target-regions westus=2=standard eastus \
--target-region-encryption WestUSDiskEncryptionSet1,0,WestUSDiskEncryptionSet2 \
EastUSDiskEncryptionSet1,0,EastUSDiskEncryptionSet2

Add a new image version and don't wait on it. Later you can invoke "az sig image-version wait" command when ready to create a vm from the gallery image version

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--managed-image /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/virtualMachines/MyVM \
--no-wait

Add a new image version but remove it from consideration as latest version in its image definition

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--managed-image /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/virtualMachines/MyVM \
--exclude-from-latest true

Add a new image version and set its end-of-life date. The image version can still be used to create a virtual machine after its end-of-life date.

az sig image-version create --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--managed-image /subscriptions/00000000-0000-0000-0000-00000000xxxx/resourceGroups/imageGroups/providers/Microsoft.Compute/virtualMachines/MyVM \
--end-of-life-date 2024-08-02T00:00:00+00:00

Required Parameters

--gallery-image-definition -i

Gallery image definition.

--gallery-image-version -e

Gallery image version in semantic version pattern. The allowed characters are digit and period. Digits must be within the range of a 32-bit integer, e.g. <MajorVersion>.<MinorVersion>.<Patch>.

--gallery-name -r

Gallery name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--data-snapshot-luns

Logical unit numbers (space-delimited) of data disk snapshots.

--data-snapshots

Names or IDs (space-delimited) of data disk snapshots.

--data-vhds-luns

Logical unit numbers (space-delimited) of source VHD URIs of data disks.

--data-vhds-sa --data-vhds-storage-accounts

Names or IDs (space-delimited) of storage accounts of source VHD URIs of data disks.

--data-vhds-uris

Source VHD URIs (space-delimited) of data disks.

--end-of-life-date

The end of life date, e.g. '2020-12-31'.

--exclude-from-latest

The flag means that if it is set to true, people deploying VMs with version omitted will not use this version.

accepted values: false, true
--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--managed-image

Image name(if in the same resource group) or resource id.

--no-wait

Do not wait for the long-running operation to finish.

--os-snapshot

Name or ID of OS disk snapshot.

--os-vhd-storage-account

Name or ID of storage account of source VHD URI of OS disk.

--os-vhd-uri

Source VHD URI of OS disk.

--replica-count

The default number of replicas to be created per region. To set regional replication counts, use --target-regions.

--replication-mode

Optional parameter which specifies the mode to be used for replication. This property is not updatable.

accepted values: Full, Shallow
--storage-account-type

The default storage account type to be used per region. To set regional storage account types, use --target-regions.

accepted values: Premium_LRS, Standard_LRS, Standard_ZRS
--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--tags

Space-separated tags: key[=value] [key[=value] ...]. Use "" to clear existing tags.

--target-region-encryption

Space-separated list of customer managed keys for encrypting the OS and data disks in the gallery artifact for each region. Format for each region: <os_des>,<lun1>,<lun1_des>,<lun2>,<lun2_des>. Use "null" as a placeholder.

--target-regions

Space-separated list of regions and their replica counts. Use <region>[=<replica count>][=<storage account type>] to optionally set the replica count and/or storage account type for each region. If a replica count is not specified, the default replica count will be used. If a storage account type is not specified, the default storage account type will be used.

az sig image-version delete

Delete a gallery image version.

az sig image-version delete --gallery-image-definition
                            --gallery-image-version
                            --gallery-name
                            --resource-group
                            [--subscription]

Required Parameters

--gallery-image-definition -i

Gallery image definition.

--gallery-image-version -e

Gallery image version in semantic version pattern. The allowed characters are digit and period. Digits must be within the range of a 32-bit integer, e.g. <MajorVersion>.<MinorVersion>.<Patch>.

--gallery-name -r

Gallery name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az sig image-version list

List gallery image versions in a gallery image definition.

az sig image-version list --gallery-image-definition
                          --gallery-name
                          --resource-group
                          [--query-examples]
                          [--subscription]

Required Parameters

--gallery-image-definition -i

Gallery image definition.

--gallery-name -r

Gallery name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--query-examples

Recommend JMESPath string for you. You can copy one of the query and paste it after --query parameter within double quotation marks to see the results. You can add one or more positional keywords so that we can give suggestions based on these key words.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az sig image-version list-community

List VM Image Versions in a gallery community (preview).

List VM Image Versions in a gallery community (private preview feature, please contact community image gallery team by email sigpmdev@microsoft.com to register for preview if you're interested in using this feature).

az sig image-version list-community --gallery-image-definition
                                    --location
                                    --public-gallery-name
                                    [--marker]
                                    [--show-next-marker]

Examples

List an image versions in a gallery community.

az sig image-version list-community --public-gallery-name publicGalleryName \
--gallery-image-definition MyImage --location myLocation

Required Parameters

--gallery-image-definition -i

The name of the community gallery image definition from which the image versions are to be listed.

--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--public-gallery-name

The public name of community gallery.

Optional Parameters

--marker

A string value that identifies the portion of the list of containers to be returned with the next listing operation. The operation returns the NextMarker value within the response body if the listing operation did not return all containers remaining to be listed with the current page. If specified, this generator will begin returning results from the point where the previous generator stopped.

--show-next-marker

Show nextMarker in result when specified.

az sig image-version list-shared

List VM Image Versions in a gallery shared directly to your subscription or tenant (preview).

List VM Image Versions in a gallery shared directly to your subscription or tenant (private preview feature, please contact shared image gallery team by email sigpmdev@microsoft.com to register for preview if you're interested in using this feature).

az sig image-version list-shared [--gallery-image-definition]
                                 [--gallery-unique-name]
                                 [--ids]
                                 [--location]
                                 [--shared-to {tenant}]
                                 [--subscription]

Examples

List image versions in a gallery shared directly to your subscription in the given location and image definition.

az sig image-version list-shared --gallery-unique-name galleryUniqueName \
--gallery-image-definition MyImage --location myLocation

List image versions in a gallery shared directly to your tenant in the given location and image definition.

az sig image-version list-shared --gallery-unique-name galleryUniqueName \
--gallery-image-definition MyImage --location myLocation --shared-to tenant

Optional Parameters

--gallery-image-definition -i

The name of the Shared Gallery Image Definition from which the Image Versions are to be listed.

--gallery-unique-name

The unique name of the Shared Gallery.

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--shared-to

The query parameter to decide what shared galleries to fetch when doing listing operations. If not specified, list by subscription id.

accepted values: tenant
--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az sig image-version show

Retrieves information about a gallery image version.

az sig image-version show --gallery-image-definition
                          --gallery-image-version
                          --gallery-name
                          --resource-group
                          [--expand]
                          [--query-examples]
                          [--subscription]

Required Parameters

--gallery-image-definition -i

Gallery image definition.

--gallery-image-version -e

Gallery image version in semantic version pattern. The allowed characters are digit and period. Digits must be within the range of a 32-bit integer, e.g. <MajorVersion>.<MinorVersion>.<Patch>.

--gallery-name -r

Gallery name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--expand

The expand expression to apply on the operation, e.g. 'ReplicationStatus'.

--query-examples

Recommend JMESPath string for you. You can copy one of the query and paste it after --query parameter within double quotation marks to see the results. You can add one or more positional keywords so that we can give suggestions based on these key words.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az sig image-version show-community

Get an image version in a gallery community (preview).

Get an image version in a gallery community (private preview feature, please contact community image gallery team by email sigpmdev@microsoft.com to register for preview if you're interested in using this feature).

az sig image-version show-community --gallery-image-definition
                                    --gallery-image-version
                                    --location
                                    --public-gallery-name

Examples

Get an image version in a gallery community in the given location.

az sig image-version show-community --public-gallery-name publicGalleryName \
--gallery-image-definition MyImage --gallery-image-version 1.0.0 --location myLocation

Required Parameters

--gallery-image-definition -i

The name of the community gallery image definition from which the image versions are to be listed.

--gallery-image-version -e

The name of the gallery image version to be created. Needs to follow semantic version name pattern: The allowed characters are digit and period. Digits must be within the range of a 32-bit integer. Format: ...

--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--public-gallery-name

The public name of community gallery.

az sig image-version show-shared

Get an image version in a gallery shared directly to your subscription or tenant (preview).

Get an image version in a gallery shared directly to your subscription or tenant (private preview feature, please contact shared image gallery team by email sigpmdev@microsoft.com to register for preview if you're interested in using this feature).

az sig image-version show-shared [--gallery-image-definition]
                                 [--gallery-image-version]
                                 [--gallery-unique-name]
                                 [--ids]
                                 [--location]
                                 [--subscription]

Examples

Get an image version in a gallery shared directly to your subscription or tenant in the given location.

az sig image-version show-shared --gallery-unique-name galleryUniqueName \
--gallery-image-definition MyImage --gallery-image-version 1.0.0 --location myLocation

Optional Parameters

--gallery-image-definition -i

The name of the Shared Gallery Image Definition from which the Image Versions are to be listed.

--gallery-image-version -e

The name of the gallery image version to be created. Needs to follow semantic version name pattern: The allowed characters are digit and period. Digits must be within the range of a 32-bit integer. Format: ...

--gallery-unique-name

The unique name of the Shared Gallery.

--ids

One or more resource IDs (space-delimited). It should be a complete resource ID containing all information of 'Resource Id' arguments. You should provide either --ids or other 'Resource Id' arguments.

--location -l

Location. Values from: az account list-locations. You can configure the default location using az configure --defaults location=<location>.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

az sig image-version update

Update a share image version.

az sig image-version update --gallery-image-definition
                            --gallery-image-version
                            --gallery-name
                            --resource-group
                            [--add]
                            [--force-string]
                            [--no-wait]
                            [--remove]
                            [--replica-count]
                            [--set]
                            [--subscription]
                            [--target-regions]

Examples

Change the replication regions and replica count

az sig image-version update --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--target-regions westcentralus=2 eastus2

Replicate to an additional region. Optional, you can set the replica count for the region.

az sig image-version update --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0 \
--add publishingProfile.targetRegions name=westcentralus \
regionalReplicaCount=3

Change whether an image should be included in consideration for latest version in the image definition. Setting this value to true excludes the image from consideration and setting this value to false includes the image for consideration.

az sig image-version update -g MyResourceGroup --gallery-name MyGallery \
--gallery-image-definition MyImage --gallery-image-version 1.0.0 \
--set publishingProfile.excludeFromLatest=true

Change the end of life date for an image version. The image can still be used to create virtual machines after the end of life date.

az sig image-version update -g MyResourceGroup --gallery-name MyGallery \
--gallery-image-definition MyImage --gallery-image-version 1.0.0 \
--set publishingProfile.endOfLifeDate=2024-08-02T00:00:00+00:00

Required Parameters

--gallery-image-definition -i

Gallery image definition.

--gallery-image-version -e

Gallery image version in semantic version pattern. The allowed characters are digit and period. Digits must be within the range of a 32-bit integer, e.g. <MajorVersion>.<MinorVersion>.<Patch>.

--gallery-name -r

Gallery name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--add

Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>.

--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

--no-wait

Do not wait for the long-running operation to finish.

--remove

Remove a property or an element from a list. Example: --remove property.list OR --remove propertyToRemove.

--replica-count

The default number of replicas to be created per region. To set regional replication counts, use --target-regions.

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--target-regions

Space-separated list of regions and their replica counts. Use <region>[=<replica count>][=<storage account type>] to optionally set the replica count and/or storage account type for each region. If a replica count is not specified, the default replica count will be used. If a storage account type is not specified, the default storage account type will be used.

az sig image-version wait

Wait for image version related operation.

az sig image-version wait --gallery-image-definition
                          --gallery-image-version
                          --gallery-name
                          --resource-group
                          [--created]
                          [--custom]
                          [--deleted]
                          [--exists]
                          [--expand]
                          [--interval]
                          [--subscription]
                          [--timeout]
                          [--updated]

Examples

wait for an image version gets updated

az sig image-version wait --updated --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0

wait for image version related operation. (autogenerated)

az sig image-version wait --created --resource-group MyResourceGroup \
--gallery-name MyGallery --gallery-image-definition MyImage \
--gallery-image-version 1.0.0

Required Parameters

--gallery-image-definition -i

Gallery image definition.

--gallery-image-version -e

Gallery image version in semantic version pattern. The allowed characters are digit and period. Digits must be within the range of a 32-bit integer, e.g. <MajorVersion>.<MinorVersion>.<Patch>.

--gallery-name -r

Gallery name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--created

Wait until created with 'provisioningState' at 'Succeeded'.

--custom

Wait until the condition satisfies a custom JMESPath query. E.g. provisioningState!='InProgress', instanceView.statuses[?code=='PowerState/running'].

--deleted

Wait until deleted.

--exists

Wait until the resource exists.

--expand

The expand expression to apply on the operation.

--interval

Polling interval in seconds.

default value: 30
--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--timeout

Maximum wait in seconds.

default value: 3600
--updated

Wait until updated with provisioningState at 'Succeeded'.