Compartilhar via

Como habilitar a criação automática de imagens com gatilhos do Construtor de Imagens do Azure

  • Artigo

Você pode usar o Construtor de Imagens de VM do Azure (AIB) com gatilhos para habilitar a criação automática de imagens quando determinados critérios forem atendidos em seu pipeline de build.

Importante

Informamos que existe uma restrição quanto ao número de gatilhos permitidos por região, especificamente 100 por região e por assinatura.

Observação

Atualmente, só oferecemos suporte à configuração de um gatilho para uma nova imagem de fonte, mas esperamos dar suporte a diferentes tipos de gatilhos no futuro.

Observação

Para evitar falhas desnecessárias, a criação automática de imagens via gatilhos será desativada se a compilação do modelo de imagem falhar várias vezes consecutivas (seja manual ou automaticamente acionada). Você ainda pode compilar manualmente o modelo de imagem e, uma vez que uma compilação manual seja bem-sucedida, os gatilhos automáticos serão reativados.

Pré-requisitos

Antes de configurar seu primeiro gatilho, verifique se você está usando a versão 2022-07-01 da API do Construtor de Imagens de VM do Azure.

Como configurar um gatilho no Construtor de Imagens de VM do Azure

Registrar os provedores

Para usar o Construtor de Imagens de VM do Azure com gatilhos, é necessário registrar os provedores abaixo. Verifique seu registro executando os seguintes comandos:

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

Caso não conste como registrado, execute o seguinte comando:

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

Registre o recurso de gatilhos de compilação automática de imagens:

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

Definir variáveis

Primeiro, é necessário definir algumas variáveis que você usará repetidamente nos comandos.

# Resource group name - ibTriggersTestRG in this example
resourceGroupName=ibTriggersRG
# Datacenter location - West US 2 in this example
location=westus2
# Additional region to replicate the image to - East US in this example
additionalregion=eastus2
# 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)

Criar grupo de recursos

Agora, você precisa criar um grupo de recursos onde possa armazenar seu modelo de imagem. Execute o seguinte comando para criar seu grupo de recursos:

az group create -n $resourceGroupName -l $location

Criar uma identidade gerenciada para o serviço

Você também precisará de criar uma identidade gerenciada que será usada para o modelo de imagem (e potencialmente o Construtor de Imagens de VM do Azure). Neste exemplo, criamos uma identidade gerenciada com acesso de "Colaborador", mas você pode refinar as permissões ou a função atribuída à identidade gerenciada, conforme desejar, desde que inclua as permissões necessárias para que o serviço do Construtor de Imagens de VM do Azure funcione corretamente.

Para obter mais informações sobre as permissões necessárias para o serviço Construtor de Imagens de VM do Azure, consulte a seguinte documentação: Configurar as permissões do Construtor de Imagens de VM do Azure usando a CLI do Azure

Para obter mais informações sobre como as identidades gerenciadas podem ser atribuídas e usadas no Construtor de Imagens de VM do Azure, consulte a seguinte documentação: Referência de modelo do Construtor de Imagens de VM do Azure: Identidade

Use o seguinte comando para criar a identidade gerenciada que será usada para o modelo de imagem:

# 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

Para usar o Construtor de Imagens de VM com a Galeria de Computação do Azure, você precisa ter uma definição de imagem e de galeria. O Construtor de Imagens de VM cria a definição de imagem e de galeria para você.

Se você ainda não tiver uma definição de imagem e a definição de galeria para usar, comece criando-as.

Primeiro, crie uma galeria:

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

Em seguida, crie uma definição de imagem:

az sig image-definition create \
   -g $resourceGroupName \
   --gallery-name $acgName \
   --gallery-image-definition $imageDefName \
   --publisher myIbPublisher \
   --offer myOffer \
   --sku 18.04-LTS \
   --os-type Linux

Criar o modelo de imagem

Faça o download do modelo JSON de exemplo e configure-o com suas variáveis. O seguinte modelo de imagem usa uma Imagem de Plataforma como sua fonte, mas você pode alterar a fonte para uma imagem da Galeria de Computação do Azure se quiser habilitar a criação automática de imagens sempre que houver uma nova versão de imagem na Galeria de Computação do Azure.

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

Requisitos do modelo de imagem:

  • O source deve ser uma Imagem de plataforma ou da Galeria de Computação do Azure (somente essas duas fontes são permitidas atualmente)
  • Se você estiver usando uma Imagem de plataforma, a versão na fonte precisa ser Latest. Para uma imagem da Galeria de Computação do Azure, a última parte da ID do recurso que tem o nome da versão precisa ser definida como Latest.
  • Não é possível especificar uma versão se você estiver distribuindo a imagem para uma Galeria de Computação do Azure. A versão é automaticamente incrementada.
  • Quando a origem é definida como uma imagem da Galeria de Computação do Azure e a distribuição é definida como uma Galeria de Computação do Azure, a imagem da galeria de fonte e a imagem da galeria de distribuição não podem ser as mesmas. A ID de definição de imagem da Galeria de Computação do Azure não pode ser a mesma para a imagem da galeria de fonte e a imagem da galeria de distribuição.
  • O modelo de imagem deve ter sido "Bem-sucedido" em provisioningState, o que significa que o modelo foi criado sem problemas. Se o modelo não for provisionado com sucesso, você não poderá criar um gatilho.

Depois de configurar seu modelo, use o seguinte comando para enviar a configuração da imagem para o serviço Construtor de Imagens de VM do Azure:

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

Você pode usar o seguinte comando para verificar se o modelo de imagem foi criado com sucesso:

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

Observação

Ao executar o comando acima, o provisioningState deve indicar "Bem-sucedido", o que significa que o modelo foi criado sem nenhum problema. Se o provisioningState não indicar bem-sucedido, você não poderá fazer com que um gatilho use o modelo de imagem.

Criar um gatilho de fonte

Faça o download do modelo de gatilho de exemplo e configure-o com suas variáveis. O seguinte gatilho inicia uma nova compilação de imagem sempre que a imagem de fonte é atualizada.

curl https://raw.githubusercontent.com/kof-f/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

Requisitos para o gatilho:

  • O local no gatilho precisa ser o mesmo que o local no modelo de imagem. Esse é um requisito do cmdlet az resource create.
  • Atualmente, oferecemos suporte a um kind de gatilho, que é uma "SourceImage"
  • Só damos suporte a uma "SourceImage" de gatilho por imagem. Se você já tiver uma "SourceImage" de gatilho na imagem, não poderá criar uma nova.
  • Não é possível atualizar o campo kind para outro tipo de gatilho. É necessário excluir o gatilho e recriá-lo ou criar outro gatilho com a configuração apropriada.

Use o seguinte comando para adicionar o gatilho ao seu grupo de recursos.

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

Você também pode usar o seguinte comando para verificar se o gatilho foi criado com sucesso:

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

Observação

Ao executar o comando acima, o provisioningState deve indicar Succeeded, o que significa que o gatilho foi criado sem nenhum problema. Em status, o código deve indicar Healthy e a mensagem deve indicar Trigger is active.

Limpar os recursos

Exclusão do gatilho

Use o seguinte comando para excluir o gatilho:

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

Exclusão do modelo de imagem

Use o seguinte comando para excluir o modelo de imagem:

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

Próximas etapas

Consulte a Referência do modelo de Construtor de Imagens de VM do Azure para obter mais informações.