Edit

How to enable automatic image creation with Azure Image Builder triggers

You can use triggers in Azure Image Builder (AIB) to enable automatic image creation when certain criteria are met in your build pipeline.

Important

There's a limit of 100 triggers per region per subscription.

Note

To prevent unnecessary build failures, automatic image creation through triggers is deactivated if the image template build fails multiple times consecutively (either manually or automatically triggered). You can still manually build the image template. Once a manual build succeeds, the automatic triggers are reactivated.

Prerequisites

Before setting up your first trigger, ensure you're using Azure Image Builder API version 2022-07-01 or later.

How to set up a trigger in Azure Image Builder

Register the providers

To use VM Image Builder with triggers, register the following providers. Check your registration by running these commands:

az provider show -n Microsoft.VirtualMachineImages -o json | grep registrationState
az provider show -n Microsoft.KeyVault -o json | grep registrationState
az provider show -n Microsoft.Compute -o json | grep registrationState
az provider show -n Microsoft.Storage -o json | grep registrationState
az provider show -n Microsoft.Network -o json | grep registrationState
az provider show -n Microsoft.ContainerInstance -o json | grep registrationState

If the output doesn't say registered, run the following commands:

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

Register the auto image build triggers feature:

az feature register --namespace Microsoft.VirtualMachineImages --name Triggers

Set variables

First, set some variables that you repeatedly use in commands.

# Resource group name - ibTriggersTestRG in this example
resourceGroupName=ibTriggersRG
# Datacenter location - Central US in this example
location=centralus
# Additional region to replicate the image to - West US in this example
additionalregion=westus
# Name of the Azure Compute Gallery - ibTriggersGallery in this example
acgName=ibTriggersGallery
# Name of the image definition to be created - ibTriggersImageDef in this example
imageDefName=ibTriggersImageDef
# Name of the Trigger to be created - ibTrigger in this example
ibTriggerName=ibTrigger
# Name of the image template to be created - ibTriggersImageTemplate in this example
imageTemplateName=ibTriggersImageTemplate
# Reference name in the image distribution metadata
runOutputName=ibTriggersTestRun
# Create a variable for your subscription ID
subscriptionID=$(az account show --query id --output tsv)

Create resource group

Create a resource group where you can store your image template:

az group create -n $resourceGroupName -l $location

Create managed identity for the service

Create a managed identity for the image template (and potentially the Azure Image Builder build VM). In this example, the managed identity gets "Contributor" access, but you can refine the permissions or role as long as you include the permissions needed for the Azure Image Builder service to function properly.

For more information on the permissions needed for the Azure Image Builder service, see Configure Azure VM Image Builder permissions by using the Azure CLI.

For more information on how managed identities can be assigned and used in Azure Image Builder, see VM Image Builder template reference: Identity.

Run the following commands to create the managed identity:

# Create user-assigned identity for VM Image Builder to access the storage account where the script is stored
identityName=aibBuiUserId$(date +'%s')
az identity create -g $resourceGroupName -n $identityName

# Get the identity client and principal ID
imgBuilderCliId=$(az identity show -g $resourceGroupName -n $identityName --query clientId -o tsv)

# Get the user identity URI that's needed for the template
imgBuilderId=/subscriptions/$subscriptionID/resourcegroups/$resourceGroupName/providers/Microsoft.ManagedIdentity/userAssignedIdentities/$identityName

# Grant "Contributor" access to the user-assigned identity
az role assignment create \
    --assignee $imgBuilderCliId \
    --role "Contributor" \
    --scope /subscriptions/$subscriptionID/resourceGroups/$resourceGroupName

To use VM Image Builder with Azure Compute Gallery, you need to have an existing gallery and image definition. VM Image Builder doesn't create the gallery and image definition for you.

If you don't already have a gallery and image definition to use, start by creating them.

First, create a gallery:

az sig create \
    -g $resourceGroupName \
    --gallery-name $acgName

Then, create an image definition:

az sig image-definition create \
   -g $resourceGroupName \
   --gallery-name $acgName \
   --gallery-image-definition $imageDefName \
   --publisher myIbPublisher \
   --offer myOffer \
   --sku 22_04-lts-gen2 \
   --os-type Linux \
   --hyper-v-generation V2

Create the image template

Download the example JSON template and configure it with your variables. The following image template uses a Platform Image as its source, but you can change the source to an Azure Compute Gallery image to enable automatic image creation anytime there's a new image version in your gallery.

curl https://raw.githubusercontent.com/Azure/azvmimagebuilder/main/quickquickstarts/9_Setting_up_a_Trigger_with_a_Custom_Linux_Image/helloImageTemplate.json -o helloImageTemplateforTriggers.json
sed -i -e "s/<subscriptionID>/$subscriptionID/g" helloImageTemplateforTriggers.json
sed -i -e "s/<rgName>/$resourceGroupName/g" helloImageTemplateforTriggers.json
sed -i -e "s/<imageDefName>/$imageDefName/g" helloImageTemplateforTriggers.json
sed -i -e "s/<acgName>/$acgName/g" helloImageTemplateforTriggers.json
sed -i -e "s/<region1>/$location/g" helloImageTemplateforTriggers.json
sed -i -e "s/<region2>/$additionalregion/g" helloImageTemplateforTriggers.json
sed -i -e "s/<runOutputName>/$runOutputName/g" helloImageTemplateforTriggers.json
sed -i -e "s%<imgBuilderId>%$imgBuilderId%g" helloImageTemplateforTriggers.json

Image template requirements:

  • The source must be either a Platform image or Azure Compute Gallery image (only these two sources are allowed currently)
  • If you're using a Platform Image, then the version in the source needs to be Latest. For an Azure Compute Gallery image the last part of the resource ID that has the version name needs to be set to Latest.
  • You can't specify a version if you're distributing the image to an Azure Compute Gallery. The version is automatically incremented.
  • When source is set to an Azure Compute Gallery image and distribute is set to an Azure Compute Gallery, the source gallery image and the distribute gallery image can't be the same. The Azure Compute Gallery image definition ID can't be the same for both the source gallery image and the distribute gallery image.
  • The image template should have "Succeeded" in the provisioningState, meaning the template was created without any issues. If the template isn't provisioned successfully, you won't be able to create a trigger.

After configuring your template use the following command to submit the image configuration to the Azure Image Builder service:

az image builder create -g $resourceGroupName -n $imageTemplateName --image-template helloImageTemplateforTriggers.json

You can use the following command to check to make sure the image template was created successfully:

az image builder show --name $imageTemplateName --resource-group $resourceGroupName

Note

When running the command above the provisioningState should say "Succeeded", which means the template was created without any issues. If the provisioningState does not say succeeded, you will not be able to make a trigger use the image template.

Create source trigger

Download the example trigger template and configure it with your variables. The following trigger starts a new image build anytime the source image is updated.

curl https://raw.githubusercontent.com/Azure/azvmimagebuilder/main/quickquickstarts/9_Setting_up_a_Trigger_with_a_Custom_Linux_Image/trigger.json -o trigger.json
sed -i -e "s/<region1>/$location/g" trigger.json

Trigger requirements:

  • The location in the trigger must be the same as the location in the image template.
  • Only one kind of trigger is currently supported: SourceImage.
  • Only one SourceImage trigger per image is supported. If you already have a SourceImage trigger on the image, you can't create a new one.
  • You can't update the kind field to another type of trigger. You must delete the trigger and recreate it, or create another trigger with the appropriate configuration.

Use the following command to add the trigger to your resource group.

az image builder trigger create --name $ibTriggerName --resource-group $resourceGroupName --image-template-name $imageTemplateName --kind SourceImage

You can also use the following command to check that the trigger was created successfully:

az image builder trigger show --name $ibTriggerName --image-template-name $imageTemplateName --resource-group $resourceGroupName

Note

When running the command above the provisioningState should say Succeeded, which means the trigger was created without any issues. In status, the code should say Healthy and the message should say Trigger is active.

Clean up your resources

Deleting the trigger

Use the following command to delete the trigger:

az image builder trigger delete --name $ibTriggerName --image-template-name $imageTemplateName --resource-group $resourceGroupName

Deleting the image template

Use the following command to delete the image template:

az image builder delete --name $imageTemplateName --resource-group $resourceGroupName

Next steps

  • Last updated on