Compartilhar via

Crie um modelo JSON do Bicep do Construtor de Imagens do Azure ou ARM

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

O Construtor de Imagens do Azure usa um arquivo Bicep ou um arquivo de modelo JSON de modelo do ARM para passar informações para o serviço Construtor de Imagens. Neste artigo, examinamos as seções dos arquivos, para que você possa criar seus próprios. For latest API versions, see template reference. Para ver exemplos completos de arquivos .json, confira o Construtor de Imagens do Azure no GitHub.

O formato básico é:

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "___location": "<region>",
  "tags": {
    "<name>": "<value>",
    "<name>": "<value>"
  },
  "identity": {},
  "properties": {
    "buildTimeoutInMinutes": <minutes>,
    "customize": [],
    "errorHandling":[],
    "distribute": [],
    "optimize": [],
    "source": {},
    "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>",
    "validate": {},
    "vmProfile": {
      "vmSize": "<vmSize>",
      "osDiskSizeGB": <sizeInGB>,
      "vnetConfig": {
        "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName1>",
        "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
        "proxyVmSize": "<vmSize>"
      },
      "userAssignedIdentities": [
              "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName1>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName2>",
        "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName3>",
        ...
      ]
    }
  }
}

Follow all Best Practices while creating image templates.

API version

A versão da API mudará ao longo do tempo à medida que a API for alterada. Confira as Novidades no Construtor de Imagens de VM do Azure para todas as principais alterações de API e atualizações de recursos para o serviço do Construtor de Imagens de VM do Azure.

Tipo

O type é o tipo de recurso, que deve ser Microsoft.VirtualMachineImages/imageTemplates.

"type": "Microsoft.VirtualMachineImages/imageTemplates",

Location

O Serviço do Construtor de Imagens de VM está disponível nessas regiões:

Note

Você ainda pode distribuir imagens fora dessas regiões.

  • Leste dos EUA
  • Leste dos EUA 2
  • Centro-oeste dos EUA
  • Oeste dos EUA
  • Oeste dos EUA 2
  • Oeste dos EUA 3
  • Centro-Sul dos EUA
  • Europa Setentrional
  • Oeste da Europa
  • Sudeste Asiático
  • Sudeste da Austrália
  • Leste da Austrália
  • Sul do Reino Unido
  • Oeste do Reino Unido
  • Sul do Brasil
  • Canadá Central
  • Índia Central
  • EUA Central
  • França Central
  • Centro-oeste da Alemanha
  • Leste do Japão
  • Centro-Norte dos EUA
  • Leste da Noruega
  • Norte da Suíça
  • Oeste da Índia JIO
  • Norte dos EAU
  • Ásia Oriental
  • Coreia Central
  • Norte da África do Sul
  • Catar Central
  • US Gov – Arizona (versão prévia pública)
  • US Gov – Virgínia (versão prévia pública)
  • Norte da China 3 (visualização pública)
  • Suécia Central
  • Polônia Central
  • Norte da Itália
  • Israel Central
  • Norte da Nova Zelândia
  • Taiwan Northwest

Important

Registre a funcionalidade Microsoft.VirtualMachineImages/FairfaxPublicPreview para ter acesso à versão prévia do Construtor de Imagens do Azure nas regiões do Azure Government (US Gov – Arizona e US Gov – Virgínia).

Important

Registre o recurso Microsoft.VirtualMachineImages/MooncakePublicPreview para acessar a visualização pública do Construtor de Imagens do Azure na região Norte da China 3.

To access the Azure VM Image Builder public preview in the Azure Government regions (USGov Arizona and USGov Virginia), you must register the Microsoft.VirtualMachineImages/FairfaxPublicPreview feature. Para fazer isso, execute o seguinte comando no PowerShell ou na CLI do Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

To access the Azure VM Image Builder public preview in the China North 3 region, you must register the Microsoft.VirtualMachineImages/MooncakePublicPreview feature. Para fazer isso, execute o seguinte comando no PowerShell ou na CLI do Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"___location": "<region>"

Data residency

O serviço Construtor de Imagens de VM do Azure mantém os dados do cliente em regiões que têm regras rígidas de residência de dados. Em caso de interrupção do serviço em regiões que têm requisitos de residência de dados, você precisará criar arquivos/modelos do Bicep em uma região e geografia diferentes.

Zone redundancy

A distribuição dá suporte à redundância de zona, os VHDs (Discos Rígidos Virtuais) são distribuídos para uma conta ZRS (Armazenamento com Redundância de Zona) por padrão e a versão da Galeria de Computação do Azure (anteriormente conhecida como Galeria de Imagens Compartilhadas) dará suporte a um tipo de armazenamento ZRS , se especificado.

Tags

Marcas são pares chave/valor que você pode especificar para a imagem gerada.

Identity

Há duas maneiras de adicionar identidades atribuídas pelo usuário explicadas abaixo.

Identidade atribuída pelo usuário para o recurso de modelo de imagem do Construtor de Imagens do Azure

Necessário – Para que o Construtor de Imagens tenha permissões para ler/gravar imagens e ler em scripts do Armazenamento do Azure, você deve criar uma identidade atribuída ao usuário do Azure que tenha permissões para os recursos individuais. Para obter detalhes sobre como as permissões do Construtor de Imagens funcionam e sobre as etapas relevantes, confira Criar uma imagem e usar uma identidade gerenciada atribuída pelo usuário para acessar arquivos em uma conta de armazenamento do Azure.

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<imgBuilderId>": {}
    }
}

A Identidade Atribuída pelo Usuário do serviço Construtor de Imagens:

  • Dá suporte a uma única identidade.
  • Não dá suporte a nomes de domínio personalizados.

Para saber mais, confira O que são identidades gerenciadas para recursos do Azure?. Para obter mais informações sobre como implantar esse recurso, confira Configurar identidades gerenciadas para recursos do Azure em uma VM do Azure usando a CLI do Azure.

Identidade atribuída pelo usuário para a VM de build do Construtor de Imagens

Esta propriedade só está disponível nas versões da API 2021-10-01 ou mais recentes.

Opcional: A VM de Compilação do Construtor de Imagens criado pelo serviço Construtor de Imagens na sua assinatura é usada para criar e personalizar a imagem. Para que a VM de Build do Construtor de Imagens tenha permissões de autenticação em outros serviços, como Azure Key Vault em sua assinatura, você deve criar uma ou mais Identidades Atribuídas pelo Usuário do Azure que tenham permissões para os recursos individuais. O Construtor de Imagens do Azure pode associar essas Identidades Atribuídas pelo Usuário à VM de Build. Os scripts personalizados em execução dentro da VM de Build podem buscar tokens para essas identidades e interagir com outros recursos do Azure conforme necessário. Lembre-se de que a identidade atribuída pelo usuário para o Construtor de Imagens do Azure deve ter a atribuição de função "Operador de Identidade Gerenciada" em todas as identidades atribuídas pelo usuário para que o Construtor de Imagens do Azure possa associá-las à VM de build.

Note

Lembre-se de que várias identidades podem ser especificadas para a VM de Build do Construtor de Imagens, incluindo a identidade que você criou para o recurso de modelo de imagem. Por padrão, a identidade que você criou para o recurso de modelo de imagem não será adicionada automaticamente à VM de build.

"properties": {
  "vmProfile": {
    "userAssignedIdentities": [
      "/subscriptions/<subscriptionID>/resourceGroups/<identityRgName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identityName>"
    ]
  }
}

A identidade atribuída pelo usuário para a VM de build do Construtor de Imagens:

  • Dá suporte a uma lista de uma ou mais identidades gerenciadas atribuídas pelo usuário a serem configuradas na VM.
  • Dá suporte a cenários de assinatura cruzada (identidade criada em uma assinatura enquanto o modelo de imagem é criado em outra assinatura no mesmo locatário).
  • Não dá suporte a cenários entre locatários (identidade criada em um locatário enquanto o modelo de imagem é criado em outro locatário).

Para obter mais informações, consulte:

Properties: buildTimeoutInMinutes

Duração máxima a aguardar durante a compilação do modelo de imagem (inclui todas as personalizações, validações e distribuições).

Se você não especificar a propriedade ou definir o valor como 0, será usado o valor padrão, que é de 240 minutos ou quatro horas. O valor mínimo é de 6 minutos, e o valor máximo é de 960 minutos ou 16 horas. Quando o valor do tempo limite é atingido (independentemente de a criação da imagem ter sido concluída ou não), você verá um erro semelhante a:

[ERROR] Failed while waiting for packerizer: Timeout waiting for microservice to
[ERROR] complete: 'context deadline exceeded'

Para o Windows, não recomendamos definir buildTimeoutInMinutes abaixo de 60 minutos. If you find you're hitting the timeout, review the logs to see if the customization step is waiting on something like user input. Se você achar que precisa de mais tempo para a conclusão das personalizações, aumente o valor de buildTimeoutInMinutes. No entanto, não defina-o muito alto, pois talvez seja necessário aguardar até que ele atinja o tempo limite antes de ver um erro.

Properties: customize

O Construtor de Imagens dá suporte a vários "personalizadores", que são funções usadas para personalizar a sua imagem, como executar scripts ou reinicializar servidores.

Ao usar customize:

  • Você pode usar vários personalizadores.
  • Os personalizadores são executados na ordem especificada no modelo.
  • Se um personalizador falhar, o componente de personalização inteiro falhará e relatará um erro.
  • Teste os scripts completamente antes de usá-los em um modelo. A depuração dos scripts por conta própria é mais fácil.
  • Não coloque dados confidenciais nos scripts. Os comandos embutidos podem ser visualizados na definição do modelo de imagem. No caso de informações confidenciais (incluindo senhas, tokens SAS, tokens de autenticação etc.), elas devem ser movidas para scripts no Armazenamento do Azure, cujo acesso exige autenticação.
  • Os locais de script precisam ser acessíveis publicamente, a menos que você esteja usando uma identidade atribuída pelo usuário.

A seção customize é uma matriz. Os tipos de personalizador com suporte são: Arquivo, PowerShell, Shell, WindowsRestart e WindowsUpdate.

"customize": [
  {
    "type": "File",
    "destination": "string",
    "sha256Checksum": "string",
    "sourceUri": "string"
  },
  {
    "type": "PowerShell",
    "inline": [ "string" ],
    "runAsSystem": "bool",
    "runElevated": "bool",
    "scriptUri": "string",
    "sha256Checksum": "string",
    "validExitCodes": [ "int" ]
  },
  {
    "type": "Shell",
    "inline": [ "string" ],
    "scriptUri": "string",
    "sha256Checksum": "string"
  },
  {
    "type": "WindowsRestart",
    "restartCheckCommand": "string",
    "restartCommand": "string",
    "restartTimeout": "string"
  },
  {
    "type": "WindowsUpdate",
    "filters": [ "string" ],
    "searchCriteria": "string",
    "updateLimit": "int"
  }
]

Shell customizer

O personalizador Shell dá suporte à execução de scripts de shell no Linux. The shell scripts must be publicly accessible or you must have configured an MSI for Image Builder to access them.

"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "scriptUri": "<link to script>",
    "sha256Checksum": "<sha256 checksum>"
  }
],
"customize": [
  {
    "type": "Shell",
    "name": "<name>",
    "inline": "<commands to run>"
  }
]

Customize properties:

  • type – Shell.

  • name - name for tracking the customization.

  • scriptUri - URI to the ___location of the file.

  • inline - array of shell commands, separated by commas.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this value locally, and then Image Builder will checksum and validate.

    Para gerar a sha256Checksum, usando um terminal no Mac/Linux, execute: sha256sum <fileName>

Note

Os comandos embutidos são armazenados como parte da definição do modelo de imagem, e você pode vê-los quando descarta a definição da imagem. Se você tem comandos ou valores confidenciais (incluindo senhas, tokens SAS, tokens de autenticação etc.), é recomendado que eles sejam movidos para scripts e usem uma identidade de usuário para a autenticação no Armazenamento do Azure.

Privilégios de superusuário

Use o prefixo sudo nos comandos para executá-los com privilégios de superusuário. Você pode adicionar os comandos em scripts ou usá-los em comandos embutidos, por exemplo:

"type": "Shell",
"name": "setupBuildPath",
"inline": [
    "sudo mkdir /buildArtifacts",
    "sudo cp /tmp/index.html /buildArtifacts/index.html"
]

Exemplo de um script usando sudo que você pode referenciar usando scriptUri:

#!/bin/bash -e

echo "Telemetry: creating files"
mkdir /myfiles

echo "Telemetry: running sudo 'as-is' in a script"
sudo touch /myfiles/somethingElevated.txt

Personalizador de reinicialização do Windows

O personalizador WindowsRestart permite reiniciar uma VM do Windows e aguardar que ela volte a ficar online, permitindo que você instale softwares que exigem uma reinicialização.

"customize": [
  {
    "type": "WindowsRestart",
    "restartCommand": "shutdown /r /f /t 0",
    "restartCheckCommand": "echo Azure-Image-Builder-Restarted-the-VM  > c:\\buildArtifacts\\azureImageBuilderRestart.txt",
    "restartTimeout": "5m"
  }
]

Customize properties:

  • Type: WindowsRestart.
  • restartCommand - Command to execute the restart (optional). O padrão é 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand – Command to check if restart succeeded (optional).
  • restartTimeout - Restart time out specified as a string of magnitude and unit. Por exemplo, 5m (5 minutos) ou 2h (2 horas). O padrão é: 5m.

Note

Não há nenhum personalizador de reinicialização do Linux.

PowerShell customizer

O PowerShell personalizador dá suporte à execução de scripts do PowerShell e comandos embutidos no Windows, os scripts devem estar acessíveis publicamente para que o serviço os acesse.

"customize": [
  {
    "type": "PowerShell",
    "name":   "<name>",
    "scriptUri": "<path to script>",
    "runElevated": <true false>,
    "runAsSystem": <true false>,
    "sha256Checksum": "<sha256 checksum>"
  },
  {
    "type": "PowerShell",
    "name": "<name>",
    "inline": "<PowerShell syntax to run>",
    "validExitCodes": [<exit code>],
    "runElevated": <true or false>,
    "runAsSystem": <true or false>
  }
]

Customize properties:

  • type – PowerShell.

  • scriptUri - URI to the ___location of the PowerShell script file.

  • inline – Inline commands to be run, separated by commas.

  • validExitCodes – Optional, valid codes that can be returned from the script/inline command. A propriedade evita a falha relatada do script/comando embutido.

  • runElevated – Optional, boolean, support for running commands and scripts with elevated permissions.

  • runAsSystem - Optional, boolean, determines whether the PowerShell script should be run as the System user.

  • sha256Checksum - generate the SHA256 checksum of the file locally, update the checksum value to lowercase, and Image Builder will validate the checksum during the deployment of the image template.

    To generate the sha256Checksum, use the Get-FileHash cmdlet in PowerShell.

File customizer

O personalizador File permite que o Construtor de Imagens baixe um arquivo de um repositório do GitHub ou armazenamento do Azure. O personalizador dá suporte ao Linux e ao Windows. Se você tiver um pipeline de build de imagem que se baseia em artefatos de build, poderá definir o personalizador de arquivo para baixar do compartilhamento de build e mover os artefatos para a imagem.

"customize": [
  {
    "type": "File",
    "name": "<name>",
    "sourceUri": "<source ___location>",
    "destination": "<destination>",
    "sha256Checksum": "<sha256 checksum>"
  }
]

Propriedades do personalizador de arquivo:

  • sourceUri - an accessible storage endpoint, this endpoint can be GitHub or Azure storage. Você só pode baixar um arquivo, não um diretório inteiro. Se você precisar baixar um diretório, use um arquivo compactado e descompacte-o usando os personalizadores Shell ou PowerShell.

    Note

    Se o sourceUri for uma Conta do Armazenamento do Azure, independentemente do blob ser marcado como público, você precisará conceder permissões de identidade de usuário gerenciadas para acesso de leitura no blob. See this example to set the storage permissions.

  • destination – the full destination path and file name. Qualquer caminho e subdiretórios referenciados devem existir. Use os personalizadores Shell ou PowerShell para configurar esses caminhos com antecedência. Você pode usar os personalizadores de script para criar o caminho.

Há suporte para esse personalizador em diretórios do Windows e caminhos do Linux, mas há algumas diferenças:

  • Linux – o único caminho em que o construtor de imagens pode gravar em é /tmp.
  • Windows – nenhuma restrição de caminho, mas o caminho deve existir.

Se houver um erro ao tentar baixar o arquivo ou colocá-lo em um diretório especificado, a etapa de personalização falhará e esse erro estará no customization.log.

Note

O personalizador de arquivos é adequado apenas para downloads de arquivos pequenos, < 20 MB. Para downloads de arquivos maiores, use um script ou comando embutido, então use o código para baixar arquivos, como o wget ou o curl do Linux e o Invoke-WebRequest do Windows. Para arquivos que estão no armazenamento do Azure, atribua uma identidade com permissões para exibir esse arquivo para a VM de build seguindo a documentação aqui: Identidade atribuída pelo usuário para a VM de build do Construtor de Imagens. Qualquer arquivo que não esteja armazenado no Azure deve estar publicamente acessível para que o Construtor de Imagens do Azure possa baixá-lo.

  • sha256Checksum - generate the SHA256 checksum of the file locally, update the checksum value to lowercase, and Image Builder will validate the checksum during the deployment of the image template.

    To generate the sha256Checksum, use the Get-FileHash cmdlet in PowerShell.

Personalizador do Windows Update

O personalizador WindowsUpdate foi criado com base no Provisionador do Windows Update da comunidade para o Packer, que é um projeto de código aberto mantido pela comunidade do Packer. A Microsoft testa e valida o provisionador com o serviço do Construtor de Imagens e dará suporte à investigação de problemas com ele, trabalhando para resolvê-los. No entanto, o projeto de código aberto não tem suporte oficial da Microsoft. Para obter a documentação detalhada e ajuda com o Provisionador do Windows Update, confira o repositório do projeto.

"customize": [
  {
    "type": "WindowsUpdate",
    "searchCriteria": "IsInstalled=0",
    "filters": [
      "exclude:$_.Title -like '*Preview*'",
      "include:$true"
    ],
    "updateLimit": 20
  }
]

Customizer properties:

  • type – WindowsUpdate.
  • searchCriteria - Optional, defines which type of updates are installed (like Recommended or Important), BrowseOnly=0 and IsInstalled=0 (Recommended) is the default.
  • filters – Optional, allows you to specify a filter to include or exclude updates.
  • updateLimit – Optional, defines how many updates can be installed, default 1000.

Note

O personalizador do Windows Update poderá falhar se houver reinicializações pendentes do Windows ou se as instalações do aplicativo ainda estiverem em execução, normalmente você poderá ver esse erro no customization.log, System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. We strongly advise you consider adding in a Windows Restart, and/or allowing applications enough time to complete their installations using sleep or wait commands in the inline commands or scripts before running Windows Update.

Generalize

Por padrão, o Construtor de Imagens do Azure também executará o código deprovision no final de cada fase de personalização de imagem para generalizar a imagem. Generalizar é um processo em que a imagem é configurada para que possa ser reutilizada para criar várias VMs. Para VMs do Windows, o Construtor de Imagens do Azure usa Sysprep. Para Linux, o Construtor de Imagens do Azure executa waagent -deprovision.

Os comandos que os usuários do Construtor de Imagens devem generalizar podem não ser adequados para todas as situações, portanto, o Construtor de Imagens do Azure permite personalizar esse comando, se necessário.

Se você estiver migrando a personalização existente e estiver usando diferentes comandos Sysprep/waagent, poderá usar os comandos genéricos do Construtor de Imagens. Se a criação da VM falhar, use seus próprios comandos Sysprep ou waagent.

Se o Construtor de Imagens do Azure criar uma imagem personalizada do Windows com êxito e você criar uma VM com base nela e descobrir que a criação da VM falhou ou não foi concluída com êxito, você precisará examinar a documentação do Windows Server Sysprep ou criar uma solicitação de suporte com a equipe de Suporte ao Atendimento ao Cliente do Windows Server Sysprep, que pode solucionar problemas e aconselhar sobre o uso correto do Sysprep.

Comando Sysprep padrão

Write-Output '>>> Waiting for GA Service (RdAgent) to start ...'
while ((Get-Service RdAgent).Status -ne 'Running') { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureTelemetryService) to start ...'
while ((Get-Service WindowsAzureTelemetryService) -and ((Get-Service WindowsAzureTelemetryService).Status -ne 'Running')) { Start-Sleep -s 5 }
Write-Output '>>> Waiting for GA Service (WindowsAzureGuestAgent) to start ...'
while ((Get-Service WindowsAzureGuestAgent).Status -ne 'Running') { Start-Sleep -s 5 }
if( Test-Path $Env:SystemRoot\system32\Sysprep\unattend.xml ) {
  Write-Output '>>> Removing Sysprep\unattend.xml ...'
  Remove-Item $Env:SystemRoot\system32\Sysprep\unattend.xml -Force
}
if (Test-Path $Env:SystemRoot\Panther\unattend.xml) {
  Write-Output '>>> Removing Panther\unattend.xml ...'
  Remove-Item $Env:SystemRoot\Panther\unattend.xml -Force
}
Write-Output '>>> Sysprepping VM ...'
& $Env:SystemRoot\System32\Sysprep\Sysprep.exe /oobe /generalize /quiet /quit
while($true) {
  $imageState = (Get-ItemProperty HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Setup\State).ImageState
  Write-Output $imageState
  if ($imageState -eq 'IMAGE_STATE_GENERALIZE_RESEAL_TO_OOBE') { break }
  Start-Sleep -s 5
}
Write-Output '>>> Sysprep complete ...'

Comando padrão de desprovisionamento do Linux

WAAGENT=/usr/sbin/waagent
waagent -version 1> /dev/null 2>&1
if [ $? -eq 0 ]; then
  WAAGENT=waagent
fi
$WAAGENT -force -deprovision+user && export HISTSIZE=0 && sync

Como substituir os comandos

Para substituir os comandos, use os provisionadores de script PowerShell ou Shell para criar os arquivos de comando com o nome exato do arquivo e coloque-os nos diretórios corretos:

  • Windows: c:\DeprovisioningScript.ps1
  • Linux: /tmp/DeprovisioningScript.sh

O Construtor de Imagens lê esses comandos, esses comandos são gravados nos logs do AIB, customization.log. See troubleshooting on how to collect logs.

Properties: errorHandling

A propriedade errorHandling permite que você configure como os erros são tratados durante a criação da imagem.

{
  "errorHandling": {
    "onCustomizerError": "abort",
    "onValidationError": "cleanup"
  }
}

A propriedade errorHandling permite que você configure como os erros são tratados durante a criação da imagem. Tem duas propriedades:

  • onCustomizerError - Specifies the action to take when an error occurs during the customizer phase of image creation.
  • onValidationError - Specifies the action to take when an error occurs during validation of the image template.

A propriedade errorHandling também tem dois valores possíveis para lidar com erros durante a criação da imagem:

  • cleanup - Ensures that temporary resources created by Packer are cleaned up even if Packer or one of the customizations/validations encounters an error. Isso mantém a compatibilidade com versões anteriores com o comportamento atual.
  • abort - In case Packer encounters an error, the Azure Image Builder (AIB) service skips the clean up of temporary resources. Como proprietário do modelo AIB, você é responsável por limpar esses recursos da sua assinatura. Esses recursos podem conter informações úteis, como logs e arquivos deixados para trás em uma VM temporária, o que pode ajudar na investigação do erro encontrado pelo Packer.

Properties: distribute

O Construtor de Imagens do Azure dá suporte a três destinos de distribuição:

  • ManagedImage - Managed image.
  • sharedImage - Azure Compute Gallery.
  • VHD - VHD in a storage account.

Você pode distribuir uma imagem para ambos os tipos de destino na mesma configuração.

Note

O comando padrão do Sysprep do AIB não inclui "/mode:vm", mas essa propriedade talvez seja necessária ao criar imagens que terão a função HyperV instalada. Se precisar adicionar esse argumento de comando, você deverá substituir o comando Sysprep.

Como você pode ter mais de um destino para distribuir, o Construtor de Imagens mantém um estado para cada destino de distribuição que pode ser acessado consultando o runOutputName. O runOutputName é um objeto que você pode consultar após a distribuição para obter informações sobre essa distribuição. Por exemplo, você pode consultar o local do VHD ou as regiões nas quais a versão da imagem foi replicada ou a versão de imagem SIG criada. Essa é uma propriedade de cada destino de distribuição. O runOutputName deve ser exclusivo para cada destino de distribuição. Aqui está um exemplo da consulta de uma distribuição da Galeria de Computação do Azure:

subscriptionID=<subcriptionID>
imageResourceGroup=<resourceGroup of image template>
runOutputName=<runOutputName>

az resource show \
  --ids "/subscriptions/$subscriptionID/resourcegroups/$imageResourceGroup/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/$runOutputName" \
--api-version=2023-07-01

Output:

{
  "id": "/subscriptions/xxxxxx/resourcegroups/rheltest/providers/Microsoft.VirtualMachineImages/imageTemplates/ImageTemplateLinuxRHEL77/runOutputs/rhel77",
  "identity": null,
  "kind": null,
  "___location": null,
  "managedBy": null,
  "name": "rhel77",
  "plan": null,
  "properties": {
    "artifactId": "/subscriptions/xxxxxx/resourceGroups/aibDevOpsImg/providers/Microsoft.Compute/galleries/devOpsSIG/images/rhel/versions/0.24105.52755",
    "provisioningState": "Succeeded"
  },
  "resourceGroup": "rheltest",
  "sku": null,
  "tags": null,
  "type": "Microsoft.VirtualMachineImages/imageTemplates/runOutputs"
}

Distribute: managedImage

A saída da imagem é um recurso de imagem gerenciado.

{
  "type":"ManagedImage",
  "imageId": "<resource ID>",
  "___location": "<region>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

Distribute properties:

  • type – ManagedImage
  • imageId – Resource ID of the destination image, expected format: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • ___location - ___location of the managed image.
  • runOutputName – unique name for identifying the distribution.
  • artifactTags - Optional user specified key\value tags.

Note

O grupo de recursos de destino deve existir. Se você quiser que a imagem seja distribuída para outra região, isso aumentará o tempo de implantação.

Distribute: sharedImage

A Galeria de Computação do Azure é um novo serviço de Gerenciamento de Imagens que permite o gerenciamento de replicação de região de imagem, o controle de versão e o compartilhamento de imagens personalizadas. O Construtor de Imagens do Azure dá suporte à distribuição com esse serviço, assim, você pode distribuir imagens para regiões com suporte nas Galerias de Computação do Azure.

uma Galeria de Computação do Azure é feita de:

  • Gallery - Container for multiple images. Uma galeria é implantada em uma região.
  • Image definitions - a conceptual grouping for images.
  • Image versions - an image type used for deploying a VM or scale set. As versões de imagem podem ser replicadas para outras regiões em que as VMs precisam ser implantadas.

Antes de distribuir para a galeria, você deve criar uma galeria e uma definição de imagem, confira Criar uma galeria.

Note

A ID da versão da imagem precisa ser distinta ou diferente de qualquer versão de imagem que esteja na Galeria de Computação do Azure existente.

{
  "type": "SharedImage",
  "galleryImageId": "<resource ID>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

O JSON a seguir é um exemplo de como usar o campo replicationRegions para distribuir para uma Galeria de Computação do Azure.

  "replicationRegions": [
      "<region where the gallery is deployed>",
      "<region>"
  ]

Note

replicationRegions foi preterido para distribuições de galerias, pois targetRegions é uma propriedade atualizada. For more information, see targetRegions.

Distribute: targetRegions

O JSON a seguir é um exemplo de como usar o campo targetRegions para distribuir para uma Galeria de Computação do Azure.

"distribute": [
      {
        "type": "SharedImage",
        "galleryImageId": "<resource ID>",
        "runOutputName": "<name>",
        "artifactTags": {
          "<name>": "<value>",
          "<name>": "<value>"
        },
        "targetRegions": [
             {
              "name": "eastus",
              "replicaCount": 2,
              "storageAccountType": "Standard_ZRS"
             },
             {
              "name": "eastus2",
              "replicaCount": 3,
              "storageAccountType": "Premium_LRS"
             }
          ]
       },
    ]

Distribuir propriedades para galerias:

  • type - sharedImage

  • galleryImageId – ID of the Azure Compute Gallery, this property can be specified in two formats:

    • Controle de versão automático: o Construtor de Imagens gera um número de versão monotônico para você. Essa propriedade é útil quando você deseja continuar reconstruindo imagens com base no mesmo modelo: o formato é: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>.
    • Controle de versão explícito – você pode passar o número de versão que deseja que o construtor de imagem use. O formato é: /subscriptions/<subscriptionID>/resourceGroups/<rgName>/providers/Microsoft.Compute/galleries/<sharedImageGalName>/images/<imageDefName>/versions/<version - for example: 1.1.1>

  • runOutputName – unique name for identifying the distribution.

  • artifactTags - optional user specified key\value tags.

  • replicationRegions - array of regions for replication. Uma das regiões deve ser aquela em que a galeria é implantada. Adicionar regiões significa um aumento do tempo de compilação, pois a compilação não é concluída até que a replicação seja concluída. Esse campo foi preterido da versão 2022-07-01 em diante da API. Use targetRegions ao distribuir um tipo “SharedImage”.

  • targetRegions - an array of regions for replication. It's newly introduced as part of the 2022-07-01 API and applies only to the SharedImage type distribute.

  • excludeFromLatest (optional) - allows you to mark the image version you create not be used as the latest version in the gallery definition, the default is 'false'.

  • storageAccountType (optional) - AIB supports specifying these types of storage for the image version that is to be created:

    • "Standard_LRS"
    • "Standard_ZRS","

Note

Se o modelo de imagem e o image definition referenciado não estiverem no mesmo local, você verá um tempo adicional para criar imagens. Atualmente, o Construtor de Imagens não tem um parâmetro ___location para o recurso de versão da imagem, nós o pegamos de seu image definition pai. Por exemplo, se uma definição de imagem estiver em westus e você quiser que a versão da imagem seja replicada para eastus, um blob será copiado para westus e, com base nele, um recurso de versão da imagem em westus será criado e replicado para eastus. Para evitar o tempo de replicação adicional, verifique se o image definition e o modelo de imagem estão no mesmo local.

controle de versão

The versioning property is for the sharedImage distribute type only. É uma enumeração com dois possíveis valores:

  • latest - New strictly increasing schema per design
  • source - Schema based upon the version number of the source image.

O esquema de numeração da versão padrão é latest. O esquema mais recente tem uma propriedade adicional, "major", que especifica a versão principal na qual gerar a versão mais recente.

Note

A lógica de geração da versão existente para a distribuição sharedImage foi preterida. Duas novas opções são fornecidas: versões monotonicamente crescentes que são sempre a versão mais recente em uma galeria e versões geradas com base no número de versão da imagem de origem. A enumeração especificando o esquema de geração da versão permite a expansão no futuro com esquemas de geração de versão adicionais.

    "distribute": [
        "versioning": {
            "scheme": "Latest",
            "major": 1
        }
    ]

versioning properties:

  • scheme - Generate new version number for distribution. Latest ou Source são dois possíveis valores.
  • major - Specifies the major version under which to generate the latest version. Aplicável somente quando o scheme estiver definido como Latest. Por exemplo, em uma galeria com as seguintes versões publicadas: 0.1.1, 0.1.2, 1.0.0, 1.0.1, 1.1.0, 1.1.1, 1.2.0, 2.0.0, 2.0.1, 2.1.0
    • Com o major não definido ou o major definido como 2, o esquema Latest gera a versão 2.1.1
    • Com o principal definido como 1, o esquema mais recente gera a versão 1.2.1
    • Com o major definido como 0, o esquema mais recente gera a versão 0.1.3

Distribute: VHD

Você pode gerar uma saída para um VHD. Em seguida, você pode copiar o VHD e usá-lo para publicar no Azure MarketPlace ou usar com Azure Stack.

{
  "type": "VHD",
  "runOutputName": "<VHD name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  }
}

Suporte a SO: Windows e Linux

Distribuir parâmetros de VHD:

  • type - VHD.
  • runOutputName – unique name for identifying the distribution.
  • tags - Optional user specified key value pair tags.

O Construtor de Imagens do Azure não permite que o usuário especifique um local de conta de armazenamento, mas você pode consultar o status de runOutputs para obter o local.

az resource show \
  --ids "/subscriptions/$subscriptionId/resourcegroups/<imageResourceGroup>/providers/Microsoft.VirtualMachineImages/imageTemplates/<imageTemplateName>/runOutputs/<runOutputName>"  | grep artifactUri

Note

Depois que o VHD tiver sido criado, copie-o para um local diferente assim que possível. O VHD é armazenado em uma conta de armazenamento no grupo de recursos temporário criado quando o modelo de imagem é enviado para o serviço do Construtor de Imagens do Azure. Se você excluir o modelo de imagem, o VHD será perdido.

O JSON a seguir distribui a imagem como um VHD para uma conta de armazenamento personalizada.

"distribute": [
  {
    "type": "VHD",
    "runOutputName": "<VHD name>",
    "artifactTags": {
        "<name>": "<value>",
        "<name>": "<value>"
    },
    "uri": "<replace with Azure storage URI>"
  }
]

Propriedades de distribuição do VHD:

uri - Optional Azure Storage URI for the distributed VHD blob. Omitir o uso do padrão (cadeia de caracteres vazia), caso em que o VHD seria publicado na conta de armazenamento no grupo de recursos de preparo.

Properties: optimize

A propriedade optimize pode ser habilitada ao criar uma imagem de VM e permite que a otimização da VM melhore o tempo de criação da imagem.

"optimize": {
      "vmBoot": {
        "state": "Enabled"
      }
    }
  • vmBoot: A configuration related to the booting process of the virtual machine (VM), used to control optimizations that can improve boot time or other performance aspects.
  • state: o estado do recurso de otimização de inicialização dentro do vmBoot, com o valor Enabled indicando que o recurso está ativado para reduzir o tempo de criação da imagem.

Para saber mais, confira Otimização de VM para imagens de galeria com o Construtor de Imagens de VM do Azure.

Properties: source

A seção source contém informações sobre a imagem de origem que será usada pelo Construtor de Imagens. O Construtor de Imagens do Azure só dá suporte para imagens generalizadas como imagens de origem; não dá suporte para imagens especializadas no momento.

A API requer um SourceType que define a origem para o build da imagem. No momento, há três tipos:

  • PlatformImage – indica que a imagem de origem é uma imagem do Marketplace.
  • ManagedImage – usado ao iniciar em uma imagem gerenciada normal.
  • SharedImageVersion – usado quando você está usando uma versão de imagem em uma Galeria de Computação do Azure como origem.

Note

When using existing Windows custom images, you can run the Sysprep command up to three times on a single Windows 7 or Windows Server 2008 R2 image, or 1001 times on a single Windows image for later versions; for more information, see the sysprep documentation.

PlatformImage source

O Construtor de Imagens do Azure dá suporte ao Windows Server e ao cliente e às imagens do Azure Marketplace do Linux, confira Saber mais sobre o Construtor de Imagens do Azure para ver a lista completa.

"source": {
  "type": "PlatformImage",
  "publisher": "Canonical",
  "offer": "UbuntuServer",
  "sku": "18.04-LTS",
  "version": "latest"
}

As propriedades aqui são as mesmas usadas para criar VMs. Usando a CLI do AZ, execute o seguinte para obter as propriedades:

az vm image list -l westus -f UbuntuServer -p Canonical --output table --all

Você pode usar latest na versão. A versão é avaliada quando o build da imagem ocorre, não quando o modelo é enviado. Se você usar essa funcionalidade com o destino da Galeria de Computação do Azure, poderá evitar reenviar o modelo e executar novamente o build da imagem a intervalos para que suas imagens sejam recriadas com base em imagens mais recentes.

Suporte para informações do plano do Marketplace

Você também pode especificar informações de plano, por exemplo:

"source": {
  "type": "PlatformImage",
  "publisher": "RedHat",
  "offer": "rhel-byos",
  "sku": "rhel-lvm75",
  "version": "latest",
  "planInfo": {
    "planName": "rhel-lvm75",
    "planProduct": "rhel-byos",
    "planPublisher": "redhat"
  }
}

ManagedImage source

Define a imagem de origem como uma imagem gerenciada existente de um VHD ou VM generalizado.

Note

A imagem gerenciada de origem precisa ser de um sistema operacional compatível e estar na mesma região e assinatura do modelo do Construtor de Imagens.

"source": {
  "type": "ManagedImage",
  "imageId": "/subscriptions/<subscriptionId>/resourceGroups/{destinationResourceGroupName}/providers/Microsoft.Compute/images/<imageName>"
}

O imageId deve ser a ResourceId da imagem gerenciada. Use az image list para listar as imagens disponíveis.

SharedImageVersion source

Define a imagem de origem como uma versão de imagem existente em uma Galeria de Computação do Azure.

Note

A versão da imagem compartilhada de origem precisa ser de um sistema operacional compatível e estar na mesma região do modelo do Construtor de Imagens do Azure, caso contrário, replique a versão da imagem para a região do modelo do Construtor de Imagens.

"source": {
  "type": "SharedImageVersion",
  "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}
  • imageVersionId: ID do recurso do modelo do ARM da versão da imagem. Quando o nome da versão da imagem é "mais recente", a versão é avaliada no momento do build da imagem. O imageVersionId deve ser o ResourceId da versão da imagem. Use az sig image-version list para listar as versões da imagem.

O JSON a seguir define a imagem de origem como uma imagem armazenada em uma Galeria Compartilhada Direta.

Note

A Galeria Compartilhada Direta está atualmente em disponibilidade de versão prévia.

    source: {
      "type": "SharedImageVersion",
      "imageVersionId": "<replace with resourceId of the image stored in the Direct Shared Gallery>"
    },

O JSON a seguir define a imagem de origem como a versão de imagem mais recente para uma imagem armazenada em uma Galeria de Computação do Azure.

"properties": {
    "source": {
        "type": "SharedImageVersion",
        "imageVersionId": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<azureComputeGalleryName>/images/<imageDefinitionName>/versions/latest"
    }
},

SharedImageVersion properties:

imageVersionId - ARM template resource ID of the image version. Quando o nome da versão da imagem é mais "recente", a versão é avaliada no momento do build da imagem.

Properties: stagingResourceGroup

A propriedade stagingResourceGroup contém informações sobre o grupo de recursos de preparo que o serviço Construtor de Imagens cria para uso durante o processo de criação de imagens. A propriedade stagingResourceGroup é opcional para quem deseja ter mais controle sobre o grupo de recursos criado pelo Construtor de Imagens durante o processo de compilação da imagem. Você pode criar seu próprio grupo de recursos e especificá-lo na seção stagingResourceGroup ou fazer com que o Construtor de Imagens crie um em seu nome.

Important

O grupo de recursos de preparação especificado não pode ser associado a outro modelo de imagem, deve estar vazio (sem recursos dentro), na mesma região que o modelo de imagem, e ter um RBAC "Colaborador" ou "Proprietário" aplicado à identidade atribuída ao recurso de modelo de imagem do Construtor de Imagens do Azure. O Construtor de Imagens verifica as marcas no grupo de recursos de preparo com chaves imageTemplateResourceGroupName e imageTemplateName para determinar se algum modelo de imagem usa o grupo de recursos de preparo. Se essas marcas existirem antes do envio do modelo de imagem ou não corresponderem ao modelo de imagem em execução durante a compilação da imagem, a operação falhará.

"properties": {
  "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>"
}

Cenários de criação de modelo

  • A propriedade stagingResourceGroup deve ficar em branco

    Se a propriedade stagingResourceGroup não for especificada ou for especificada com uma cadeia de caracteres vazia, o serviço Construtor de Imagens criará um grupo de recursos de preparo com a convenção de nome padrão "IT_***". O grupo de recursos de preparo tem as marcas padrão aplicadas a ele: createdBy, imageTemplateName, imageTemplateResourceGroupName. Além disso, o RBAC padrão é aplicado à identidade atribuída ao recurso de modelo do Construtor de Imagens do Azure, que é "Colaborador".

  • A propriedade stagingResourceGroup é especificada com um grupo de recursos existente

    Se a propriedade stagingResourceGroup for especificada com um grupo de recursos que existe, o serviço Construtor de Imagens verificará se o grupo de recursos não está associado a outro modelo de imagem, se está vazio (sem recursos dentro), na mesma região do modelo de imagem e se o RBAC "Colaborador" ou "Proprietário" foi aplicado à identidade atribuída ao recurso de modelo de imagem do Construtor de Imagens do Azure. Se algum dos requisitos mencionados acima não for atendido, um erro será gerado. O grupo de recursos de preparo tem as seguintes marcas adicionadas a ele: usedBy, imageTemplateName, imageTemplateResourceGroupName. Marcas preexistentes não são excluídas.

Important

Você precisará atribuir a função de colaborador ao grupo de recursos da entidade de serviço correspondente ao aplicativo próprio do Construtor de Imagens do Azure, ao tentar especificar um grupo de recursos pré-existente e uma VNet para o serviço do Construtor de Imagens do Azure com uma imagem de origem do Windows. Para obter as instruções do comando e do portal da CLI sobre como atribuir a função de colaborador ao grupo de recursos, confira a seguinte documentação Solucionar problemas do Construtor de Imagens da VM do Azure: erro de autorização ao criar disco

  • A propriedade stagingResourceGroup é especificada com um grupo de recursos que não existe

    Se a propriedade stagingResourceGroup for especificada com um grupo de recursos que não existe, o serviço Construtor de Imagens criará um grupo de recursos de preparo com o nome fornecido na propriedade stagingResourceGroup. Haverá um erro se o nome fornecido não atender aos requisitos de nomenclatura do Azure para grupos de recursos. O grupo de recursos de preparo tem as marcas padrão aplicadas a ele: createdBy, imageTemplateName, imageTemplateResourceGroupName. Por padrão, a identidade atribuída ao recurso de modelo de imagem do Construtor de Imagens do Azure tem o RBAC “Colaborador” aplicado a ela no grupo de recursos.

Template deletion

Qualquer grupo de recursos de preparo criado pelo serviço do Construtor de Imagens será excluído após a exclusão do modelo de imagem. A exclusão inclui grupos de recursos de preparo que foram especificados na propriedade stagingResourceGroup, mas que não existiam antes da compilação da imagem.

Se o Construtor de Imagens não criou o grupo de recursos de preparo, mas criou recursos dentro dele, esses recursos serão excluídos depois que o modelo de imagem for excluído, desde que o serviço do Construtor de Imagens tenha as permissões ou a função apropriadas necessárias para excluir recursos.

Properties: validate

A propriedade validate pode ser usada para validar imagens de plataforma e quaisquer imagens personalizadas criadas, independentemente de ter usado o Construtor de Imagens do Azure para criá-las.

O Construtor de Imagens do Azure dá suporte a um modo "Source-Validation-Only" que pode ser definido usando a propriedade sourceValidationOnly. Se a propriedade sourceValidationOnly for definida como true, a imagem especificada na seção source será validada diretamente. Nenhuma compilação separada será executada para gerar e validar uma imagem personalizada.

A propriedade inVMValidations usa uma lista de validadores que serão executados na imagem. O Construtor de Imagens do Azure dá suporte a validadores do arquivo, do PowerShell e do Shell.

A propriedade continueDistributeOnFailure é responsável por saber se as imagens de saída serão distribuídas se a validação falhar. Por padrão, se a validação falhar e essa propriedade for definida como false, as imagens de saída não serão distribuídas. Se a validação falhar e essa propriedade for definida como true, as imagens de saída ainda serão distribuídas. Use essa opção com cuidado, pois pode resultar na distribuição para uso de imagens com falha. Em ambos os casos (true ou false), a execução de imagem de ponta a ponta será relatada como uma falha no caso de uma falha de validação. Essa propriedade não tem efeito sobre o sucesso ou não da validação.

Ao usar validate:

  • Você pode usar vários validadores.
  • Os validadores são executados na ordem especificada no modelo.
  • Se um validador falhar, o componente de validação inteiro falhará e relatará um erro.
  • É recomendável testar o script cuidadosamente antes de usá-lo em um modelo. A depuração do script em sua própria VM será mais fácil.
  • Não coloque dados confidenciais nos scripts.
  • The script locations need to be publicly accessible, unless you're using MSI.

Como usar a propriedade validate para validar imagens do Windows:

{
   "properties":{
      "validate":{
         "continueDistributeOnFailure":false,
         "sourceValidationOnly":false,
         "inVMValidations":[
            {
               "type":"File",
               "destination":"string",
               "sha256Checksum":"string",
               "sourceUri":"string"
            },
            {
               "type":"PowerShell",
               "name":"test PowerShell validator inline",
               "inline":[
                  "<command to run inline>"
               ],
               "validExitCodes":"<exit code>",
               "runElevated":"<true or false>",
               "runAsSystem":"<true or false>"
            },
            {
               "type":"PowerShell",
               "name":"<name>",
               "scriptUri":"<path to script>",
               "runElevated":"<true false>",
               "sha256Checksum":"<sha256 checksum>"
            }
         ]
      }
   }
}

inVMValidations Propriedades:

  • type – PowerShell.

  • name - name of the validator

  • scriptUri - URI of the PowerShell script file.

  • inline – array of commands to be run, separated by commas.

  • validExitCodes – Optional, valid codes that can be returned from the script/inline command, this avoids reported failure of the script/inline command.

  • runElevated – Optional, boolean, support for running commands and scripts with elevated permissions.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this locally, and then Image Builder will checksum and validate.

    To generate the sha256Checksum, using a PowerShell on Windows Get-Hash

Como usar a propriedade validate para validar imagens do Linux:

{
  "properties": {
    "validate": {
      "continueDistributeOnFailure": false,
      "sourceValidationOnly": false,
      "inVMValidations": [
        {
          "type": "Shell",
          "name": "<name>",
          "inline": [
            "<command to run inline>"
          ]
        },
        {
          "type": "Shell",
          "name": "<name>",
          "scriptUri": "<path to script>",
          "sha256Checksum": "<sha256 checksum>"
        },
        {
          "type": "File",
          "destination": "string",
          "sha256Checksum": "string",
          "sourceUri": "string"
        }
      ]
    }
  }
}

inVMValidations Propriedades:

  • type – Shell or File specified as the validation type to be performed.

  • name - name of the validator

  • scriptUri - URI of the script file

  • inline - array of commands to be run, separated by commas.

  • sha256Checksum - Value of sha256 checksum of the file, you generate this locally, and then Image Builder will checksum and validate.

    Para gerar a sha256Checksum, usando um terminal no Mac/Linux, execute: sha256sum <fileName>

  • destination - Destination of the file.

  • sha256Checksum - Specifies the SHA256 checksum of the file.

  • sourceUri - The source URI of the file.

Properties: vmProfile

vmSize (optional)

O Construtor de Imagens usa um tamanho de SKU padrão de Standard_D1_v2 para imagens de Gen1 e de Standard_D2ds_v4 para imagens de Gen2. A geração é definida pela imagem especificada no source. Você pode substituir vmSize por estes motivos:

  • Executar personalizações que exigem maior memória, CPU e manipulação de GBs (arquivos grandes).
  • Para executar builds do Windows, você deve usar "Standard_D2_v2" ou tamanho de VM equivalente.
  • Require VM isolation.
  • Personalize uma imagem que requer hardware específico. Por exemplo, para uma VM de GPU, você precisa de um tamanho de VM de GPU.
  • Require end to end encryption at rest of the build VM, you need to specify the support build VM size that doesn't use local temporary disks.

osDiskSizeGB

Por padrão, o Construtor de Imagens não altera o tamanho da imagem, ele usa o tamanho da imagem de origem. You can optionally only increase the size of the OS Disk (Win and Linux), and a value of 0 means leaving the same size as the source image. Não é possível reduzir o tamanho do disco do sistema operacional para menor do que o tamanho da imagem de origem.

{
  "osDiskSizeGB": 100
}

vnetConfig (optional)

Se você não especificar nenhuma propriedade da VNet, o Construtor de Imagens criará sua própria VNet, IP público e grupo de segurança de rede (NSG). O IP público é usado para que o serviço se comunique com a VM do build. Se você não quiser ter um IP público ou quiser que o Construtor de Imagens tenha acesso aos recursos da VNet existentes, como servidores de configuração (DSC, Chef, Puppet, Ansible), compartilhamentos de arquivos, você poderá especificar uma VNet. For more information, review the networking documentation.

"vnetConfig": {
  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName1>",
  "containerInstanceSubnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName2>",
  "proxyVmSize": "<vmSize>"
}

subnetId

ID de recurso de uma sub-rede pré-existente na qual a VM de build e a VM de validação são implantadas.

containerInstanceSubnetId (optional)

Resource ID of a pre-existing subnet on which Azure Container Instance (ACI) is deployed for Isolated Builds. Se esse campo não for especificado, uma Rede Virtual temporária, juntamente com sub-redes e Grupos de Segurança de Rede, será implantada no grupo de recursos de preparo, além de outros recursos de rede (Ponto de Extremidade Privado, Serviço de Link Privado, Azure Load Balancer e VM de Proxy) para habilitar a comunicação entre a ACI e a VM de build.

[Essa propriedade está disponível apenas em versões 2024-02-01 de API ou mais recentes, embora os modelos existentes criados usando versões anteriores da API possam ser atualizados para especificar essa propriedade.]

Este campo só pode ser especificado se subnetId também for especificado e deve atender aos seguintes requisitos:

  • Essa sub-rede deve estar na mesma Rede Virtual que a sub-rede especificada no subnetId.
  • Essa sub-rede não deve ser a mesma sub-rede especificada no subnetId.
  • Essa sub-rede deve ser delegada ao serviço da ACI para que possa ser usada para implantar recursos da ACI. You can read more about subnet delegation for Azure services here. ACI specific subnet delegation information is available here.
  • Essa sub-rede deve permitir acesso de saída à Internet e à sub-rede especificada no subnetId. Esses acessos são necessários para que a ACI possa ser provisionada e possa se comunicar com a VM de build para executar personalizações/validações. Na outra extremidade, a sub-rede especificada deve subnetId permitir o acesso de entrada dessa sub-rede. Em geral, as regras de segurança padrão dos NSGs (Grupos de Segurança de Rede) do Azure permitem esses acessos. No entanto, se você adicionar mais regras de segurança aos NSGs, os seguintes acessos ainda deverão ser permitidos:
    1. Acesso de saída da sub-rede especificada em containerInstanceSubnetId :
      1. Para a Internet na porta 443 (para provisionar a imagem do contêiner).
      2. Para a Internet na porta 445 (para montar o compartilhamento de arquivos do Armazenamento do Azure).
      3. Para a sub-rede especificada na subnetId porta 22 (para ssh/Linux) e na porta 5986 (para WinRM/Windows) (para conexão com a VM de build).
    2. Acesso de entrada à sub-rede especificada em subnetId:
      1. Para a porta 22 (para ssh/Linux) e a porta 5986 (para WinRM/Windows) da sub-rede especificada em containerInstanceSubnetId (para que a ACI se conecte à VM de compilação).
  • The template identity must have permission to perform 'Microsoft.Network/virtualNetworks/subnets/join/action' action on this subnet's scope. You can read more about Azure permissions for Networking here.

proxyVmSize (optional)

Tamanho da máquina virtual de proxy usada para passar o tráfego para a VM de build e a VM de validação. Esse campo não deve ser especificado se containerInstanceSubnetId for especificado porque nenhuma máquina virtual proxy é implantada nesse caso. Omita ou especifique uma cadeia de caracteres vazia para usar o padrão (Standard_A1_v2).

Properties: autoRun

Você pode usar a autoRun propriedade para controlar se o processo de criação do modelo de imagem deve ser iniciado automaticamente quando o modelo é criado. É uma enumeração com dois possíveis valores:

  • Enabled - Auto run is enabled, so your image template build process will automatically start when the template is created.
  • Disabled - Auto run is disabled, so you will have to manually start the image build process after the template is created.
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Note

When you set autoRun to "Enabled," the image build process runs once upon template creation. Ele garante que a construção inicial da imagem ocorra perfeitamente. No entanto, ele não fornece compilações de imagem consistentes e contínuas. Para builds de imagem consistentes e contínuos que são executados depois que um modelo de imagem é atualizado, consulte Como usar gatilhos do Construtor de Imagens do Azure para configurar um build de imagem automático.

Ao contrário autoRundo , a criação automática de imagens por meio do recurso de gatilho do Construtor de Imagens do Azure garante que as compilações de imagem ocorram de forma consistente. Sempre que houver alterações no modelo, o serviço Construtor de Imagens do Azure disparará automaticamente o processo de build da imagem.

Escolha autoRun para construções de imagem imediatas após a criação do modelo. Opte pela criação automática de imagens quando precisar de consistência contínua nas compilações de imagens. Considere seus requisitos específicos e use a opção apropriada com base em seu fluxo de trabalho.

Properties: managedResourceTags

Você pode usar a managedResourceTags propriedade para aplicar marcas aos recursos que o serviço Construtor de Imagens do Azure cria no grupo de recursos de preparo durante a compilação da imagem. Para obter mais informações sobre o grupo de recursos de preparo, consulte Visão geral do Construtor de Imagens do Azure

"properties": {
    "managedResourceTags": {
      "tag1": "value1",
            "tag2": "value2"
              }
}

Operações com modelos de imagem

Como iniciar uma build de imagem

Para iniciar uma build, você precisa invocar 'Run' no recurso de modelo de imagem, exemplos de comandos run:

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Run -Force

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

Cancelando uma build de imagem

Se você estiver executando uma build de imagem que parece incorreta, aguardando a entrada do usuário ou que nunca será concluída com êxito, você pode cancelar a build.

O build pode ser cancelado a qualquer momento. Se a fase de distribuição tiver começado, você ainda poderá cancelar, mas precisará limpar todas as imagens que talvez não tenham sido concluídas. The cancel command doesn't wait for cancel to complete, monitor lastrunstatus.runstate for canceling progress, using these status commands.

Exemplos de comandos cancel:

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2023-07-01" -Action Cancel -Force

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

Next steps

Há arquivos .json de exemplo para diferentes cenários no Construtor de Imagens do Azure no GitHub.

  • Last updated on