Criar um modelo do Bicep do Azure Image Builder ou do ARM JSON

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

O Azure Image Builder utiliza um ficheiro Bicep ou um ficheiro de modelo JSON do ARM para transmitir informações para o serviço Construtor de Imagens. Neste artigo, vamos ver as secções dos ficheiros, para que possa criar os seus próprios ficheiros. Para obter as versões mais recentes da API, veja Referência de modelos. Para ver exemplos de ficheiros .json completos, veja GitHub do Azure Image Builder.

O formato básico é:

{
  "type": "Microsoft.VirtualMachineImages/imageTemplates",
  "apiVersion": "2022-02-14",
  "location": "<region>",
  "tags": {
    "<name>": "<value>",
    "<name>": "<value>"
  },
  "identity": {},
  "properties": {
    "buildTimeoutInMinutes": <minutes>,
    "customize": [],
    "distribute": [],
    "source": {},
    "stagingResourceGroup": "/subscriptions/<subscriptionID>/resourceGroups/<stagingResourceGroupName>",
    "validate": {},
    "vmProfile": {
      "vmSize": "<vmSize>",
      "proxyVmSize": "<vmSize>",
      "osDiskSizeGB": <sizeInGB>,
      "vnetConfig": {
        "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>"
      },
      "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>",
        ...
      ]
    }
  }
}

Tipo e versão da API

É type o tipo de recurso, que tem de ser Microsoft.VirtualMachineImages/imageTemplates. O apiVersion irá mudar ao longo do tempo à medida que a API muda. Veja Novidades no Construtor de Imagens da VM do Azure para todas as principais alterações de API e atualizações de funcionalidades do serviço Azure VM Image Builder.

"type": "Microsoft.VirtualMachineImages/imageTemplates",
"apiVersion": "2022-02-14",

Localização

A localização é a região onde a imagem personalizada será criada. São suportadas as seguintes regiões:

  • 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 Virginia (Pré-visualização Pública)

Importante

Registe a funcionalidade Microsoft.VirtualMachineImages/FairfaxPublicPreview para aceder à pré-visualização pública do Azure Image Builder em regiões Azure Government (USGov Arizona e USGov Virginia).

Utilize o seguinte comando para registar a funcionalidade do Azure Image Builder em regiões Azure Government (USGov Arizona e USGov Virginia).

Register-AzProviderPreviewFeature -ProviderNamespace Microsoft.VirtualMachineImages -Name FairfaxPublicPreview
"location": "<region>"

Residência dos dados

O serviço Azure VM Image Builder não armazena nem processa dados de clientes fora de regiões que tenham requisitos rigorosos de residência de dados de região única quando um cliente pede uma compilação nessa região. Se ocorrer uma indisponibilidade do serviço para regiões que têm requisitos de residência dos dados, terá de criar ficheiros/modelos bicep numa região e geografia diferentes.

Redundância entre zonas

A distribuição suporta redundância entre zonas, os VHDs são distribuídos por predefinição para uma conta de Armazenamento Com Redundância entre Zonas (ZRS) e a versão da Galeria de Computação do Azure (anteriormente conhecida como Shared Image Gallery) suportará um tipo de armazenamento ZRS, se especificado.

Etiquetas

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

Identidade

Existem duas formas de adicionar identidades atribuídas pelo utilizador abaixo.

Identidade atribuída pelo utilizador 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 funcionam as permissões do Construtor de Imagens e os passos relevantes, veja Criar uma imagem e utilizar uma identidade gerida atribuída pelo utilizador para aceder a ficheiros numa conta de armazenamento do Azure.

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

Identidade Atribuída pelo Utilizador do serviço Image Builder:

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

Para saber mais, veja O que são identidades geridas para recursos do Azure?. Para obter mais informações sobre como implementar esta funcionalidade, veja Configurar identidades geridas para recursos do Azure numa VM do Azure com a CLI do Azure.

Identidade atribuída pelo utilizador para a VM de Compilação do Construtor de Imagens

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

Opcional – a VM de Compilação do Construtor de Imagens, criada pelo serviço Construtor de Imagens na sua subscrição, é utilizada para criar e personalizar a imagem. Para que a VM de Compilação do Construtor de Imagens tenha permissões para autenticar com outros serviços, como o Azure Key Vault na sua subscrição, tem de criar uma ou mais Identidades Atribuídas pelo Utilizador do Azure que tenham permissões para os recursos individuais. Em seguida, o Azure Image Builder pode associar estas Identidades Atribuídas pelo Utilizador à VM de Compilação. Os scripts de personalizador em execução na VM de Compilação podem, em seguida, obter tokens para estas identidades e interagir com outros recursos do Azure, conforme necessário. Tenha em atenção que a identidade atribuída pelo utilizador para o Azure Image Builder tem de ter a atribuição de função "Operador de Identidade Gerida" em todas as identidades atribuídas pelo utilizador ao Azure Image Builder para poder associá-las à VM de compilação.

Nota

Tenha em atenção que podem ser especificadas múltiplas identidades para a VM de Compilação do Construtor de Imagens, incluindo a identidade que criou para o recurso de modelo de imagem. Por predefinição, a identidade que criou 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 pelo Utilizador da VM de Compilação do Construtor de Imagens:

  • Suporta uma lista de uma ou mais identidades geridas atribuídas pelo utilizador a configurar na VM.
  • Suporta cenários entre subscrições (identidade criada numa subscrição enquanto o modelo de imagem é criado noutra subscrição no mesmo inquilino).
  • Não suporta cenários entre inquilinos (identidade criada num inquilino enquanto o modelo de imagem é criado noutro inquilino).

Para saber mais, veja:

Propriedades: buildTimeoutInMinutes

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

Se não especificar a propriedade ou definir o valor como 0, é utilizado o valor predefinido, que é 240 minutos ou quatro horas. O valor mínimo é 6 minutos e o valor máximo é 960 minutos ou 16 horas. Quando o valor de tempo limite for atingido (se a compilação da imagem estiver ou não concluída), 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 dos 60 minutos. Se descobrir que está a atingir o tempo limite, reveja os registos para ver se o passo de personalização está à espera de algo como a entrada do utilizador. Se precisar de mais tempo para concluir as personalizações, aumente o buildTimeoutInMinutes valor. No entanto, não o defina muito alto porque poderá ter de esperar que o tempo limite seja excedido antes de ver um erro.

Propriedades: personalizar

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

Ao utilizar customize:

  • Pode utilizar vários personalizadores.
  • Os personalizadores são executados pela ordem especificada no modelo.
  • Se um personalizador falhar, todo o componente de personalização irá falhar e comunicar um erro.
  • Teste os scripts cuidadosamente antes de os utilizar num modelo. A depuração dos scripts por si só é mais fácil.
  • Não coloque dados confidenciais nos scripts. Os comandos inline podem ser visualizados na definição do modelo de imagem. Se tiver informações confidenciais (incluindo palavras-passe, token de SAS, tokens de autenticação, etc.), estas deverão ser movidas para scripts no Armazenamento do Microsoft Azure, onde o acesso requer autenticação.
  • As localizações do script têm de estar acessíveis publicamente, a menos que esteja a utilizar o MSI.

A customize secção é uma matriz. Os tipos de personalizador suportados são: Ficheiro, 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 scripts de shell no Linux. Os scripts da shell têm de estar acessíveis publicamente ou tem de ter configurado um MSI para o Construtor de Imagens aceder aos mesmos.

"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 controlar a personalização.

  • scriptUri - URI para a localização do ficheiro.

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

  • sha256Checksum - Valor da soma de verificação sha256 do ficheiro, gera este valor localmente e, em seguida, o Construtor de Imagens irá fazer a soma de verificação e validar.

    Para gerar o sha256Checksum, utilize um terminal em execução no Mac/Linux: sha256sum <fileName>

Nota

Os comandos inline são armazenados como parte da definição do modelo de imagem. Pode vê-los ao eliminar a definição de imagem. Se tiver comandos ou valores confidenciais (incluindo palavras-passe, token de SAS, tokens de autenticação, etc.), recomenda-se que estes sejam movidos para scripts e utilize uma identidade de utilizador para autenticar no Armazenamento do Microsoft Azure.

Privilégios de superutilizador

Prefixe os comandos com sudo para executá-los com privilégios de superutilizador. Pode adicionar os comandos em scripts ou utilizá-lo em comandos inline, por exemplo:

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

Exemplo de um script com sudo que pode referenciar com 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 reinício do Windows

O WindowsRestart personalizador permite-lhe reiniciar uma VM do Windows e aguardar que a VM volte a ficar online. Este personalizador permite-lhe instalar software que requer um reinício.

"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 o reinício (opcional). A predefinição é 'shutdown /r /f /t 0 /c \"packer restart\"'.
  • restartCheckCommand – Comando para verificar se o reinício foi concluído com êxito (opcional).
  • restartTimeout - Tempo limite de reinício especificado como uma cadeia de magnitude e unidade. Por exemplo, 5m (5 minutos) ou 2h (2 horas). A predefinição é: 5m.

Nota

Não existe nenhum personalizador de reinício do Linux.

Personalizador do PowerShell

O personalizador suporta a execução de scripts do PowerShell e o comando inline no Windows. Os PowerShell scripts têm de estar acessíveis publicamente para que o IB lhes aceda.

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

Personalizar propriedades:

  • type – PowerShell.

  • scriptUri - URI para a localização do ficheiro de script do PowerShell.

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

  • validExitCodes – códigos opcionais e válidos que podem ser devolvidos a partir do comando script/inline. A propriedade evita a falha reportada do script/comando inline.

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

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

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

Personalizador de ficheiros

O File personalizador permite que o Image Builder transfira um ficheiro a partir de um repositório do GitHub ou do armazenamento do Azure. O personalizador suporta o Linux e o Windows. Se tiver um pipeline de compilação de imagens que depende de artefactos de compilação, pode definir o personalizador de ficheiros para transferir a partir da partilha de compilação e mover os artefactos para a imagem.

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

Propriedades do personalizador de ficheiros:

  • sourceUri – um ponto final de armazenamento acessível, este ponto final pode ser o GitHub ou o armazenamento do Azure. Só pode transferir um ficheiro, não um diretório inteiro. Se precisar de transferir um diretório, utilize um ficheiro comprimido e, em seguida, descomprima-o com os personalizadores do Shell ou do PowerShell.

    Nota

    Se o sourceUri for uma Conta de Armazenamento do Azure, independentemente de o blob estar marcado como público, terá de conceder as permissões de Identidade de Utilizador Gerida para ler o acesso no blob. Veja este exemplo para definir as permissões de armazenamento.

  • destination – o caminho de destino completo e o nome do ficheiro. Qualquer caminho e subdiretórios referenciados têm de existir, utilize os personalizadores do Shell ou do PowerShell para configurar previamente estes caminhos. Pode utilizar os personalizadores de scripts para criar o caminho.

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

  • Linux – o único caminho no qual o Construtor de imagens pode escrever é /tmp.
  • Windows – sem restrição de caminho, mas o caminho tem de existir.

Se ocorrer um erro ao tentar transferir o ficheiro ou colocá-lo num diretório especificado, o passo de personalização falhará e este erro estará no ficheiro customization.log.

Nota

O personalizador de ficheiros só é adequado para transferências de ficheiros pequenos, < 20 MB. Para transferências de ficheiros maiores, utilize um script ou um comando inline e, em seguida, utilize código para transferir ficheiros, como Linux wget ou curl, Windows, Invoke-WebRequest. Para ficheiros que estão no armazenamento do Azure, certifique-se de que atribui uma identidade com permissões para ver esse ficheiro na VM de compilação ao seguir a documentação aqui: Identidade Atribuída pelo Utilizador para a VM de Compilação do Construtor de Imagens. Qualquer ficheiro que não esteja armazenado no Azure tem de estar acessível publicamente para que o Azure Image Builder possa transferi-lo.

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

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

Personalizador do Windows Update

O WindowsUpdate personalizador baseia-se na comunidade Windows Update Provisioner for Packer, que é um projeto open source mantido pela comunidade Packer. A Microsoft testa e valida o aprovisionador com o serviço Construtor de Imagens e irá suportar a investigação de problemas com o mesmo e trabalhar para resolver problemas, no entanto o projeto open source não é oficialmente suportado pela Microsoft. Para obter documentação detalhada sobre e ajudar com o Aprovisionador de Windows Update, veja 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 estão instaladas (como Recomendado ou Importante), BrowseOnly=0 e IsInstalled=0 (Recomendado) é a predefinição.
  • filtros – opcional, permite-lhe especificar um filtro para incluir ou excluir atualizações.
  • updateLimit – opcional, define quantas atualizações podem ser instaladas, predefinição 1000.

Nota

O Windows Update personalizador pode falhar se existirem reinícios pendentes do Windows ou instalações de aplicações ainda em execução, normalmente poderá ver este erro no customization.log, System.Runtime.InteropServices.COMException (0x80240016): Exception from HRESULT: 0x80240016. Recomendamos vivamente que considere adicionar um Reinício do Windows e/ou permitir às aplicações tempo suficiente para concluir as instalações com comandos de suspensão ou espera nos comandos ou scripts inline antes de executar Windows Update.

Generalizar

Por predefinição, o Azure Image Builder também executará deprovision código no final de cada fase de personalização de imagens, 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 Azure Image Builder utiliza o Sysprep. Para Linux, o Azure Image Builder executa waagent -deprovision.

Os comandos que os utilizadores do Image Builder para generalizar podem não ser adequados para todas as situações, pelo que o Azure Image Builder irá permitir-lhe personalizar este comando, se necessário.

Se estiver a migrar a personalização existente e estiver a utilizar diferentes comandos Sysprep/waagent, pode utilizar os comandos genéricos do Construtor de Imagens e, se a criação da VM falhar, utilize os seus próprios comandos Sysprep ou waagent.

Se o Azure Image Builder criar uma imagem personalizada do Windows com êxito e criar uma VM a partir da mesma, verifique se a criação da VM falha ou não é concluída com êxito, terá de rever a documentação do Windows Server Sysprep ou criar um pedido de suporte com a equipa de Suporte aos Serviços de Clientes do Windows Server Sysprep, que pode resolver problemas e aconselhar sobre a utilização correta do Sysprep.

Comando Sysprep predefinido

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 }
Write-Output '>>> Sysprepping VM ...'
if( Test-Path $Env:SystemRoot\system32\Sysprep\unattend.xml ) {
  Remove-Item $Env:SystemRoot\system32\Sysprep\unattend.xml -Force
}
& $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 desaprovisionamento do Linux predefinido

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

Substituir os Comandos

Para substituir os comandos, utilize os aprovisionadores de scripts do PowerShell ou shell para criar os ficheiros de comando com o nome de ficheiro exato e colocá-los nos diretórios corretos:

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

O Construtor de Imagens irá ler estes comandos, estes comandos são escritos nos registos do AIB, customization.log. Veja a resolução de problemas sobre como recolher registos.

Propriedades: distribuir

O Azure Image Builder suporta três destinos de distribuição:

  • managedImage - imagem gerida.
  • sharedImage - Galeria de Computação do Azure.
  • VHD – VHD numa conta de armazenamento.

Pode distribuir uma imagem por ambos os tipos de destino na mesma configuração.

Nota

O comando predefinido do AIB sysprep não inclui "/mode:vm", no entanto, esta propriedade talvez seja necessária quando criar imagens que terão a função HyperV instalada. Se precisar de adicionar este argumento de comando, tem de substituir o comando sysprep.

Uma vez que pode ter mais do que um destino para distribuir, o Construtor de Imagens mantém um estado para cada destino de distribuição que pode ser acedido consultando o runOutputName. É runOutputName um objeto que pode consultar após a distribuição para obter informações sobre essa distribuição. Por exemplo, pode consultar a localização do VHD ou regiões para as quais a versão da imagem foi replicada ou a versão da Imagem SIG criada. Esta é uma propriedade de cada destino de distribuição. O runOutputName tem de ser exclusivo para cada destino 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=2021-10-01

Resultado:

{
  "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 da imagem será um recurso de imagem gerida.

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

Distribuir propriedades:

  • type – managedImage
  • imageId – ID de recurso da imagem de destino, formato esperado: /subscriptions/<subscriptionId>/resourceGroups/<destinationResourceGroupName>/providers/Microsoft.Compute/images/<imageName>
  • location - localização da imagem gerida.
  • runOutputName – nome exclusivo para identificar a distribuição.
  • artifactTags – etiquetas chave\valor especificadas pelo utilizador opcional.

Nota

O grupo de recursos de destino tem de existir. Se quiser que a imagem seja distribuída para uma região diferente, aumentará o tempo de implementação.

Distribuir: sharedImage

A Galeria de Computação do Azure é um novo serviço de Gestão de Imagens que permite gerir a replicação da região de imagem, o controlo de versões e a partilha de imagens personalizadas. O Azure Image Builder suporta a distribuição com este serviço, para que possa distribuir imagens por regiões suportadas pelas Galerias de Computação do Azure.

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

  • Galeria - Contentor para múltiplas imagens. Uma galeria é implementada numa região.
  • Definições de imagem – um agrupamento conceptual para imagens.
  • Versões de imagem – um tipo de imagem utilizado para implementar uma VM ou um conjunto de dimensionamento. As versões de imagem podem ser replicadas para outras regiões onde as VMs precisam de ser implementadas.

Antes de poder distribuir para a galeria, tem de criar uma galeria e uma definição de imagem, consulte Criar uma galeria.

{
  "type": "SharedImage",
  "galleryImageId": "<resource ID>",
  "runOutputName": "<name>",
  "artifactTags": {
      "<name>": "<value>",
      "<name>": "<value>"
  },
  "replicationRegions": [
      "<region where the gallery is deployed>",
      "<region>"
  ]
}

Distribuir propriedades para galerias:

  • type - sharedImage

  • galleryImageId – ID da Galeria de Computação do Azure, esta propriedade pode ser especificada em dois formatos:

    • Controlo de versões automático – o Construtor de Imagens irá gerar um número de versão monotónico para si. Esta propriedade é útil para quando pretende continuar a reconstruir imagens a partir do mesmo modelo: o formato é: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroupName>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageGalleryName>.
    • Controlo de versões explícito – pode transmitir o número da versão que pretende que o construtor de imagens utilize. 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 - etiquetas chave\valor especificadas pelo utilizador opcional.

  • replicationRegions - matriz de regiões para replicação. Uma das regiões tem de ser a região onde a Galeria é implementada. Adicionar regiões significará um aumento do tempo de compilação, uma vez que a compilação não é concluída até que a replicação esteja concluída.

  • excludeFromLatest (opcional) - permite-lhe marcar a versão da imagem que criar não ser utilizada como a versão mais recente na definição da galeria, a predefinição é "falso".

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

    • "Standard_LRS"
    • "Standard_ZRS"","

Nota

Se o modelo de imagem e referenciado image definition não estiverem na mesma localização, verá tempo adicional para criar imagens. Atualmente, o Construtor de Imagens não tem um location parâmetro para o recurso da versão da imagem. Vamos retirá-lo do respetivo principal image definition. Por exemplo, se uma definição de imagem estiver em westus e quiser que a versão da imagem seja replicada para eastus, é copiado um blob para westus, é criado um recurso de versão de imagem no e, em westus seguida, replica para eastus. Para evitar o tempo adicional de replicação, certifique-se de que o image definition modelo e imagem estão na mesma localização.

Distribuir: VHD

Pode exportar para um VHD. Em seguida, pode copiar o VHD e utilizá-lo para publicar no Azure MarketPlace ou utilizar com o Azure Stack.

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

Suporte do SO: Windows e Linux

Distribuir parâmetros VHD:

  • type - VHD.
  • runOutputName – nome exclusivo para identificar a distribuição.
  • tags - Etiquetas de par de valores de chave especificadas pelo utilizador opcional.

O Azure Image Builder não permite que o utilizador especifique uma localização da conta de armazenamento, mas pode consultar o estado do runOutputs para obter a localização.

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

Nota

Assim que o VHD tiver sido criado, copie-o para uma localização diferente, o mais rapidamente possível. O VHD é armazenado numa conta de armazenamento no grupo de recursos temporário criado quando o modelo de imagem é submetido para o serviço Azure Image Builder. Se eliminar o modelo de imagem, perderá o VHD.

Propriedades: origem

A source secção contém informações sobre a imagem de origem que serão utilizadas pelo Construtor de Imagens. O Azure Image Builder só suporta imagens generalizadas como imagens de origem. Neste momento, as imagens especializadas não são suportadas.

A API requer um SourceType que defina a origem da compilação da imagem, atualmente existem três tipos:

  • PlatformImage – indica que a imagem de origem é uma imagem do Marketplace.
  • ManagedImage - utilizado quando começa a partir de uma imagem gerida normal.
  • SharedImageVersion - utilizado quando está a utilizar uma versão de imagem numa Galeria de Computação do Azure como a origem.

Nota

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

Origem PlatformImage

O Azure Image Builder suporta o Windows Server e o cliente e o Linux Azure Marketplace imagens, veja 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 utilizadas para criar VMs, com a CLI do AZ, executam as seguintes para obter as propriedades:

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

Pode utilizar latest na versão, a versão é avaliada quando a compilação da imagem ocorre, não quando o modelo é submetido. Se utilizar esta funcionalidade com o destino da Galeria de Computação do Azure, pode evitar voltar a submeter o modelo e voltar a executar a compilação da imagem em intervalos, para que as imagens sejam recriadas a partir das imagens mais recentes.

Suporte para informações do plano de mercado

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

Origem ManagedImage

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

Nota

A imagem gerida de origem tem de ser de um SO suportado e a imagem tem de residir na mesma subscrição e região que o modelo do Azure Image Builder.

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

Deve imageId ser o ResourceId da imagem gerida. Utilize para listar az image list imagens disponíveis.

Origem sharedImageVersion

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

Nota

A versão da imagem partilhada de origem tem de ser de um SO suportado e a versão da imagem tem de residir na mesma região que o modelo do Azure Image Builder, caso contrário, replicar a versão da imagem para a região Modelo do Construtor de Imagens.

"source": {
  "type": "SharedImageVersion",
  "imageVersionID": "/subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>/providers/Microsoft.Compute/galleries/<sharedImageGalleryName>/images/<imageDefinitionName/versions/<imageVersion>"
}

Deve imageVersionId ser o ResourceId da versão da imagem. Utilize az sig image-version list para listar versões de imagens.

Propriedades: stagingResourceGroup

A stagingResourceGroup propriedade contém informações sobre o grupo de recursos de teste que o serviço Construtor de Imagens irá criar para utilização durante o processo de compilação da imagem. É stagingResourceGroup uma propriedade opcional para qualquer pessoa que pretenda ter mais controlo sobre o grupo de recursos criado pelo Construtor de Imagens durante o processo de compilação da imagem. Pode criar o seu próprio grupo de recursos e especificá-lo na secção ou fazer com que o stagingResourceGroup Construtor de Imagens crie um em seu nome.

"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 vazia, o serviço Construtor de Imagens criará um grupo de recursos de teste com a convenção de nomes predefinida "IT_***". O grupo de recursos de teste terá as etiquetas predefinidas aplicadas: createdBy, imageTemplateName, imageTemplateResourceGroupName. Além disso, o RBAC predefinido será aplicado à identidade atribuída ao recurso de modelo do Azure Image Builder, que é "Contribuidor".

  • 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 Construtor de Imagens irá verificar se o grupo de recursos não está associado a outro modelo de imagem, está vazio (sem recursos no interior), na mesma região que o modelo de imagem e tem o RBAC "Contribuidor" ou "Proprietário" aplicado à identidade atribuída ao recurso de modelo de imagem do Azure Image Builder. Se qualquer um dos requisitos mencionados acima não for cumprido, será apresentado um erro. O grupo de recursos de teste terá as seguintes etiquetas adicionadas: usedBy, imageTemplateName, imageTemplateResourceGroupName. As etiquetas pré-existentes não são eliminadas.

Importante

Terá de atribuir a função de contribuidor ao grupo de recursos do principal de serviço correspondente à aplicação original 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 as instruções do comando e do portal da CLI sobre como atribuir a função de contribuidor ao grupo de recursos, veja a seguinte documentação Resolver problemas do Azure Image Builder da VM: Erro de autorização ao criar o 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 teste com o nome fornecido na stagingResourceGroup propriedade . Haverá um erro se o nome especificado não cumprir os requisitos de nomenclatura do Azure para grupos de recursos. O grupo de recursos de teste terá as etiquetas predefinidas aplicadas: createdBy, imageTemplateName, imageTemplateResourceGroupName. Por predefinição, a identidade atribuída ao recurso de modelo de imagem do Azure Image Builder terá o RBAC "Contribuidor" aplicado ao mesmo no grupo de recursos.

Eliminação de modelos

Qualquer grupo de recursos de teste criado pelo serviço Construtor de Imagens será eliminado depois de o modelo de imagem ser eliminado. A eliminação inclui grupos de recursos de teste que foram especificados na stagingResourceGroup propriedade, mas que não existiam antes da compilação da imagem.

Se o Construtor de Imagens não tiver criado o grupo de recursos de teste, mas os recursos dentro do grupo de recursos, esses recursos serão eliminados após a eliminação do modelo de imagem, dado que o serviço Construtor de Imagens tem as permissões ou funções adequadas necessárias para eliminar recursos.

Propriedades: validar

Pode utilizar a propriedade para validar imagens de plataforma e quaisquer imagens personalizadas que criar, independentemente de ter utilizado o validate Azure Image Builder para as criar.

O Azure Image Builder suporta um modo "Source-Validation-Only" que pode ser definido com a sourceValidationOnly propriedade . Se a sourceValidationOnly propriedade estiver definida como verdadeira, a imagem especificada na source secção será validada diretamente. Não será executada nenhuma compilação separada para gerar e, em seguida, validar uma imagem personalizada.

A inVMValidations propriedade utiliza uma lista de validadores que serão executados na imagem. O Azure Image Builder suporta validadores do PowerShell e da Shell.

A continueDistributeOnFailure propriedade é responsável por saber se as imagens de saída serão distribuídas se a validação falhar. Por predefinição, se a validação falhar e esta propriedade estiver definida como falsa, as imagens de saída não serão distribuídas. Se a validação falhar e esta propriedade estiver definida como verdadeira, as imagens de saída continuarão a ser distribuídas. Utilize esta opção com cuidado, uma vez que pode resultar na distribuição de imagens falhadas para utilização. Em qualquer um dos casos (verdadeiro ou falso), a execução da imagem ponto a ponto será comunicada como uma falha se ocorrer uma falha de validação. Esta propriedade não tem qualquer efeito sobre se a validação é bem-sucedida ou não.

Ao utilizar validate:

  • Pode utilizar vários validadores.
  • Os validadores são executados pela ordem especificada no modelo.
  • Se um validador falhar, todo o componente de validação falhará e reportará um erro.
  • É aconselhável testar o script cuidadosamente antes de o utilizar num modelo. A depuração do script na sua própria VM será mais fácil.
  • Não coloque dados confidenciais nos scripts.
  • As localizações do script têm de estar acessíveis publicamente, a menos que esteja a utilizar o MSI.

Como utilizar a validate propriedade para validar imagens do Windows:

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

inVMValidations propriedades:

  • type – PowerShell.

  • name - nome do validador

  • scriptUri - URI do ficheiro de script do PowerShell.

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

  • validExitCodes – códigos opcionais e válidos que podem ser devolvidos a partir do comando script/inline, o que evitará a falha reportada do script/comando inline.

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

  • sha256Checksum - Valor da soma de verificação sha256 do ficheiro, gera-o localmente e, em seguida, o Construtor de Imagens irá fazer a soma de verificação e validar.

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

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

inVMValidations propriedades:

  • type – Shell

  • name - nome do validador

  • scriptUri - URI do ficheiro de script

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

  • sha256Checksum - Valor da soma de verificação sha256 do ficheiro, gera-o localmente e, em seguida, o Construtor de Imagens irá fazer a soma de verificação e validar.

    Para gerar o sha256Checksum, utilize um terminal em execução no Mac/Linux: sha256sum <fileName>

Propriedades: vmProfile

vmSize (opcional)

O Construtor de Imagens utiliza um tamanho de SKU predefinido de Standard_D1_v2 para imagens gen1 e Standard_D2ds_v4 para imagens Gen2. A geração é definida pela imagem que especificar em source. Pode substituir o vmSize por estes motivos:

  • Realizar personalizações que requerem maior memória, CPU e processamento de ficheiros grandes (GBs).
  • Ao executar compilações do Windows, deve utilizar "Standard_D2_v2" ou tamanho de VM equivalente.
  • Exigir isolamento da VM.
  • Personalizar uma imagem que requer hardware específico. Por exemplo, para uma VM de GPU, precisa de um tamanho de VM de GPU.
  • Exigir encriptação ponto a ponto no resto da VM de compilação, tem de especificar o tamanho da VM de compilação de suporte que não utiliza discos temporários locais.

osDiskSizeGB

Por predefinição, o Construtor de Imagens não altera o tamanho da imagem, utiliza o tamanho da imagem de origem. Opcionalmente, pode aumentar o tamanho do Disco do SO (Win e Linux) e um valor de 0 significa deixar o mesmo tamanho que a imagem de origem. Não pode reduzir o tamanho do Disco do SO para um tamanho inferior ao tamanho da imagem de origem.

{
  "osDiskSizeGB": 100
}

vnetConfig (opcional)

Se não especificar quaisquer propriedades da VNet, o Construtor de Imagens criará a sua própria VNet, IP Público e grupo de segurança de rede (NSG). O IP Público é utilizado para o serviço comunicar com a VM de compilação. Se 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), pode especificar uma VNet. Para obter mais informações, veja a documentação de rede.

"vnetConfig": {
  "subnetId": "/subscriptions/<subscriptionID>/resourceGroups/<vnetRgName>/providers/Microsoft.Network/virtualNetworks/<vnetName>/subnets/<subnetName>"
}

Operações de Modelo de Imagem

Iniciar uma Compilação de Imagem

Para iniciar uma compilação, tem de invocar "Executar" no recurso Modelo de Imagem, exemplos de run comandos:

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Run -Force
az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Run

Cancelar uma Compilação de Imagem

Se estiver a executar uma compilação de imagem que acredita estar incorreta, à espera da entrada do utilizador ou se sentir que nunca será concluída com êxito, pode cancelar a compilação.

A compilação pode ser cancelada em qualquer altura. Se a fase de distribuição tiver sido iniciada, ainda pode cancelar, mas terá de limpar quaisquer imagens que possam não estar concluídas. O comando cancelar não aguarda que o cancelamento seja concluído, monitorize lastrunstatus.runstate o cancelamento do progresso com estes comandos de estado.

Exemplos de cancel comandos:

Invoke-AzResourceAction -ResourceName $imageTemplateName -ResourceGroupName $imageResourceGroup -ResourceType Microsoft.VirtualMachineImages/imageTemplates -ApiVersion "2021-10-01" -Action Cancel -Force
az resource invoke-action \
  --resource-group $imageResourceGroup \
  --resource-type  Microsoft.VirtualMachineImages/imageTemplates \
  -n helloImageTemplateLinux01 \
  --action Cancel

Passos seguintes

Existem ficheiros .json de exemplo para diferentes cenários no GitHub do Azure Image Builder.