Compartilhar via

Novidades no Construtor de Imagens de VM do Azure

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 construtor de imagens da VM do Azure.

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. Essa desativação evita falhas desnecessárias de compilação.

Você ainda pode criar manualmente o modelo de imagem. Após a conclusão bem-sucedida de uma build manual, os gatilhos automáticos são reativados.

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 entre maiúsculas e minúsculas

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

Importante

Se você for um usuário existente do Construtor de Imagens de VM, essa alteração não afetará seus recursos existentes. A aplicação da diferenciação entre maiúsculas e minúsculas aplica-se somente aos recursos recém-criados que utilizam a versão de API 2024-02-01 e posterior. Seus recursos existentes continuam funcionando conforme o esperado sem alterações.

Se você encontrar problemas relacionados à sensibilidade a maiúsculas/minúsculas, consulte a documentação atualizada da API do Construtor de Imagens de VM para obter orientações.

Anteriormente, a API do Construtor de Imagens da VM era mais tolerante em termos de caso. Seguindo em frente, 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 nomeado vmBoot, você deverá usar vmBoot (não VMBoot ou vmboot).

Se você enviar uma solicitação para a API do Construtor de Imagens da VM versão 2024-02-01 ou posterior com uso incorreto de maiúsculas/minúsculas ou com campos não reconhecidos, o serviço rejeitará a solicitação. Você recebe uma resposta de erro indicando que a solicitação é inválida. O erro é semelhante a este exemplo:

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 menciona um "campo desconhecido" e direciona você para a documentação oficial: Criar um modelo JSON do Bicep ou do Azure Resource Manager para o Construtor de Imagens de VM do Azure.

Observação

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

As alterações de documentação a seguir foram feitas para corresponder aos nomes de campo na API versão 2024-02-01.

Na documentação Criar um modelo JSON do Bicep ou do Azure Resource Manager para o Construtor de Imagens de VM do Azure:

  • Campos atualizados:

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

  • Campo removido:

    • apiVersion: recomendamos evitar a inclusão desse campo em suas solicitações porque ele não é especificado explicitamente na API. 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 está obsoleto. O novo campo é subnetId.
    • resourceGroupName na propriedade vnetConfig: este campo está obsoleto. O novo campo é subnetId.

Anexação a uma versão anterior da API do Construtor de Imagens de VM

Se você quiser evitar alterações nas propriedades dos modelos de imagem devido às novas regras de diferenciação entre maiúsculas e minúsculas, poderá fixar suas chamadas de API do Construtor de Imagens de VM do Azure a uma versão anterior da API. Essa anexação permite continuar usando o comportamento familiar sem modificações.

Importante

A anexação a uma versão anterior da API do Construtor de Imagens de VM pode garantir a compatibilidade com seus modelos existentes, mas não é recomendada devido aos seguintes fatores:

  • Versões de API mais antigas podem eventualmente ser preteridas.
  • 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.

Para garantir a compatibilidade com seus modelos existentes ao criar ou atualizar um modelo de imagem, especifique a versão da API desejada, incluindo o api-version parâmetro em sua chamada para o serviço. Por 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 a 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.

Novembro de 2023

VM Image Builder está habilitando construções de imagens isoladas por meio de Instâncias de Contêiner do Azure de forma faseada. A distribuição deve ser concluída no início de 2024. Seus modelos de imagem existentes continuam funcionando e não há nenhuma alteração na maneira como você cria ou cria novos modelos de imagem.

Você pode observar um conjunto diferente de recursos transitórios do Azure que podem aparecer temporariamente no grupo de recursos de estágio. Isso não afeta seus builds reais ou a maneira como você interage com o Construtor de Imagens da VM. Para obter mais informações, consulte Compilações de imagem isoladas.

Para usar Builds de Imagens Isoladas, verifique se:

  • Sua assinatura está registrada para o Microsoft.ContainerInstance provedor.
  • Não há políticas que bloqueiem a implantação de recursos das Instâncias de Contêiner do Azure.
  • Há cota disponível para recursos de Instâncias de Contêiner do Azure.

Abril de 2023

A nova funcionalidade do portal foi adicionada ao Construtor de Imagens da VM. Pesquise modelos de imagem no portal do Azure e selecione Criar. Você também pode usar essa configuração de modelo para começar a criar e validar imagens personalizadas dentro do portal.

Versões da API

Versão 2024-02-01

Aprimoramentos

  • Você pode usar a nova autoRun propriedade para executar o build de imagem na criação ou atualização do modelo. Para obter mais informações, consulte Propriedades: autoRun.

  • Você pode usar a nova propriedade managedResourceTags para aplicar rótulos aos recursos que o serviço Construtor de Imagens de VM cria no grupo de recursos de preparo durante a build da imagem. Para obter mais informações, consulte Propriedades: managedResourceTags.

  • Você pode usar a nova propriedade containerInstanceSubnetId para especificar uma sub-rede onde as Instâncias de Contêiner do Azure serão implantadas para builds de imagens isoladas. Você só poderá especificar esse campo se especificar subnetId. Esse campo deve estar na mesma rede virtual que a sub-rede especificada em subnetId. Para obter mais informações, confira Traga sua própria sub-rede de VM de build e traga sua própria sub-rede de Instâncias de Contêiner.

  • Esta versão adiciona suporte para atualizar a vmProfile propriedade, incluindo os seguintes campos:

    • vmSize
    • osDiskSizeGB
    • userAssignedIdentities
    • vnetConfig
      • subnetId
      • containerInstanceSubnetId

    Para obter mais informações sobre a vmProfile propriedade, consulte vmProfile.

Alterações

A versão da API 2024-02-01 introduz uma alteração interruptiva que impõe diferenciação entre maiúsculas e minúsculas para todos os campos. 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 Construtor de Imagens da VM versão 2024-02-01 ou posterior com um caso incorreto ou campos não reconhecidos, o serviço a rejeitará. Você recebe uma resposta de erro indicando que a solicitação é inválida. Para obter mais informações, confira Alteração interruptiva: diferenciação entre maiúsculas e minúsculas neste artigo.

Versão 2023-07-01

Alterações

A nova errorHandling propriedade fornece mais controle sobre como os erros são tratados durante o processo de criação da imagem. Para obter mais informações, consulte errorHandling.

Versão 2022-07-01

Aprimoramentos

  • Esta versão adiciona suporte para usar a versão mais recente da imagem armazenada na Galeria de Computação do Azure como a origem do modelo de imagem.
  • Esta versão adiciona versioning para dar suporte à geração de números de versão para distribuições de imagem. Para obter mais informações, consulte Propriedades: versioning.
  • Esta versão adiciona suporte para a configuração por região quando você está distribuindo para a Galeria de Computação do Azure. Para obter mais informações, confira Distribuir: targetRegions.
  • Esta versão adiciona um novo File tipo de validação. Para obter mais informações, consulte Propriedades: validate.
  • Agora você pode distribuir VHDs (discos rígidos virtuais) para um blob ou contêiner personalizado em uma conta de armazenamento personalizada. Para obter mais informações, consulte Distribuir: VHD.
  • Esta versão adiciona suporte para usar uma imagem de galeria compartilhada direta como a origem do modelo de imagem.

Alterações

Versão 2022-02-14+

Aprimoramentos

Versão 2021-10-01

Alteração da falha

A versão da API 01-10-2021 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, depois de alternar para a versão mais recente da API, que você não reverta para uma versão anterior. Se você reverter, será necessário alterar sua automação novamente para gerar o esquema de erro anterior. Não esperamos que o esquema de erros 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." 
  }
}

Aprimoramentos

Versão 2020-02-14

Aprimoramentos

  • 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)
    • Reinicialização do 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
    • Imagem gerenciada
    • Galeria de Computação do Azure
  • Adicionado suporte para os clientes usarem sua própria rede virtual.
  • Adicionado suporte para os clientes personalizarem a VM de build (tamanho da VM, tamanho do disco do sistema operacional).
  • Adicionado suporte para identidades gerenciadas atribuídas pelo usuário (para personalizar/distribuir etapas).
  • Adicionado suporte para imagens de Geração 2.

API de visualização

A API a seguir foi preterida, mas ainda tem suporte:

  • Versão 2019-05-01-preview

Conteúdo relacionado

  • Last updated on