Compartilhar via

Novidades no Construtor de Imagens de VM do Azure

  • Artigo

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

Este artigo contém todas as principais alterações de API e atualizações de recursos para o serviço do Construtor de Imagens de VM do Azure (AIB).

Atualizações

Setembro de 2024

A criação automática de imagem por meio de gatilhos será desativada se o build do modelo de imagem falhar várias vezes consecutivamente, a fim de evitar falhas de build desnecessárias.

Você ainda pode criar manualmente o modelo de imagem. Depois que um build manual for bem-sucedido, os gatilhos automáticos serão reativados.

Observe que esse comportamento é o mesmo, independentemente de qual versão da API você usa para o recurso de modelo de imagem.

Maio de 2024

Alteração interruptiva: Diferenciação de maiúsculas e minúsculas

A partir de 21 de maio de 2024, a API do Construtor de Imagens da VM do Azure versão 2024-02-01 e posterior imporá a confidencialidade de maiúsculas e minúsculas para todos os campos. Isso significa que a capitalização de letras em suas solicitações de API deve corresponder exatamente ao formato esperado.

Importante

Nota importante para usuários existentes do Construtor de Imagens do Azure

Se você for um usuário existente do Construtor de Imagens de VM do Azure, tenha certeza de que essa alteração nãoafetará seus recursos existentes. A imposição de confidencialidade de maiúsculas e minúsculas aplica-se apenas a recursos recém-criados usando API versão 2024-02-01 e além. Seus recursos existentes continuarão funcionando conforme o esperado sem nenhuma alteração.

Se você encontrar problemas relacionados à confidencialidade de caso, consulte a documentação atualizada da API do Construtor de Imagens do Azure para obter diretrizes.

Anteriormente, a API do Construtor de Imagens do Azure era mais tolerante em termos de caso, mas avançar, a precisão é crucial. Ao fazer chamadas à API, certifique-se de usar a capitalização correta para nomes de campo, parâmetros e valores. Por exemplo, se um campo for chamado "vmBoot", você deverá usar "vmBoot" (não "VMBoot" ou "vmboot").

Se você enviar uma solicitação de API para a API do Azure Image Builder versão 2024-02-01 e posterior com maiúsculas e minúsculas incorretas ou campos não reconhecidos, o serviço a rejeitará. Você receberá uma resposta de erro indicando que a solicitação é inválida. O erro será semelhante a este:

Unmarshalling entity encountered error: unmarshalling type *v2024_02_01.ImageTemplate: struct field Properties: unmarshalling type *v2024_02_01.ImageTemplateProperties: struct field Optimize: unmarshalling type *v2024_02_01.ImageTemplatePropertiesOptimize: unmarshalling type *v2024_02_01.ImageTemplatePropertiesOptimize, unknown field \"vmboot\". There is an issue with the syntax with the JSON template you are submitting. Please check the JSON template for syntax and grammar. For more information on the syntax and grammar of the JSON template, visit http://aka.ms/azvmimagebuildertmplref.

A mensagem de erro mencionará um "campo desconhecido" e direcionará você para a documentação oficial: Criar um modelo JSON do modelo do Azure Image Builder ou do ARM.

Observação

Referenciar o Swagger do Construtor de Imagens do Azure para chamadas à API

Ao fazer chamadas para o serviço do Construtor de Imagens do Azure, sempre faça referência à documentação do Swagger, que serve como a fonte definitiva da verdade para as especificações da API do Construtor de Imagens do Azure. Embora a documentação pública tenha sido atualizada para incluir os nomes de capitalização e de campo adequados antes da versão da API, a definição do Swagger contém detalhes precisos sobre cada API AIB para garantir que você esteja fazendo chamadas para o serviço corretamente.

Veja abaixo uma lista das alterações de documentação feitas para corresponder aos nomes de campo na API versão 2024-02-01:

Na documentação Criar um modelo JSON do Azure Image Builder Bicep ou ARM:

Campos atualizados:

  • Substituiu várias menções de vmboot por vmBoot
  • Substituiu uma menção de imageVersionID por imageVersionId

Campo Removido:

  • apiVersion: é recomendável evitar a inclusão desse campo em suas solicitações porque ele não é especificado explicitamente em nossa API, portanto, incluí-lo em seu modelo JSON pode levar a erros no build de imagem.

Na documentação das opções de rede do Azure VM Image Builder:

Campo Atualizado:

  • Substituiu uma menção de VirtualNetworkConfig por vnetConfig

Campos removidos:

  • subnetName na propriedade vnetConfig - este campo foi preterido e o novo campo é subnetId
  • resourceGroupName na propriedade vnetConfig - este campo foi preterido e o novo campo é subnetId

Como fixar em uma versão mais antiga da API do Construtor de Imagens do Azure

Consideração importante para fixar em versões de API mais antigas

Fixar a uma versão mais antiga da API do Construtor de Imagens do Azure pode fornecer compatibilidade com seus modelos existentes, mas isso não é recomendado devido aos seguintes fatores:

  • Risco de substituição: versões de API mais antigas podem eventualmente ser preteridas.

  • Recursos ausentes: ao fixar uma versão mais antiga da API, você perde os recursos e melhorias mais recentes introduzidos em versões mais recentes. Esses aprimoramentos geralmente melhoram o desempenho, a segurança e a funcionalidade.

Se você quiser evitar fazer alterações nas propriedades em seus modelos de imagem devido às novas regras de confidencialidade de caso, terá a opção de fixar as chamadas à API do Construtor de Imagens da VM do Azure para uma versão anterior da API. Isso permite que você continue usando o comportamento familiar sem nenhuma modificação.

Para garantir a compatibilidade com seus modelos existentes, ao criar ou atualizar um modelo de imagem, especifique a versão da API desejada (por exemplo, api-version=2022-07-01) incluindo o parâmetro api-version em sua chamada para o serviço. Exemplo:

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.VirtualMachineImages/imageTemplates/{imageTemplateName}?api-version=2022-07-01

Testar seu código

Depois de fixar na versão mais antiga da API, teste seu código para verificar se ele se comporta conforme o esperado. Verifique se os modelos existentes continuam funcionando corretamente.

novembrod e 2023

O Construtor de Imagens do Azure está habilitando as Compilações de imagem isoladas usando Instâncias de Contêiner do Azure em fases. A distribuição deve ser concluída no início de 2024. Os modelos de imagem existentes continuarão funcionando e a maneira como você criará ou compilará novos modelos de imagem não será alterada.

Você pode observar que um conjunto diferente de recursos transitórios do Azure aparece temporariamente no grupo de recursos de preparo, mas isso não afeta seus builds reais ou a maneira como você interage com o Construtor de Imagens do Azure. Para obter mais informações, consulte Compilações de imagem isoladas.

Importante

Verifique se sua assinatura está registrada para o provedor de Microsoft.ContainerInstance e se não há políticas bloqueando a implantação de recursos das Instâncias de Contêiner do Azure. Verifique também se a cota está disponível para recursos das Instâncias de Contêiner do Azure.

Abril de 2022

A nova funcionalidade do portal foi adicionada no Construtor de Imagens do Azure. Pesquise "Modelos de Imagem" no portal do Azure e clique em "Criar". Você também pode começar aqui com a criação e validação de imagens personalizadas dentro do portal.

Versões da API

Versão 2024-02-01

Melhorias

  • Nova propriedade autoRun que permite executar o build de imagem na criação ou atualização do modelo. Para obter mais informações, consulte painel Propriedades: autoRun.
  • Nova propriedade managedResourceTags que permite aplicar marcas aos recursos que o serviço do Construtor de Imagens do Azure cria no grupo de recursos de preparo durante o build de imagem. Para obter mais informações, consulte painel Propriedades: managedResourceTags.
  • Nova propriedade containerInstanceSubnetId que permite especificar uma sub-rede na qual a Instância de Contêiner do Azure será implantada para Builds Isolados. Esse campo só poderá ser especificado se subnetId também for especificado e deve estar na mesma Rede Virtual que a sub-rede especificada em subnetId. Para obter mais informações, consulte Traga sua própria sub-rede de VM de compilação e traga sua própria sub-rede de ACI .
  • Adicionado suporte para atualizar a propriedade vmProfile incluindo os seguintes campos:
    • vmSize
    • osDiskSizeGB
    • userAssignedIdentities
    • vnetConfig
      • subnetId
      • containerInstanceSubnetId Para obter mais informações sobre a propriedade vmProfile, consulte vmProfile.

Alterações API versão 2024-02-01 introduz uma alteração interruptiva que impõe a diferenciação de maiúsculas e minúsculas para todos os campos. Isso significa que a capitalização de letras em suas solicitações de API deve corresponder exatamente ao formato esperado. Se você enviar uma solicitação de API para a API do Azure Image Builder versão 2024-02-01 e posterior com maiúsculas e minúsculas incorretas ou campos não reconhecidos, o serviço a rejeitará. Você receberá uma resposta de erro indicando que a solicitação é inválida. Para obter mais informações, consulte Alteração interruptiva: diferenciação de maiúsculas e minúsculas.

Versão 2023-07-01

Em breve

Suporte para atualizar destinos de distribuição da Galeria de Computação do Azure.

Alterações

Nova propriedade errorHandling. Essa propriedade fornece aos usuários mais controle sobre como os erros são tratados durante o processo de criação da imagem. Para obter mais informações, confira errorHandling

Versão 2022-07-01

Melhorias

  • Foi adicionado suporte para usar a versão de imagem mais recente armazenada na Galeria de Computação do Azure como a origem do modelo de imagem
  • versioning foi adicionado para dar suporte à geração de números de versão para distribuições de imagem. Para obter mais informações, confira propriedades: controle de versão
  • Foi adicionado suporte para a configuração por região ao distribuir para a Galeria de Computação do Azure. Para obter mais informações, confira Distribute:targetRegions.
  • Foi adicionado o novo tipo de validação "Arquivo". Para obter mais informações, confira validar propriedades.
  • Os VHDs agora podem ser distribuídos para um blob ou contêiner personalizado em uma conta de armazenamento personalizada. Para obter mais informações, confira Distribuir: VHD.
  • Foi adicionado suporte para usar uma imagem da Galeria Compartilhada Direta como a origem do modelo de imagem

Alterações

  • replicationRegions agora está preterido para distribuições de galeria. Para obter mais informações, use gallery-replicated-regions
  • Os VHDs agora podem ser distribuídos para um blob ou contêiner personalizado em uma conta de armazenamento personalizada
  • targetRegions matriz adicionada e aplicada somente à distribuição do tipo "SharedImage". Para obter mais informações sobre targetRegions, confira Galeria de Computação do Azure.
  • Foi adicionado suporte para usar uma imagem da Galeria Compartilhada Direta como a origem do modelo de imagem. A Galeria Compartilhada Direta está atualmente em versão prévia.
  • Os gatilhos agora estão disponíveis na visualização pública para configurar builds de imagem automáticas. Para obter mais informações, confira Como usar os gatilhos AIB

Versão 2022-02-14+

Melhorias

Versão 2021-10-01

Alterações da falha

A versão de 01-10-2021 da API apresenta uma alteração no esquema de erro que fará parte de cada versão futura da API. Se você tiver alguma automação do Construtor de Imagens de VM do Azure, lembre-se da nova saída de erro ao alternar para a versão 2021-10-01 ou posterior da API. Recomendamos que, depois de alternar para a versão mais recente da API, você não reverta para uma versão anterior, pois precisará alterar sua automação novamente para produzir o esquema de erro anterior. Não prevemos que o esquema de erro seja alterado novamente em versões futuras.

Saída de erro para a versão 2020-02-14 e anterior
{ 
  "code": "ValidationFailed",
  "message": "Validation failed: 'ImageTemplate.properties.source': Field 'imageId' has a bad value: '/subscriptions/subscriptionID/resourceGroups/resourceGroupName/providers/Microsoft.Compute/images/imageName'. Please review  http://aka.ms/azvmimagebuildertmplref  for details on fields requirements in the Image Builder Template." 
}
Saída de erro para a versão 2021-10-01 e posterior
{ 
  "error": {
    "code": "ValidationFailed", 
    "message": "Validation failed: 'ImageTemplate.properties.source': Field 'imageId' has a bad value: '/subscriptions/subscriptionID/resourceGroups/resourceGroupName/providers/Microsoft.Compute/images/imageName'. Please review  http://aka.ms/azvmimagebuildertmplref  for details on fields requirements in the Image Builder Template." 
  }
}

Melhorias

  • Adicionado suporte para MSIs de VM de build.
  • Adicionado suporte para personalização de tamanho da VM de proxy.

Versão 2020-02-14

Melhorias

  • Adicionado suporte para criar imagens a partir das seguintes fontes:
    • Imagem gerenciada
    • Galeria de Computação do Azure
    • Repositório de imagens de plataforma (incluindo o Plano de Compra de Imagens de Plataforma)
  • Adicionado suporte para as seguintes personalizações:
    • Shell (Linux)?: script ou embutido
    • PowerShell (Windows): script ou embutido, execução elevada, execução como sistema
    • Arquivo (Linux e Windows)
    • Reiniciar Windows (Windows)
    • Windows Update (Windows): critérios de pesquisa, filtros e limite de atualização
  • Adicionado suporte para os seguintes tipos de distribuição:
    • VHD (disco rígido virtual)
    • Imagem gerenciada
    • Galeria de Computação do Azure
  • Outros recursos:
    • Adicionado suporte para os clientes usarem uma rede virtual própria
    • Adicionado suporte para os clientes personalizarem a VM de build (tamanho da VM, tamanho do disco do sistema operacional)
    • Adicionado suporte para MSI (Microsoft Windows Installer) atribuído pelo usuário (para personalizar/distribuir etapas)
    • Adicionado suporte para Imagens Gen2

APIs de pré-visualização

As seguintes APIs estão preteridas, mas ainda têm suporte:

  • Versão 2019-05-01-preview

Próximas etapas

Saiba mais sobre o Construtor de Imagens de VM.