Azure VM 映像生成器中的新增功能

适用于：✔️ Linux VM ✔️ Windows VM ✔️ 灵活规模集 ✔️ 统一规模集

本文包含 Azure VM 映像生成器服务的所有主要 API 更改和功能更新。

如果映像模板构建连续多次失败，则会停用通过触发器生成映像的功能。 停用此功能可以避免不必要的构建失败。

你仍然可以手动生成映像模板。 手动生成成功后，自动触发器将重新激活。

无论对映像模板资源使用哪个 API 版本，此行为都是相同的。

截至 2024 年 5 月 21 日，VM 映像生成器 API 版本 2024-02-01 及更高版本对所有字段强制实施区分大小写。 API 请求中的字母大写必须与预期格式完全匹配。

以前，VM 映像生成器 API 在案例方面更宽容。 前进，精度至关重要。 进行 API 调用时，请确保对字段名称、参数和值使用正确的大写。 例如，如果字段名为 vmBoot，则必须使用 vmBoot（不是 VMBoot 或 vmboot）。

如果向 VM 映像生成器 API 版本 2024-02-01 或更高版本发送 API 请求，但出现错误或无法识别的字段，服务将拒绝该请求。 收到一个错误响应，指示请求无效。 此错误类似于以下示例：

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.

错误消息提到“未知字段”，并将你定向到官方文档： 创建 Azure VM 映像生成器 Bicep 或 Azure 资源管理器 JSON 模板。

进行了以下文档更改，以匹配 API 版本 2024-02-01 中的字段名称。

在 创建 Azure VM 映像生成器 Bicep 或 Azure 资源管理器 JSON 模板 文档中：

• 字段已更新：

  • 将多处提及的 vmboot 替换为 vmBoot。
  • 将一处提及的 imageVersionID 替换为 imageVersionId。

• 删除了字段：

  • apiVersion：建议避免将此字段包含在请求中，因为它未在 API 中显式指定。 在 JSON 模板中包含它可能会导致映像生成中出现错误。

在 Azure VM 映像生成器网络选项文档中：

• 已更新的字段：

  • 将一处提及的 VirtualNetworkConfig 替换为 vnetConfig。

• 已删除的字段：

  • subnetName 在 vnetConfig 属性中：该字段已弃用。 新字段为 subnetId.
  • resourceGroupName 在 vnetConfig 属性中：该字段已弃用。 新字段为 subnetId.

如果想要避免由于新的区分大小写规则对映像模板中的属性进行更改，可以选择将 Azure VM 映像生成器 API 调用固定到以前的 API 版本。 这种固定可以继续使用熟悉的行为，而无需进行任何修改。

若要确保在创建或更新映像模板时与现有模板兼容，请在调用服务时包括 api-version 参数来指定所需的 API 版本。 例如：

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

az resource create \
    --api-version=2022-07-01 \
    --resource-group <resourceGroupName> \
    --properties <jsonResource> \
    --is-full-object \
    --resource-type Microsoft.VirtualMachineImages/imageTemplates \
    -n <imageTemplateName>

New-AzResourceGroupDeployment -ResourceGroupName <resourceGroupName> -TemplateFile <templateFilePath> -TemplateParameterObject @{"api-version" = "2022-07-01"; "imageTemplateName" = <imageTemplateName>; "svclocation" = <location>}

固定到较旧的 API 版本后，测试代码以验证它是否按预期方式运行。 确保现有模板继续正常运行。

VM 映像生成器通过分阶段方式通过 Azure 容器实例启用独立映像生成。 预计到 2024 年初，推出将完成。 现有映像模板可继续工作，并且创建或生成新映像模板的方式没有变化。

你可能会观察到有一组不同的暂时性 Azure 资源临时出现在暂存资源组中。 它不会影响实际生成或与 VM 映像生成器交互的方式。 有关详细信息，请参阅独立映像生成。

若要使用独立映像生成，请确保：

• 您的订阅已在 Microsoft.ContainerInstance 提供商处注册。
• 没有阻止部署 Azure 容器实例资源的策略。
• 配额可用于 Azure 容器实例资源。

为 VM 映像生成器添加了新的门户功能。 在 Azure 门户中搜索 图像模板 ，然后选择“ 创建”。 还可以 使用此模板配置 开始在门户中生成和验证自定义映像。

• 可以使用新 autoRun 属性在模板创建或更新时运行映像生成。 有关详细信息，请参阅 “属性： autoRun”。

• 可以使用新 managedResourceTags 属性将标记应用于 VM 映像生成器服务在映像生成期间在过渡资源组中创建的资源。 有关详细信息，请参阅 “属性： managedResourceTags”。

• 可以使用新的containerInstanceSubnetId属性来指定用于孤立映像生成的子网，在其上部署 Azure 容器实例。 只有在指定subnetId时，才能指定此字段。 此字段必须位于与 subnetId 指定的子网相同的虚拟网络上。 有关详细信息，请参阅使用自己的生成 VM 子网并使用自己的容器实例子网。

• 此版本添加了对更新 vmProfile 属性的支持，包括以下字段：

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

  有关属性 vmProfile 的详细信息，请参阅 vmProfile。

API 版本 2024-02-01 引入了一个重大变更，强制所有字段区分大小写。 API 请求中的字母大写必须与预期格式完全匹配。 如果向 VM 映像生成器 API 版本 2024-02-01 或更高版本发送 API 请求，但出现错误情况或无法识别的字段，服务将拒绝该请求。 收到一个错误响应，指示请求无效。 有关详细信息，请参阅本文中的中断性变更：区分大小写。

使用新 errorHandling 属性可以更好地控制在映像生成过程中如何处理错误。 有关详细信息，请参阅 errorHandling。

• 此版本添加了支持，以使用 Azure 计算库中存储的最新映像版本作为映像模板的源。
• 此版本添加了 versioning 以支持为映像分发生成版本号。 有关详细信息，请参阅 “属性： versioning”。
• 在您将内容分发到 Azure 计算图库时，此版本现在增加了对按区域配置的支持。 有关详细信息，请参阅 Distribute: targetRegions。
• 此版本添加了新的 File 验证类型。 有关详细信息，请参阅 “属性： validate”。
• 现在可以将虚拟硬盘（VHD）分发到自定义存储帐户中的自定义 Blob 或容器。 有关详细信息，请参阅 “分发：VHD”。
• 此版本支持使用 直接共享图库 映像作为图像模板的源。

• 库分发现已弃用 replicationRegions。 请改用 gallery-replication-regions。
• 现在可以将 VHD 分发到自定义存储帐户中的自定义 Blob 或容器。
• 版本中添加了仅适用于 targetRegions 类型分配的 SharedImage 数组。 有关targetRegions的详细信息，请参阅Azure Compute Gallery 中的存储和共享资源。
• 此版本支持使用 直接共享图库 映像作为图像模板的源。 直接共享库目前处于预览状态。

• 验证支持
  • Shell (Linux)：脚本或内联
  • PowerShell (Windows)：脚本或内联、特权运行、以系统身份运行
  • 仅限源验证模式
• 为过渡资源组提供自定义支持

API 版本 2021-10-01 引入了对错误架构的更改，该架构将成为每个未来 API 版本的一部分。 如果有任何 Azure VM 映像生成器自动化，请注意切换到 API 版本 2021-10-01 或更高版本时的新错误输出。

建议切换到最新的 API 版本后，不要还原到早期版本。 如果还原，则必须再次更改自动化，以生成早期的错误架构。 我们预计将来的版本不会再次更改错误架构。

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

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

• 添加了对生成 VM 的托管标识的支持。
• 添加了对代理 VM 大小的自定义支持。

• 添加了对从以下源创建映像的支持：
  • 托管映像
  • Azure 计算画廊
  • 平台映像存储库（包括平台映像购买计划）
• 添加了对以下自定义项的支持：
  • Shell (Linux)：脚本或内联
  • PowerShell (Windows)：脚本或内联、特权运行、以系统身份运行
  • 文件（Linux 和 Windows）
  • Windows 重启 (Windows)
  • Windows 更新 (Windows)：搜索条件、筛选器以及更新限制
• 添加了对以下分布类型的支持：
  • VHD
  • 托管映像
  • Azure 计算画廊
• 添加了对客户使用自己的虚拟网络的支持。
• 添加了对客户自定义生成 VM（VM 大小、作系统磁盘大小）的支持。
• 添加了对用户分配的托管标识的支持（用于自定义/分发步骤）。
• 添加了对 第 2 代映像的支持。

以下 API 已弃用，但仍受支持：

• 版本 2019-05-01-preview

• Azure VM 映像生成器概述