Partilhar via

Criar um modelo JSON do Azure Image Builder Bicep ou ARM

  • Artigo

Aplica-se a: ✔️ Linux VMs ✔️ Windows VMs ✔️ Conjuntos de escala flexível

O Azure Image Builder usa um arquivo Bicep ou um arquivo de modelo JSON de modelo ARM para passar informações para o serviço Construtor de Imagens. Neste artigo, vamos sobre as seções dos arquivos, para que você possa construir o seu próprio. Para obter as versões mais recentes da API, consulte a referência do modelo. Para ver exemplos de arquivos de .json completos, consulte o GitHub do Azure Image Builder.

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 mudando. Consulte O que há de novo no Construtor de Imagens de VM do Azure para obter todas as principais alterações de API e atualizações de recursos para o serviço Construtor de Imagens de VM do Azure.

Type

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. As seguintes regiões são suportadas:

  • E.U.A. Leste
  • E.U.A. Leste 2
  • E.U.A. Centro-Oeste
  • E.U.A. Oeste
  • E.U.A. Oeste 2
  • EUA Oeste 3
  • E.U.A. Centro-Sul
  • Europa do Norte
  • Europa Ocidental
  • Ásia Sudeste
  • Austrália Sudeste
  • Leste da Austrália
  • Sul do Reino Unido
  • Oeste do Reino Unido
  • Sul do Brasil
  • Canadá Central
  • Índia Central
  • E.U.A. Central
  • França Central
  • Alemanha Centro-Oeste
  • Leste do Japão
  • E.U.A. Centro-Norte
  • Leste da Noruega
  • Norte da Suíça
  • Jio, Oeste da Índia
  • Norte dos E.A.U.
  • Ásia Leste
  • Coreia do Sul Central
  • Norte da África do Sul
  • Catar Central
  • USGov Arizona (Pré-visualização Pública)
  • USGov Virgínia (Visualização Pública)
  • China Norte 3 (Visualização Pública)
  • Suécia Central
  • Polónia Central
  • Norte da Itália
  • Israel Central

Importante

Registre o recurso Microsoft.VirtualMachineImages/FairfaxPublicPreview para acessar a visualização pública do Azure Image Builder nas regiões do Azure Government (USGov Arizona e USGov Virginia).

Importante

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

Para acessar a visualização pública do Construtor de Imagens de VM do Azure nas regiões do Azure Government (USGov Arizona e USGov Virginia), você deve registrar 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 China Norte 3, você deve registrar 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 dados

O serviço Azure VM Image Builder não armazena nem processa dados de clientes fora de regiões que tenham requisitos estritos de residência de dados de região única quando um cliente solicita uma compilação nessa região. Se houver uma interrupção de serviço para regiões com requisitos de residência de dados, você precisará criar arquivos/modelos Bicep em uma região e geografia diferentes.

Redundância entre zonas

A distribuição dá suporte à redundância de zona, os VHDs são distribuídos para uma conta ZRS (Zone Redundant Storage) 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.

Etiquetas

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

Identidade

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

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

Obrigatório - Para que o Construtor de Imagens tenha permissões para ler/escrever imagens e ler em scripts do Armazenamento do Azure, tem de criar uma identidade atribuída pelo utilizador do Azure que tenha permissões para os recursos individuais. Para obter detalhes sobre como as permissões do Construtor de Imagens funcionam e etapas relevantes, consulte 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 ao serviço do Construtor de Imagens:

  • Suporta apenas uma única identidade.
  • Não suporta nomes de domínio personalizados.

Para saber mais, consulte O que são identidades gerenciadas para recursos do Azure?. Para obter mais informações sobre como implantar esse recurso, consulte 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 compilação do Image Builder

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

Opcional - A VM de compilação do Image Builder criada pelo serviço Image Builder em sua assinatura é usada para criar e personalizar a imagem. Para que a VM de Criação do Construtor de Imagens tenha permissões para autenticação com outros serviços, como o Azure Key Vault, na sua subscrição, tem de criar uma ou mais Identidades Atribuídas ao Utilizador do Azure que tenham permissões para os recursos individuais. O Construtor de Imagens do Azure pode então associar estas Identidades Atribuídas pelo Utilizador à VM de Compilação. Os scripts do personalizador executados dentro da VM de compilação podem, então, buscar tokens para essas identidades e interagir com outros recursos do Azure conforme necessário. Esteja ciente, a identidade atribuída ao usuário para o Azure Image Builder deve ter a atribuição de função "Operador de Identidade Gerenciado" em todas as identidades atribuídas ao usuário para que o Azure Image Builder possa associá-las à VM de compilação.

Nota

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

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

A identidade atribuída ao usuário da VM do Image Builder Build:

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

Para saber mais, veja:

Propriedades: buildTimeoutInMinutes

Duração máxima de espera durante a criaçã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, o valor padrão será usado, 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 de tempo limite é atingido (independentemente de a compilação da imagem estar 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 Windows, não recomendamos a configuração buildTimeoutInMinutes abaixo de 60 minutos. Se você achar que está atingindo o tempo limite, revise os logs para ver se a etapa de personalização está aguardando algo como a entrada do usuário. Se você achar que precisa de mais tempo para que as personalizações sejam concluídas, aumente o buildTimeoutInMinutes valor. Mas, não o defina muito alto, porque você pode ter que esperar que ele atinja o tempo limite antes de ver um erro.

Propriedades: personalizar

O Image Builder suporta vários "personalizadores", que são funções usadas para personalizar sua imagem, como executar scripts ou reinicializar servidores.

Ao utilizar customize:

  • Você pode usar vários personalizadores.
  • Os personalizadores executam na ordem especificada no modelo.
  • Se um personalizador falhar, todo o componente de personalização falhará e reportará um erro.
  • Teste os scripts completamente antes de usá-los em um modelo. Depurar os scripts por si só é mais fácil.
  • Não coloque dados confidenciais nos scripts. Os comandos embutidos podem ser visualizados na definição do modelo de imagem. Se você tiver informações confidenciais (incluindo senhas, token SAS, tokens de autenticação, etc.), elas deverão ser movidas para scripts no Armazenamento do Azure, onde o acesso requer autenticação.
  • Os locais de script precisam ser acessíveis publicamente, a menos que você esteja usando o MSI.

A customize seção é uma matriz. Os tipos de personalizador suportados são: File, 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 Shell personalizador suporta a execução de shell scripts no Linux. Os shell scripts devem ser acessíveis publicamente ou você deve ter configurado um MSI para o Image Builder 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 acompanhar a personalização.

  • scriptUri - URI para o local do arquivo.

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

  • sha256Checksum - Valor da soma de verificação sha256 do arquivo, você gera esse valor localmente e, em seguida, o Image Builder verificará a soma e validará.

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

Nota

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

Privilégios de superusuário

Prefira os comandos com sudo para executá-los com privilégios de superusuário. Você pode adicionar os comandos em scripts ou usá-los 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 WindowsRestart personalizador permite que você reinicie uma VM do Windows e aguarde a VM voltar a ficar online, esse personalizador permite que você instale o software que requer 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:

  • Tipo: WindowsRestart.
  • restartCommand - Comando para executar a reinicialização (opcional). A predefiniçã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 magnitude e unidade. Por exemplo, 5m (5 minutos) ou 2h (2 horas). O padrão é: 5m.

Nota

Não existe um personalizador de reinicialização do Linux.

Personalizador do PowerShell

O PowerShell personalizador suporta a execução de scripts do PowerShell e comando embutido no Windows, os scripts devem ser acessíveis publicamente para que o IB 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>
  }
]

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 e válidos que podem ser retornados a partir do comando script/inline. A propriedade evita falha relatada do comando script/inline.

  • runElevated – Opcional, booleano, suporte para executar comandos e scripts com permissões elevadas.

  • runAsSystem - Opcional, booleano, 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úsculas e o Image Builder 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 ficheiros

O File personalizador permite que o Image Builder baixe um arquivo de um repositório GitHub ou armazenamento do Azure. O personalizador suporta Linux e Windows. Se você tiver um pipeline de compilação de imagem que depende de artefatos de compilação, poderá definir o personalizador de arquivos para download do compartilhamento de compilação e mover os artefatos para a imagem.

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

Propriedades do personalizador de ficheiros:

  • sourceUri - um ponto de extremidade de armazenamento acessível, esse ponto de extremidade pode ser o armazenamento do GitHub ou 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 do Shell ou do PowerShell.

    Nota

    Se sourceUri for uma Conta de Armazenamento do Azure, independentemente se o blob estiver marcado como público, você precisará conceder permissões de Identidade de Usuário Gerenciado para acesso de leitura no blob. Consulte este exemplo para definir as permissões de armazenamento.

  • destino – o caminho de destino completo e o nome do arquivo. Qualquer caminho e subdiretórios referenciados devem existir, use os personalizadores do Shell ou do PowerShell para configurar esses caminhos com antecedência. Você pode usar os personalizadores de script para criar o caminho.

Este personalizador é suportado por diretórios Windows e caminhos Linux, mas existem algumas diferenças:

  • Linux – o único caminho em que o construtor de imagens pode escrever é /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.

Nota

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

  • sha256Checksum - gere a soma de verificação SHA256 do arquivo localmente, atualize o valor da soma de verificação para minúsculas e o Image Builder 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 atualização do Windows

O WindowsUpdate personalizador é criado na comunidade Windows Update Provisioner for Packer, que é um projeto de código aberto mantido pela comunidade Packer. A Microsoft testa e valida o provisionador com o serviço Image Builder e dará suporte à investigação de problemas com ele e trabalhará para resolver problemas, no entanto, o projeto de código aberto não é oficialmente suportado pela Microsoft. Para obter documentação detalhada e ajuda com o Windows Update Provisioner, consulte o repositório do projeto.

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

Propriedades do personalizador:

  • type – 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.
  • filtros – Opcional, permite especificar um filtro para incluir ou excluir atualizações.
  • updateLimit – Opcional, define quantas atualizações podem ser instaladas, padrão 1000.

Nota

O personalizador do Windows Update pode falhar se houver reinicializações pendentes do Windows ou instalações de aplicativos ainda em execução, normalmente você pode ver esse erro no customization.log, System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. É altamente recomendável que você considere adicionar uma Reinicialização do Windows e/ou permitir que os aplicativos tenham tempo suficiente para concluir suas instalações usando comandos de suspensão ou espera nos comandos ou scripts embutidos antes de executar o Windows Update.

Generalizar

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

Os comandos que os usuários do Construtor de Imagens generalizam podem não ser adequados para todas as situações, portanto, o Azure Image Builder permite que você personalize esse comando, se necessário.

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

Se o Azure Image Builder criar uma imagem personalizada do Windows com êxito e você criar uma VM a partir dela, descobrirá que a criação da VM falha ou não é concluída com êxito, você precisará revisar a documentação do Windows Server Sysprep ou gerar uma solicitação de suporte com a equipe de Suporte ao Serviço ao Cliente do Windows Server Sysprep, que poderá 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 de desprovisionamento padrão 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

Substituindo 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 colocá-los nos diretórios corretos:

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

O Image Builder lê esses comandos, esses comandos são gravados nos logs do AIB, customization.log. Consulte a solução de problemas sobre como coletar logs.

Propriedades: errorHandling

A errorHandling propriedade permite configurar como os erros são tratados durante a criação da imagem.

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

A errorHandling propriedade permite configurar 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 do personalizador de criação de imagem.
  • onValidationError - Especifica a ação a ser executada quando ocorre um erro durante a validação do modelo de imagem.

A errorHandling propriedade também tem dois valores possíveis para manipular 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 o comportamento existente.
  • abortar - Caso o Packer encontre um erro, o serviço Azure Image Builder (AIB) 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, que podem ajudar na investigação do erro encontrado pelo Packer.

Propriedades: distribuir

O Azure Image Builder 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.

Nota

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

Como você pode ter mais de um destino para distribuir, o Image Builder 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 a distribuição de postagem para obter informações sobre essa distribuição. Por exemplo, você pode consultar o local do VHD, ou regiões onde a versão da imagem foi replicada, ou a versão da imagem SIG criada. Esta é uma propriedade de cada alvo de distribuição. O runOutputName deve ser exclusivo para cada alvo de distribuição. Eis um exemplo para consultar 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"
}

Distribuir: managedImage

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

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

Distribuir propriedades:

  • tipo – ManagedImage
  • imageId – ID do recurso da imagem de destino, formato esperado: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • localização - localização da imagem gerida.
  • runOutputName – nome exclusivo para identificar a distribuição.
  • artifactTags - Tags chave\valor especificadas pelo usuário opcional.

Nota

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

Distribuir: sharedImage

A Galeria de Computação do Azure é um novo serviço de Gerenciamento de Imagens que permite gerenciar a replicação, o controle de versão e o compartilhamento de imagens personalizadas da região da imagem. O Azure Image Builder dá suporte à distribuição com esse serviço, para que você possa distribuir imagens para regiões suportadas pelas Galerias de Computação do Azure.

uma Galeria de Computação do Azure é composta por:

  • Galeria - Recipiente 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 escalas. As versões de imagem podem ser replicadas para outras regiões onde as VMs precisam ser implantadas.

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

Nota

A ID da versão da imagem precisa ser distinta ou diferente de quaisquer versões de imagem que estejam 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 replicationRegions campo para distribuir para uma Galeria de Computação do Azure.

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

Nota

replicationRegions é preterido para distribuições de galeria como targetRegions é propriedade atualizada. Para obter mais informações, consulte 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 Image Builder gera um número de versão monotônico para você, esta propriedade é útil para quando você deseja continuar reconstruindo imagens do 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 da versão que deseja que o construtor de imagens 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 - tags de chave\valor especificadas pelo usuário opcionais.

  • replicationRegions - matriz de regiões para replicação. Uma das regiões deve ser a região onde a Galeria está 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. Este campo foi preterido a partir da versão da API 2022-07-01, use targetRegions ao distribuir um tipo "SharedImage".

  • targetRegions - uma matriz de regiões para replicação. Ele foi recentemente introduzido como parte da API 2022-07-01 e se aplica apenas ao SharedImage tipo distribuir.

  • excludeFromLatest (opcional) - permite que você marque a versão da imagem que você criou não ser usada como a versão mais recente na definição da galeria, o padrão é 'false'.

  • storageAccountType (opcional) - O AIB suporta a especificação destes tipos de armazenamento para a versão da imagem a ser criada:

    • "Standard_LRS"
    • "Standard_ZRS","

Nota

Se o modelo de imagem e a referência image definition não estiverem no mesmo local, você verá tempo adicional para criar imagens. O Image Builder atualmente não tem um location parâmetro para o recurso de versão de imagem, nós o tiramos de seu pai image definition. 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, um recurso de versão de imagem em será criado e, em westus seguida, replicar para eastus. Para evitar o tempo adicional de replicação, verifique se o modelo e a image definition imagem estão no mesmo local.

Controle de versão

A propriedade versionamento é apenas para o sharedImage tipo distribuir. É um enum com dois valores possíveis:

  • mais recente - Novo esquema estritamente crescente por projeto
  • source - Esquema baseado no número da versão da imagem de origem.

O esquema de numeração de 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.

Nota

A lógica de geração de versão existente para sharedImage distribuição 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 da versão da imagem de origem. O enum que especifica o esquema de geração de versão permite a expansão no futuro com esquemas de geração de versão adicionais.

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

Propriedades de controle de versão:

  • scheme - Gerar novo número de versão para distribuição. Latest ou Source são dois valores possíveis.
  • major - Especifica a versão principal sob a qual gerar a versão mais recente. Aplicável apenas quando o scheme está 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 major não definido ou major definido como 2, o esquema gera a Latest versão 2.1.1
    • Com major definido como 1, o esquema mais recente gera a versão 1.2.1
    • Com major definido como 0, o esquema mais recente gera a versão 0.1.3

Distribuir: VHD

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

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

Suporte a SO: Windows e Linux

Distribuir parâmetros VHD:

  • tipo - VHD.
  • runOutputName – nome exclusivo para identificar a distribuição.
  • tags - Tags de par de valor de chave especificadas pelo usuário opcional.

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

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

Nota

Uma vez que o VHD tenha sido criado, copie-o para um local diferente, o mais rápido possível. O VHD é armazenado em uma conta de armazenamento no grupo de recursos temporários criado quando o modelo de imagem é enviado ao serviço Azure Image Builder. Se você excluir o modelo de imagem, perderá o VHD.

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

uri - URI de Armazenamento do Azure opcional para o blob VHD distribuído. Omitir o uso 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 optimize propriedade pode ser habilitada durante a criação de uma imagem de VM e permite a otimização de VM para melhorar 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 aspetos de desempenho.
  • state: O estado do recurso de otimização de inicialização no vmBoot, com o valor Enabled indicando que o recurso está ativado para melhorar o tempo de criação da imagem.

Para saber mais, consulte Otimização de VM para imagens de galeria com o Azure VM Image Builder.

Propriedades: fonte

A source seção contém informações sobre a imagem de origem que será usada pelo Image Builder. O Azure Image Builder suporta apenas imagens generalizadas como imagens de origem, não havendo suporte para imagens especializadas neste momento.

A API requer um SourceType que define a fonte para a construção da imagem, atualmente existem três tipos:

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

Nota

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, consulte a documentação do Sysprep .

PlataformaFonte da imagem

O Azure Image Builder suporta o Windows Server e o cliente, e imagens do Linux Azure Marketplace, consulte Saiba mais sobre o Azure Image Builder para obter a lista completa.

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

As propriedades aqui são as mesmas que são usadas para criar VMs, usando AZ CLI, execute o abaixo 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 a construção 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 o reenvio do modelo e executar novamente a compilação de imagem em intervalos, para que suas imagens sejam recriadas a partir das imagens mais recentes.

Suporte para informações do plano de mercado

Você também pode especificar informações do 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"
  }
}

Fonte ManagedImage

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

Nota

A imagem gerenciada de origem deve ser de um sistema operacional com suporte e a imagem deve residir na mesma assinatura e região que seu modelo do Azure Image Builder.

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

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

Fonte SharedImageVersion

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

Nota

A versão da imagem compartilhada de origem deve ser de um sistema operacional com suporte e a versão da imagem deve residir na mesma região do seu modelo do Azure Image Builder, 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 de modelo ARM da versão da imagem. Quando o nome da versão da imagem é 'mais recente', a versão é avaliada quando a compilação da imagem ocorre. O imageVersionId deve ser o ResourceId da versão da imagem. Use az sig image-version list para listar versões de imagem.

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

Nota

A Galeria Compartilhada Direta está atualmente em disponibilidade de visualização.

    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 de modelo ARM da versão da imagem. Quando o nome da versão da imagem é 'mais recente', a versão é avaliada quando a construção da imagem ocorre.

Propriedades: stagingResourceGroup

A stagingResourceGroup propriedade 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 compilação da imagem. A stagingResourceGroup é uma propriedade opcional para quem deseja mais controle sobre o grupo de recursos criado pelo Image Builder durante o processo de criação de imagem. Você pode criar seu próprio grupo de recursos e especificá-lo na seção ou fazer com que o stagingResourceGroup Image Builder crie um em seu nome.

Importante

O grupo de recursos de preparo especificado não pode ser associado a outro modelo de imagem, deve estar vazio (sem recursos dentro), na mesma região do modelo de imagem e ter RBAC "Colaborador" ou "Proprietário" aplicado à identidade atribuída ao recurso de modelo de imagem do Azure Image Builder.

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

Cenários de criação de modelos

  • A propriedade stagingResourceGroup é deixada vazia

    Se a stagingResourceGroup propriedade não for especificada ou especificada com uma cadeia de caracteres vazia, o serviço do 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 tags padrão aplicadas a ele: createdBy, imageTemplateName, imageTemplateResourceGroupName. Além disso, o RBAC padrão é aplicado à identidade atribuída ao recurso de modelo do Azure Image Builder, que é "Colaborador".

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

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

Importante

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

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

    Se a stagingResourceGroup propriedade 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 stagingResourceGroup propriedade. 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 tags padrão aplicadas a ele: createdBy, imageTemplateName, imageTemplateResourceGroupName. Por padrão, a identidade atribuída ao recurso de modelo de imagem do Azure Image Builder tem o RBAC "Colaborador" aplicado a ele no grupo de recursos.

Exclusão de modelo

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

Se o Construtor de Imagens não tiver criado o grupo de recursos de preparação, mas os recursos dentro do grupo de recursos, esses recursos serão excluídos depois que o modelo de imagem for excluído, dado que o serviço Construtor de Imagens tem as permissões ou a função apropriadas necessárias para excluir recursos.

Propriedades: validar

Você pode usar a propriedade para validar imagens da plataforma e quaisquer imagens personalizadas que criar, independentemente de ter usado o validate Azure Image Builder para criá-las.

O Azure Image Builder dá suporte a um modo 'Somente validação de origem' que pode ser definido usando a sourceValidationOnly propriedade. Se a sourceValidationOnly propriedade for definida como true, a imagem especificada na seção será validada source diretamente. Nenhuma compilação separada será executada para gerar e, em seguida, validar uma imagem personalizada.

A inVMValidations propriedade leva uma lista de validadores que serão executados na imagem. O Azure Image Builder dá suporte a validadores de Arquivo, PowerShell e Shell.

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

Ao utilizar validate:

  • Você pode usar vários validadores.
  • Os validadores são executados na ordem especificada no modelo.
  • Se um validador falhar, todo o componente de validação falhará e reportará um erro.
  • É aconselhável que você teste o script completamente antes de usá-lo em um modelo. Depurar o 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 o MSI.

Como usar a propriedade para validar imagens do validate 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.

  • nome - nome do validador

  • scriptUri - URI do arquivo de script do PowerShell.

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

  • validExitCodes – Opcional, códigos válidos que podem ser retornados a partir do comando script/inline, isso evita falhas relatadas do comando script/inline.

  • runElevated – Opcional, booleano, suporte para executar comandos e scripts com permissões elevadas.

  • sha256Checksum - Valor da soma de verificação sha256 do arquivo, você gera isso localmente e, em seguida, o Image Builder verificará a soma e validará.

    Para gerar o sha256Checksum, usando um PowerShell no Windows Get-Hash

Como usar a validate propriedade 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 ou File especificado como o tipo de validação a ser executado.

  • nome - 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ê gera isso localmente e, em seguida, o Image Builder verificará a soma e validará.

    Para gerar o 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 Image Builder usa um tamanho de SKU padrão para Standard_D1_v2 imagens Gen1 e Standard_D2ds_v4 para imagens Gen2. A geração é definida pela imagem especificada no source. Você pode substituir vmSize pelos seguintes motivos:

  • Realizar personalizações que exigem maior memória, CPU e manipulação de arquivos grandes (GBs).
  • Executando compilações do Windows, você deve usar "Standard_D2_v2" ou tamanho de VM equivalente.
  • Exigir isolamento de VM.
  • Personalize uma imagem que requer hardware específico. Por exemplo, para uma VM GPU, você precisa de um tamanho de VM 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 Image Builder não altera o tamanho da imagem, ele usa o tamanho da imagem de origem. Opcionalmente , você só pode aumentar o tamanho do disco do sistema operacional (Win e Linux), e um valor de 0 significa deixar o mesmo tamanho da imagem de origem. Não é possível reduzir o tamanho do disco do SO para menor do que o tamanho da imagem de origem.

{
  "osDiskSizeGB": 100
}

vnetConfig (opcional)

Se você não especificar nenhuma propriedade de rede virtual, o Construtor de Imagens criará sua própria rede virtual, IP público e NSG (grupo de segurança de rede). O IP público é usado para que o serviço se comunique com a VM de compilação. Se você não quiser ter um IP público ou quiser que o Image Builder tenha acesso aos recursos de rede virtual existentes, como servidores de configuração (DSC, Chef, Puppet, Ansible), compartilhamentos de arquivos, especifique uma rede virtual. Para obter mais informações, consulte a documentação da 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 compilação e a VM de validação são implantadas.

containerInstanceSubnetId (opcional)

ID de recurso de uma sub-rede pré-existente na qual a Instância de Contêiner do Azure (ACI) é implantada para Compilações Isoladas. 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, Balanceador de Carga do Azure e VM de Proxy) para habilitar a comunicação entre a ACI e a VM de compilação.

[Esta propriedade só está disponível 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 satisfazer os seguintes requisitos:

  • Essa sub-rede deve estar na mesma rede virtual que a sub-rede especificada em subnetId.
  • Esta sub-rede não deve ser a mesma sub-rede especificada em subnetId.
  • Essa sub-rede deve ser delegada ao serviço ACI para que possa ser usada para implantar recursos ACI. Você pode ler mais sobre delegação de sub-rede para serviços do Azure aqui. As informações sobre a delegação de sub-redes específicas do ACI estão disponíveis aqui.
  • Esta sub-rede deve permitir o acesso de saída à Internet e à sub-rede especificada em subnetId. Esses acessos são necessários para que o ACI possa ser provisionado e possa se comunicar com a VM de compilação para executar personalizações/validações. Na outra extremidade, a sub-rede especificada em subnetId deve permitir o acesso de entrada a partir 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 seus 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 montagem de partilha de ficheiros a partir do Armazenamento do Azure).
      3. Para a sub-rede especificada na porta 22 (para ssh/Linux) e na subnetId porta 5986 (para WinRM/Windows) (para conexão com a VM de compilação).
    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 ACI se conectar à 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 proxy usada para passar o tráfego para a VM de compilação e a VM de validação. Este campo não deve ser especificado se containerInstanceSubnetId for especificado porque nenhuma máquina virtual proxy é implantada nesse caso. Omita ou especifique a 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 compilação do modelo de imagem deve ser iniciado automaticamente quando o modelo é criado. É um enum com dois valores possíveis:

  • Ativado - A execução automática está ativada, pelo que o processo de criação do modelo de imagem será iniciado automaticamente quando o modelo for criado.
  • Desativado - A execução automática está desativada, então você terá que iniciar manualmente o processo de construção da imagem depois que o modelo for criado.
"properties": {
    "autoRun": {
        "state": "Enabled"
    }
 }

Nota

Quando você define autoRun como "Habilitado", o processo de construçã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 compilações de imagem consistentes e contínuas que são executadas depois que um modelo de imagem é atualizado, consulte Como usar gatilhos do Azure Image Builder para configurar uma compilação automática de imagem.

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

Escolha autoRun por imagens imediatas baseadas na criação de modelos. 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 Azure Image Builder cria no grupo de recursos de preparo durante a compilação da imagem. Para obter mais informações sobre o grupo de recursos de preparação, consulte Visão geral do Azure Image Builder

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

Operações de modelo de imagem

Iniciando uma compilação de imagem

Para iniciar uma compilação, você precisa invocar 'Executar' no recurso Modelo de Imagem, exemplos de run comandos:

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 compilação de imagem

Se você estiver executando uma compilação de imagem que você acredita estar incorreta, aguardando a entrada do usuário, ou você sente que nunca será concluída com êxito, então você pode cancelar a compilação.

A compilação pode ser cancelada a qualquer momento. Se a fase de distribuição tiver começado, você ainda poderá cancelar, mas precisará limpar as imagens que podem não ser concluídas. O comando cancel não espera que cancel seja concluído, monitore lastrunstatus.runstate o cancelamento do progresso, usando esses comandos de status.

Exemplos de cancel comandos:

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óximos passos

Há arquivos de .json de exemplo para diferentes cenários no GitHub do Azure Image Builder.