Compartilhar via

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

  • Artigo

Aplica-se a: ✔️ VMs Linux ✔️ VMs Windows ✔️ Conjuntos de dimensionamento flexíveis

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. Para conhecer as versões mais recentes da API, confira referência do modelo. 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>",
        ...
      ]
    }
  }
}

Versão da API

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 local é a região onde a imagem personalizada é criada. Há suporte para as seguintes áreas:

  • 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 Estados Unidos
  • Norte da Europa
  • Europa Ocidental
  • Sudeste da Ásia
  • Australia Southeast
  • Leste da Austrália
  • Sul do Reino Unido
  • Oeste do Reino Unido
  • Brazil South
  • Canadá Central
  • Índia Central
  • Centro dos EUA
  • 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
  • Leste da Ásia
  • 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

Importante

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).

Importante

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.

Para acessar a versão prévia pública do Construtor de Imagens de VM do Azure nas regiões do Azure Government (USGov Arizona e USGov Virginia), registre o recurso Microsoft.VirtualMachineImages/FairfaxPublicPreview. Para fazer isso, execute o seguinte comando no PowerShell ou na CLI do Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview

Para acessar a visualização pública do Construtor de Imagens de VM do Azure na região Norte da China 3, registre o recurso Microsoft.VirtualMachineImages/MooncakePublicPreview. Para fazer isso, execute o seguinte comando no PowerShell ou na CLI do Azure:

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name MooncakePublicPreview

"location": "<region>"

Residência de dadosResidência de dados

O serviço de Construtor de Imagens de VM do Azure não armazena nem processa dados do cliente fora de regiões que têm requisitos estritos de residência de dados de região única quando um cliente solicita um build nessa região. 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.

Redundância de zona

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

Marcas

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

Identidade

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.

Observação

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:

Propriedades: 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. Se você descobrir que está atingindo o tempo limite, examine os logs para ver se a etapa de personalização está aguardando algo, como uma entrada do usuário. 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.

Propriedades: personalizar

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 MSI.

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"
  }
]

Personalizador de Shell

O personalizador Shell dá suporte à execução de scripts de shell no Linux. Os scripts de shell devem ser acessíveis publicamente ou você deve ter configurado uma MSI para o Construtor de Imagens acessá-los.

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

Personalizar propriedades:

  • type – Shell.

  • name – nome para acompanhamento da personalização.

  • scriptUri – URI para o local do arquivo.

  • inline – matriz de comandos de shell separados por vírgulas.

  • sha256Checksum – valor da soma de verificação SHA256 do arquivo. Você gera esse valor localmente e, em seguida, o Construtor de Imagens faz a soma de verificação e a validação.

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

Observação

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"
  }
]

Personalizar propriedades:

  • Type: WindowsRestart.
  • restartCommand – comando para executar a reinicialização (opcional). O padrão é 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand – comando para verificar se a reinicialização foi bem-sucedida (opcional).
  • restartTimeout: tempo limite de reinicialização especificado como uma cadeia de caracteres de magnitude e unidade. Por exemplo, 5m (5 minutos) ou 2h (2 horas). O padrão é: 5m.

Observação

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

Personalizador do PowerShell

O personalizador PowerShell dá suporte à execução de scripts do PowerShell e ao comando embutido no Windows. Os scripts devem estar publicamente acessíveis para que o IB possa acessá-los.

"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>
  }
]

Personalizar propriedades:

  • type – PowerShell.

  • scriptUri – URI para o local do arquivo de script do PowerShell.

  • inline – comandos embutidos a serem executados, separados por vírgulas.

  • validExitCodes – códigos opcionais válidos que podem ser retornados do script/comando embutido. A propriedade evita a falha relatada do script/comando embutido.

  • runElevated – opcional, booliano, suporte para a execução de comandos e scripts com permissões elevadas.

  • runAsSystem - Opcional, booliano, determina se o script do PowerShell deve ser executado como o usuário do Sistema.

  • sha256Checksum - gere a soma de verificação SHA256 do arquivo localmente, atualize o valor da soma de verificação para minúscula e o Construtor de Imagens validará a soma de verificação durante a implantação do modelo de imagem.

    Para gerar o sha256Checksum, use o cmdlet Get-FileHash no PowerShell.

Personalizador de arquivo

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 – um ponto de extremidade de armazenamento acessível. Pode ser o GitHub ou o armazenamento do Azure. 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.

    Observação

    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. Consulte este exemplo para definir as permissões de armazenamento.

  • destination – o caminho de destino completo e o nome do arquivo. 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.

Observação

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 - gere a soma de verificação SHA256 do arquivo localmente, atualize o valor da soma de verificação para minúscula e o Construtor de Imagens validará a soma de verificação durante a implantação do modelo de imagem.

    Para gerar o sha256Checksum, use o cmdlet Get-FileHash no 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
  }
]

Propriedades do personalizador:

  • tipo – WindowsUpdate.
  • searchCriteria – opcional, define que tipo de atualizações são instaladas (como recomendado ou importante), BrowseOnly = 0 e IsInstalled = 0 (recomendado) é o padrão.
  • filters – opcional, permite que você especifique um filtro para incluir ou excluir atualizações.
  • updateLimit – opcional, define quantas atualizações podem ser instaladas. O padrão é 1.000.

Observação

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. Aconselhamos que você considere a adição de uma reinicialização do Windows e/ou permita que os aplicativos tenham tempo suficiente para concluir suas instalações, usando comandos de suspensão ou espere comandos embutidos ou scripts antes de executar Windows Update.

Generalizar

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. Confira solução de problemas sobre como coletar logs.

Propriedades: 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 – Especifica a ação a ser executada quando ocorre um erro durante a fase de criação de imagem do personalizador.
  • onValidationError – Especifica a ação a ser executada quando ocorre um erro durante a validação do modelo da imagem.

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

  • cleanup – Garante que os recursos temporários criados pelo Packer sejam limpos mesmo se o Packer ou uma das personalizações/validações encontrar um erro. Isso mantém a compatibilidade com versões anteriores com o comportamento atual.
  • abort – Caso o Packer encontre um erro, o serviço AIB (Construtor de Imagens do Azure) ignora a limpeza de recursos temporários. 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.

Propriedades: distribuição

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

  • ManagedImage – imagem gerenciada.
  • sharedImage - Galeria de Computação do Azure.
  • VHD – VHD em uma conta de armazenamento.

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

Observação

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

Saída:

{
  "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"
}

Distribuição: 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>"
  }
}

Propriedades de distribuição:

  • type – ManagedImage
  • imageId – ID do recurso da imagem de destino. Formato esperado: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • local – local da imagem gerenciada.
  • runOutputName – nome exclusivo para identificar a distribuição.
  • artifactTags – marcas opcionais de chave-valor especificadas pelo usuário.

Observação

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.

Distribuição: 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:

  • Galeria – contêiner para várias imagens. Uma galeria é implantada em uma região.
  • Definições de imagem – um agrupamento conceitual para imagens.
  • Versões de imagem – um tipo de imagem usado para implantar uma VM ou um conjunto de dimensionamento. 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.

Observação

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>"
  ]

Observação

replicationRegions foi preterido para distribuições de galerias, pois targetRegions é uma propriedade atualizada. Para saber mais, confira targetRegions.

Distribuir: 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 da Galeria de Computação do Azure, esta propriedade pode ser especificada em dois formatos:

    • 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 – nome exclusivo para identificar a distribuição.

  • artifactTags – marcas opcionais de chave-valor especificadas pelo usuário.

  • replicationRegions – matriz de regiões para replicação. 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 – uma matriz de regiões para replicação. Foi recentemente introduzido como parte da API 2022-07-01 e se aplica somente à distribuição do tipo SharedImage.

  • excludeFromLatest (opcional) – permite marcar a versão de imagem que você cria para que não seja usada como a versão mais recente na definição da galeria; o padrão é 'false'.

  • storageAccountType (opcional) – o AIB dá suporte à especificação desses tipos de armazenamento para a versão de imagem a ser criada:

    • "Standard_LRS"
    • "Standard_ZRS","

Observação

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

A propriedade controle de versão é apenas para o tipo de distribuição sharedImage. É uma enumeração com dois possíveis valores:

  • latest: ovo esquema estritamente crescente de acordo com o projeto
  • source: esquema baseado no número de versão da imagem de origem.

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 sob a qual gerar a versão mais recente.

Observação

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
        }
    ]

propriedades do controle de versão:

  • scheme: gera novo número de versão para distribuição. Latest ou Source são dois possíveis valores.
  • major: especifica a versão principal sob a qual gerar a versão mais recente. 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

Distribuir: 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 – nome exclusivo para identificar a distribuição.
  • tags – marcas opcionais de par de chave-valor especificadas pelo usuário.

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

Observação

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: URI de Armazenamento do Microsoft Azure opcional para o blob de VHD distribuído. 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.

Propriedades: otimizar

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: uma configuração relacionada ao processo de inicialização da máquina virtual (VM), usada para controlar otimizações que podem melhorar o tempo de inicialização ou outros aspectos de desempenho.
  • 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.

Propriedades: origem

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.

Observação

Ao usar imagens personalizadas existentes do Windows, você pode executar o comando Sysprep até três vezes em uma única imagem do Windows 7 ou Windows Server 2008 R2, ou 1001 vezes em uma única imagem do Windows para versões posteriores; para obter mais informações, confira a documentação do sysprep.

Origem da PlatformImage

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"
  }
}

Origem da ManagedImage

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

Observação

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.

Origem da SharedImageVersion

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

Observação

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.

Observação

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"
    }
},

Propriedades SharedImageVersion:

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.

Propriedades: 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.

Importante

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.

"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.

Importante

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.

Exclusão do modelo

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.

Propriedades: validar

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.
  • Os locais de script precisam ser acessíveis publicamente, a menos que você esteja usando 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 properties:

  • type – PowerShell.

  • name - nome do validador

  • scriptUri - URI do arquivo de script do PowerShell.

  • inline – matriz de comandos a serem executados, separados por vírgulas.

  • validExitCodes: códigos válidos e opcionais que podem ser retornados do comando script/embutido, o que evita a falha relatada do comando script/embutido.

  • runElevated – opcional, booliano, suporte para a execução de comandos e scripts com permissões elevadas.

  • sha256Checksum – valor da soma de verificação SHA256 do arquivo. Você o gera localmente e, em seguida, o Construtor de Imagens faz a soma de verificação e a validação.

    Para gerar o sha256Checksum, usando um PowerShell no 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 properties:

  • tipo: Shell ou Arquivo especificado como o tipo de validação a ser executada.

  • name - nome do validador

  • scriptUri - URI do arquivo de script

  • inline – matriz de comandos a serem executados, separados por vírgulas.

  • sha256Checksum – valor da soma de verificação SHA256 do arquivo. Você o gera localmente e, em seguida, o Construtor de Imagens faz a soma de verificação e a validação.

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

  • destination: destino do arquivo.

  • sha256Checksum: especifica a soma de verificação SHA256 do arquivo.

  • sourceUri: o URI de origem do arquivo.

Propriedades: vmProfile

vmSize (opcional)

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.
  • Exige isolamento da VM.
  • Personalize uma imagem que requer hardware específico. Por exemplo, para uma VM de GPU, você precisa de um tamanho de VM de GPU.
  • Exigir criptografia de ponta a ponta no restante da VM de compilação. Você precisa especificar o tamanho da VM de compilação de suporte que não usa discos temporários locais.

osDiskSizeGB

Por padrão, o Construtor de Imagens não altera o tamanho da imagem, ele usa o tamanho da imagem de origem. Você pode opcionalmente aumentar somenteo tamanho do Disco do SO (Win e Linux), e o valor 0 significa deixar o mesmo tamanho da imagem de origem. 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 (opcional)

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. Para obter mais informações, confira a documentação de rede.

"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 (opcional)

ID do recurso de uma sub-rede pré-existente na qual a ACI (Instância de Contêiner do Azure) é implantada para builds isolados. 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. Você pode ler mais sobre a delegação de sub-rede para serviços do Azure aqui. As informações de delegação de sub-rede específicas da ACI estão disponíveis aqui.
  • 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).
  • A identidade do modelo deve ter permissão para executar a ação 'Microsoft.Network/virtualNetworks/subnets/join/action' no escopo dessa sub-rede. Você pode ler mais sobre as permissões do Azure para rede aqui.

proxyVmSize (opcional)

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).

Propriedades: 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:

  • Habilitado - A execução automática está habilitada, portanto, o processo de criação do modelo de imagem será iniciado automaticamente quando o modelo for criado.
  • Desabilitado - A execução automática está desabilitada, portanto, você terá que iniciar manualmente o processo de criação da imagem após a criação do modelo.
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Observação

Quando você define autoRun como "Habilitado", o processo de criação da imagem é executado uma vez após a criação do modelo. 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.

Propriedades: 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. O comando cancelar não aguarda o cancelamento ser concluído, monitore o lastrunstatus.runstate para ver o progresso do cancelamento, usando estes comandosde status.

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

Próximas etapas

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