Find and use Azure Marketplace VM images with Azure PowerShell

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

This article describes how to use Azure PowerShell to find VM images in the Azure Marketplace. You can then specify a Marketplace image and plan information when you create a VM.

You can also browse available images and offers using the Azure Marketplace or the Azure CLI.

Terminology

A Marketplace image in Azure has the following attributes:

  • Publisher: The organization that created the image. Examples: Canonical, MicrosoftWindowsServer
  • Offer: The name of a group of related images created by a publisher. Examples: UbuntuServer, WindowsServer
  • SKU: An instance of an offer, such as a major release of a distribution. Examples: 18.04-LTS, 2019-Datacenter
  • Version: The version number of an image SKU.

These values can be passed individually or as an image URN, combining the values separated by the colon (:). For example: Publisher:Offer:Sku:Version. You can replace the version number in the URN with latest to use the latest version of the image.

If the image publisher provides additional license and purchase terms, then you must accept those before you can use the image. For more information, see Accept purchase plan terms.

List images

You can use PowerShell to narrow down a list of images. Replace the values of the variables to meet your needs.

  1. List the image publishers using Get-AzVMImagePublisher.

    $locName="<location>"
    Get-AzVMImagePublisher -Location $locName | Select PublisherName
    
  2. For a given publisher, list their offers using Get-AzVMImageOffer.

    $pubName="<publisher>"
    Get-AzVMImageOffer -Location $locName -PublisherName $pubName | Select Offer
    
  3. For a given publisher and offer, list the SKUs available using Get-AzVMImageSku.

    $offerName="<offer>"
    Get-AzVMImageSku -Location $locName -PublisherName $pubName -Offer $offerName | Select Skus
    
  4. For a SKU, list the versions of the image using Get-AzVMImage.

    $skuName="<SKU>"
    Get-AzVMImage -Location $locName -PublisherName $pubName -Offer $offerName -Sku $skuName | Select Version
    

    You can also use latest if you want to use the latest image and not a specific older version.

Now you can combine the selected publisher, offer, SKU, and version into a URN (values separated by :). Pass this URN with the -Image parameter when you create a VM with the New-AzVM cmdlet. You can also replace the version number in the URN with latest to get the latest version of the image.

If you deploy a VM with a Resource Manager template, then you'll set the image parameters individually in the imageReference properties. See the template reference.

View purchase plan properties

Some VM images in the Azure Marketplace have additional license and purchase terms that you must accept before you can deploy them programmatically. You'll need to accept the image's terms once per subscription.

To view an image's purchase plan information, run the Get-AzVMImage cmdlet. If the PurchasePlan property in the output is not null, the image has terms you need to accept before programmatic deployment.

For example, the Windows Server 2016 Datacenter image doesn't have additional terms, so the PurchasePlan information is null:

$version = "2016.127.20170406"
Get-AzVMImage -Location $locName -PublisherName $pubName -Offer $offerName -Skus $skuName -Version $version

The output will look similar to the following:

Id               : /Subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/Providers/Microsoft.Compute/Locations/westus/Publishers/MicrosoftWindowsServer/ArtifactTypes/VMImage/Offers/WindowsServer/Skus/2016-Datacenter/Versions/2019.0.20190115
Location         : westus
PublisherName    : MicrosoftWindowsServer
Offer            : WindowsServer
Skus             : 2019-Datacenter
Version          : 2019.0.20190115
FilterExpression :
Name             : 2019.0.20190115
OSDiskImage      : {
                     "operatingSystem": "Windows"
                   }
PurchasePlan     : null
DataDiskImages   : []

The example below shows a similar command for the Data Science Virtual Machine - Windows 2016 image, which has the following PurchasePlan properties: name, product, and publisher. Some images also have a promotion code property. To deploy this image, see the following sections to accept the terms and to enable programmatic deployment.

Get-AzVMImage -Location "westus" -PublisherName "microsoft-ads" -Offer "windows-data-science-vm" -Skus "windows2016" -Version "0.2.02"

The output will look similar to the following:

Id               : /Subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/Providers/Microsoft.Compute/Locations/westus/Publishers/microsoft-ads/ArtifactTypes/VMImage/Offers/windows-data-science-vm/Skus/windows2016/Versions/19.01.14
Location         : westus
PublisherName    : microsoft-ads
Offer            : windows-data-science-vm
Skus             : windows2016
Version          : 19.01.14
FilterExpression :
Name             : 19.01.14
OSDiskImage      : {
                     "operatingSystem": "Windows"
                   }
PurchasePlan     : {
                     "publisher": "microsoft-ads",
                     "name": "windows2016",
                     "product": "windows-data-science-vm"
                   }
DataDiskImages   : []

To view the license terms, use the Get-AzMarketplaceterms cmdlet and pass in the purchase plan parameters. The output provides a link to the terms for the Marketplace image and shows whether you previously accepted the terms. Be sure to use all lowercase letters in the parameter values.

Get-AzMarketplaceterms -Publisher "microsoft-ads" -Product "windows-data-science-vm" -Name "windows2016"

The output will look similar to the following:

Publisher         : microsoft-ads
Product           : windows-data-science-vm
Plan              : windows2016
LicenseTextLink   : https://storelegalterms.blob.core.windows.net/legalterms/3E5ED_legalterms_MICROSOFT%253a2DADS%253a24WINDOWS%253a2DDATA%253a2DSCIENCE%253a2DVM%253a24WINDOWS2016%253a24OC5SKMQOXSED66BBSNTF4XRCS4XLOHP7QMPV54DQU7JCBZWYFP35IDPOWTUKXUC7ZAG7W6ZMDD6NHWNKUIVSYBZUTZ245F44SU5AD7Q.txt
PrivacyPolicyLink : https://www.microsoft.com/EN-US/privacystatement/OnlineServices/Default.aspx
Signature         : 2UMWH6PHSAIM4U22HXPXW25AL2NHUJ7Y7GRV27EBL6SUIDURGMYG6IIDO3P47FFIBBDFHZHSQTR7PNK6VIIRYJRQ3WXSE6BTNUNENXA
Accepted          : False
Signdate          : 1/25/2019 7:43:00 PM

Accept purchase plan terms

Use the Set-AzMarketplaceterms cmdlet to accept or reject the terms. You only need to accept terms once per subscription for the image. Be sure to use all lowercase letters in the parameter values.

$agreementTerms=Get-AzMarketplaceterms -Publisher "microsoft-ads" -Product "windows-data-science-vm" -Name "windows2016"

Set-AzMarketplaceTerms -Publisher "microsoft-ads" -Product "windows-data-science-vm" -Name "windows2016" -Terms $agreementTerms -Accept
Publisher         : microsoft-ads
Product           : windows-data-science-vm
Plan              : windows2016
LicenseTextLink   : https://storelegalterms.blob.core.windows.net/legalterms/3E5ED_legalterms_MICROSOFT%253a2DADS%253a24WINDOWS%253a2DDATA%253a2DSCIENCE%253a2DV
                    M%253a24WINDOWS2016%253a24OC5SKMQOXSED66BBSNTF4XRCS4XLOHP7QMPV54DQU7JCBZWYFP35IDPOWTUKXUC7ZAG7W6ZMDD6NHWNKUIVSYBZUTZ245F44SU5AD7Q.txt
PrivacyPolicyLink : https://www.microsoft.com/EN-US/privacystatement/OnlineServices/Default.aspx
Signature         : XXXXXXK3MNJ5SROEG2BYDA2YGECU33GXTD3UFPLPC4BAVKAUL3PDYL3KBKBLG4ZCDJZVNSA7KJWTGMDSYDD6KRLV3LV274DLBXXXXXX
Accepted          : True
Signdate          : 2/23/2018 7:49:31 PM

Create a new VM from a marketplace image

If you already have the information about what image you want to use, you can pass that information into Set-AzVMSourceImage cmdlet to add image information to the VM configuration. See the next sections for searching and listing the images available in the marketplace.

Some paid images also require that you provide purchase plan information using the Set-AzVMPlan.

...

$vmConfig = New-AzVMConfig -VMName "myVM" -VMSize Standard_D1

# Set the Marketplace image
$offerName = "windows-data-science-vm"
$skuName = "windows2016"
$version = "19.01.14"
$vmConfig = Set-AzVMSourceImage -VM $vmConfig -PublisherName $publisherName -Offer $offerName -Skus $skuName -Version $version

# Set the Marketplace plan information, if needed
$publisherName = "microsoft-ads"
$productName = "windows-data-science-vm"
$planName = "windows2016"
$vmConfig = Set-AzVMPlan -VM $vmConfig -Publisher $publisherName -Product $productName -Name $planName

...

You'll then pass the VM configuration along with the other configuration objects to the New-AzVM cmdlet. For a detailed example of using a VM configuration with PowerShell, see this script.

If you get a message about accepting the terms of the image, see the earlier section Accept purchase plan terms.

Create a new VM from a VHD with purchase plan information

If you have an existing VHD that was created using an Azure Marketplace image, you might need to supply the purchase plan information when you create a new VM from that VHD.

If you still have the original VM, or another VM created from the same image, you can get the plan name, publisher, and product information from it using Get-AzVM. This example gets a VM named myVM in the myResourceGroup resource group and then displays the purchase plan information.

$vm = Get-azvm `
   -ResourceGroupName myResourceGroup `
   -Name myVM
$vm.Plan

If you didn't get the plan information before the original VM was deleted, you can file a support request. They will need the VM name, subscription ID and the time stamp of the delete operation.

To create a VM using a VHD, refer to this article Create a VM from a specialized VHD and add in a line to add the plan information to the VM configuration using Set-AzVMPlan similar to the following:

$vmConfig = Set-AzVMPlan `
   -VM $vmConfig `
   -Publisher "publisherName" `
   -Product "productName" `
   -Name "planName"

Next steps

To create a virtual machine quickly with the New-AzVM cmdlet by using basic image information, see Create a Windows virtual machine with PowerShell.

For more information on using Azure Marketplace images to create custom images in an Azure Compute Gallery (formerly known as Shared Image Gallery), see Supply Azure Marketplace purchase plan information when creating images.