Create a windows Virtual Machine using Azure Image Builder template

You decide to test Azure Image Builder to discover if it can meet the needs of the Contoso IT operations staff. You plan to create a Windows VM by using Azure Image Builder and a sample .json template that you have downloaded from the GitHub library. But first, you must register Azure Image Builder with your Azure subscription.


In this preview, you can't use the Azure portal to work with Azure Image Builder.

Register Azure Image Builder

To use Azure Image Builder in public preview, you must register the features in your Azure subscription. The following steps provide guidance on this process.

  1. To register Azure Image Builder, run the following Azure CLI command:

    az feature register --namespace Microsoft.VirtualMachineImages --name VirtualMachineTemplatePreview`
  2. Check the status of the feature registration using the following command:

    az feature show --namespace Microsoft.VirtualMachineImages --name VirtualMachineTemplatePreview | grep state
  3. Check your registration status using the following command:

    az provider show -n Microsoft.VirtualMachineImages | grep registrationState
    az provider show -n Microsoft.KeyVault | grep registrationState
    az provider show -n Microsoft.Compute | grep registrationState
    az provider show -n Microsoft.Storage | grep registrationState
  4. If any provider doesn't display Registered, run the following command:

    az provider register -n Microsoft.VirtualMachineImages
    az provider register -n Microsoft.Compute
    az provider register -n Microsoft.KeyVault
    az provider register -n Microsoft.Storage

When all is ready, all providers should display as Registered.

A screenshot that displays the registration state as registered for all four required components in Azure Image Builder.

Create an image

The next steps are to create an image, and then create the VM from the image. To create an image, perform the following procedure:

  1. Set variables that you'll use during the build process:

    # Resource group name
    # Region location
    # Name for the image
    # Run output name
    # name of the image to be created
    # Create a variable for your subscription ID
    subscriptionID=<Your subscription ID>


    You can determine your subscription ID using the az account show | grep id command.

  2. Create a resource group: az group create -n $imageResourceGroup -l $location.


    You can, of course, use an existing resource group if you prefer. However, it's easier to manage (from a cleanup perspective) if you create one for this specific purpose.

  3. Create a user-assigned identity and set permissions on the resource group:

     # create user assigned identity for image builder to access the storage account where the script is located
     identityName=aibBuiUserId$(date +'%s')
     az identity create -g $imageResourceGroup -n $identityName
     # get identity id
     imgBuilderCliId=$(az identity show -g $imageResourceGroup -n $identityName | grep "clientId" | cut -c16- | tr -d '",')
     # get the user identity URI, needed for the template
     # download preconfigured role definition example
     curl -o aibRoleImageCreation.json
     imageRoleDefName="Azure Image Builder Image Def"$(date +'%s')
     # update the definition
     sed -i -e "s/<subscriptionID>/$subscriptionID/g" aibRoleImageCreation.json
     sed -i -e "s/<rgName>/$imageResourceGroup/g" aibRoleImageCreation.json
     sed -i -e "s/Azure Image Builder Service Image Creation Role/$imageRoleDefName/g" aibRoleImageCreation.json
     # create role definitions
     az role definition create --role-definition ./aibRoleImageCreation.json
     # grant role definition to the user assigned identity
     az role assignment create \
     --assignee $imgBuilderCliId \
     --role $imageRoleDefName \
     --scope /subscriptions/$subscriptionID/resourceGroups/$imageResourceGroup
  4. Download the image configuration template:

    curl -o helloImageTemplateWin.json
    sed -i -e "s/<subscriptionID>/$subscriptionID/g" helloImageTemplateWin.json
    sed -i -e "s/<rgName>/$imageResourceGroup/g" helloImageTemplateWin.json
    sed -i -e "s/<region>/$location/g" helloImageTemplateWin.json
    sed -i -e "s/<imageName>/$imageName/g" helloImageTemplateWin.json
    sed -i -e "s/<runOutputName>/$runOutputName/g" helloImageTemplateWin.json
    sed -i -e "s%<imgBuilderId>%$imgBuilderId%g" helloImageTemplateWin.json
  5. Create the image by submitting the image configuration to the VM Image Builder service:

    az resource create \
     --resource-group $imageResourceGroup \
     --properties @helloImageTemplateWin.json \
     --is-full-object \
     --resource-type Microsoft.VirtualMachineImages/imageTemplates \
     -n helloImageTemplateWin01


    You can edit the code using a text editor.

    After the image creation completes, Azure Image Builder displays a success message in the console, and creates an Image Builder Configuration Template in the $imageResourceGroup. You can review this resource in the resource group in the Azure portal if you enable Show hidden types. In the background, Azure Image Builder also creates a staging resource group in your subscription. This resource group is used for the image build. It will be in this format: IT_<DestinationResourceGroup>_<TemplateName>_<GUID>.

  6. Start the image build:

     az resource invoke-action \
      --resource-group $imageResourceGroup \
      --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
      -n helloImageTemplateWin01 \
      --action Run


The image build can take up to 15 minutes.

Build a VM

The final step is to create a VM from the newly built image. To build the VM, run the following command in Azure CLI:

az vm create \
  --resource-group $imageResourceGroup \
  --name aibImgWinVm00 \
  --admin-username azureuser \
  --admin-password <password> \
  --image $imageName \
  --location $location


Change the administrator name in the preceding code to suit your requirements.

After you have built your VM, you should verify the customization. You do this by opening a Remote Desktop Protocol (RDP) connection to the VM, signing in with the defined username and password, and verifying the presence of the following objects:

  • buildActions
  • buildArtifacts


When you have finished, clean up all the resources that you created during the build process. For more details, refer to Clean up.

Additional reading

You can learn more by reviewing the following documents: