将资源转换并迁移到 Bicep 文件

  • 10 分钟

开始迁移到 Bicep 后，请务必遵循结构化的过程，以确保 Bicep 文件正确描述 Azure 资源。 你需要确保 Bicep 代码遵循最佳做法，并且经过充分测试，可以安全地用于后续部署。 在此单元中，你将了解 Bicep 迁移的前两个阶段：转换阶段和迁移阶段。

Diagram that shows the convert and migrate phases of the recommended workflow for migrating Azure resources to Bicep.

这两个阶段的重点在于，重构和测试之前先准备一个新的 Bicep 文件。

转换阶段

在将资源迁移到 Bicep 的转换阶段的目标是捕获 Azure 资源的初始表示形式。 你在此阶段创建的 Bicep 文件并未完成，尚未准备好使用。 但是，该文件提供了开始迁移的起点。

转换阶段包括两个可能的步骤，按顺序完成这些步骤：

  1. 捕获 Azure 资源的表示形式。
  2. 如果需要，使用 decompile 命令将 JSON 表示形式转换为 Bicep。

Diagram that shows a JSON template decompiled to JSON, and Azure resources that are exported to a JSON template, which is then decompiled.

如果有现有 JSON 模板，要将其转换为 Bicep，第一步很简单，因为你已经有源模板。 在本单元中，你将了解如何将它反编译成 Bicep。

如果要转换使用 Azure 门户或其他工具部署的 Azure 资源，需要捕获资源定义。 可以导出资源定义并将其转换为 Bicep，也可以在 Visual Studio Code 内使用“插入资源”命令，插入 Azure 资源的 Bicep 表示形式。

Azure 如何表示资源

Azure 资源管理器是用于部署和管理 Azure 中的资源的服务。 无论使用什么方法部署资源，资源管理器都会跟踪部署到 Azure 的所有资源。 你可以使用 Azure 门户、Azure CLI、Azure PowerShell、资源管理器 REST API 和 Azure SDK 来与资源管理器交互。

Diagram that shows Resource Manager accepting requests from all Azure clients and libraries.

Azure 中有两种类型的操作：控制平面操作和数据平面操作。 控制平面操作用于管理订阅中的资源。 数据平面操作用于访问资源公开的功能。 例如，使用控制平面操作创建虚拟机，但使用数据平面操作通过远程桌面协议 (RDP) 连接到虚拟机。

将现有资源导出到 JSON 模板

无论 Azure 资源是如何创建的，资源管理器都会以 JSON 格式提供有关每个资源的信息。 当请求资源的 JSON 表示形式的副本时，你正在导出资源。 导出的 JSON 文件可反编译到 Bicep 中。

资源管理器提供多种将 Azure 资源导出到模板的方法。 可以使用 Azure 门户、Azure CLI 和 Azure PowerShell cmdlet 导出单个资源、多个资源以及整个资源组。

导出过程属于控制平面操作，这意味着它仅导出 Azure 资源的配置。 例如，导出虚拟机时，虚拟机硬盘驱动器上的数据未导出。 导出存储帐户时，该存储帐户的 blob 和其他内容不会包含在导出过程中。

导出现有资源时，需要考虑以下几点：

  • 导出的资源定义是资源当前状态的快照。 包括自初始部署以来对资源所做的所有更改。
  • 导出的模板可能包含某些默认资源属性，这些属性通常会从 Bicep 定义中省略。 例如，导出过程可能会添加 Azure 自动设置的只读属性。 添加这些属性没有意义，因为它们是只读属性。 迁移到 Bicep 时，请考虑从资源定义中删除这些属性，以使 Bicep 文件没有可能导致混淆的不必要代码。
  • 导出的模板可能不包括使模板可重复使用所需的所有参数。 导出模板时，许多属性将硬编码到模板中。 本模块稍后将介绍如何添加参数。
  • 某些资源不能使用此方法导出，你需要在 Bicep 文件中手动定义这些资源。 在本单元稍后部分，你将学习如何重新创建这些资源。

将部署保存到 JSON 模板

如果曾通过 Azure 门户手动部署过资源，你可能已经注意到“查看 + 创建”选项卡上的“下载自动化模板”选项。此选项根据在门户中创建资源时所设置的名称和属性来保存 JSON ARM 模板。

资源管理器还会跟踪资源部署。 部署操作包括 Azure 门户资源创建体验提交的更改以及任何 ARM 模板部署。 使用 Azure 门户、Azure PowerShell cmdlet、Azure CLI 或其他工具对现有资源所做的更改通常不会创建部署。

如果使用兼容工具创建部署，则可以从资源组的部署历史记录中访问部署模板。 可以使用 Azure 门户、Azure CLI 或 Azure PowerShell 来保存部署。

使用此方法保存模板时，需要考虑以下几点：

  • 保存的模板显示的是部署时的资源状态。 不包括部署后所做的任何更改。
  • 如果部署包含多个资源，则不能选择要包含和排除的特定资源。 此操作会下载属于初始部署的所有资源的定义。 但是，当进入流程的迁移阶段时，你可以手动忽略不需要的资源。
  • 该模板仅包含部署所需的资源属性。
  • 模板可能包括可用于在多个环境中重新部署模板的参数。 但是，需要确认这些参数是否符合你的需求。
  • 此模板可能不包括外来属性，但仍应检查模板是否包含所需的所有内容，并删除任何不需要的属性。

注意

无论是通过导出现有资源还是通过保存部署来导出资源，都应将导出的文件视为起点，而不是直接使用。 改为将其用作最终模板的起点。

将现有资源插入到 Bicep 中

适用于 Visual Studio Code 的 Bicep 扩展包括“插入资源”命令，该命令捕获 Azure 资源的 Bicep 表示形式。 此命令从 Azure 读取资源的 JSON 定义，删除被识别为只读的属性，并将 JSON 反向编译为 Bicep。 与导出函数一样，生成的 Bicep 代码可以用作最终 Bicep 文件的起点。

可以通过打开 Visual Studio Code 命令面板来插入资源。 在 Windows 和 Linux 上使用 Ctrl+Shift+P，在 macOS 上使用 ⌘+Shift+P。

反编译源 JSON ARM 模板

将 Azure 资源迁移到 Bicep 的第二步是将 JSON ARM 模板和 Azure 资源转换为 Bicep 模板。 Bicep 工具包含用于转换模板的 decompile 命令。 可以从 Azure CLI 或 Bicep CLI 调用 decompile 命令。

反编译过程不能保证从 JSON 到 Bicep 的完整映射。 在使用文件部署资源之前，你可能需要修改生成的 Bicep 文件以满足模板最佳做法。 将其视为迁移的开始。 在本模块稍后部分，你将学习如何修复在反编译过程中遇到的任何问题。

反向编译模板后，就完成了转换阶段。 现在，你有一个有效的 Bicep 文件可以作为起点。

迁移阶段

在将资源迁移到 Bicep 的迁移阶段的目标是要创建可部署 Bicep 文件的草稿，并确保其可定义迁移范围内的所有 Azure 资源。

迁移阶段包括三个步骤，按顺序完成这些步骤：

  1. 创建新的空白 Bicep 文件。
  2. 从反编译的模板中复制每个资源。
  3. 标识并重新创建任何缺失的资源。

Diagram that shows the steps for migrating a template to Bicep.

创建新的 Bicep 文件

最好是创建新的 Bicep 文件。 转换阶段创建的文件是查看的参考点，但不应将其视为最终文件或按原样部署。

将资源复制到新的 Bicep 文件

将已转换的 Bicep 文件中的每个资源逐个复制到新的 Bicep 文件。 此过程有助于逐个解决资源中的任何问题，并避免随着模板大小的增长而出现任何混淆。

重新创建不支持的资源

并非所有 Azure 资源类型都可以通过 Azure 门户、Azure CLI 或 Azure PowerShell 进行导出。 例如，DependencyAgentWindows 和 MMAExtension (Microsoft Monitoring Agent) 等虚拟机扩展就是无法导出的资源类型。

如果尝试通过 Azure 门户、Azure CLI 或 Azure PowerShell 导出资源并且包含不受支持的资源类型，则会生成详细的错误消息。 需要在新的 Bicep 文件中重新创建任何未导出的资源，例如虚拟机扩展。 可以选择若干工具和方法（包括 Azure 资源浏览器、ARM 模板参考和 Azure 快速启动模板）之一来重新创建资源。

Azure 资源浏览器

Azure 资源浏览器是嵌入在 Azure 门户中的工具。 门户不显示某些资源类型，但资源浏览器提供资源的 JSON 表示形式。 若要访问资源浏览器，请在搜索框中搜索它：

Screenshot of the Azure portal that shows the search box with resource explorer entered.

“结果”窗格显示订阅的已注册资源提供程序列表，以及你有权查看的所有资源、资源组和订阅的详细信息。 若要查看资源的 JSON 表示形式，请选择窗格左侧的层次结构：

Screenshot of the Azure portal that shows Azure Resource Explorer.

通过选择资源，可以查看 JSON 表示形式，如以下示例所示：

{
    "name": "DependencyAgentWindows",
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rg-app-prod-truckline/providers/Microsoft.Compute/virtualMachines/vm-prod-001/extensions/DependencyAgentWindows",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "location": "eastus",
    "properties": {
        "autoUpgradeMinorVersion": true,
        "provisioningState": "Succeeded",
        "publisher": "Microsoft.Azure.Monitoring.DependencyAgent",
        "type": "DependencyAgentWindows",
        "typeHandlerVersion": "9.10"
    }
}

可以使用 JSON 表示形式来定义 Bicep 资源：

resource dependencyAgentWindows 'Microsoft.Compute/virtualMachines/extensions@2022-08-01' = {
  parent: virtualMachine
  name: 'DependencyAgentWindows'
  location: 'eastus'
  properties: {
    autoUpgradeMinorVersion: true
    publisher: 'Microsoft.Azure.Monitoring.DependencyAgent'
    type: 'DependencyAgentWindows'
    typeHandlerVersion: '9.10'
  }
}

注意

JSON 表示形式包括名为 provisioningState 的属性。 provisioningState 属性是只读的，它由 Azure 自动设置，因此不包含在 Bicep 资源定义中。

提示

Visual Studio Code 的 Bicep 扩展可帮助你在 Bicep 中定义 Azure 资源。 例如，资源的 Bicep 表示形式包含 API 版本，但导出的 JSON 版本不包含。 在 Visual Studio Code 中，当你开始输入资源类型时，系统会自动建议 API 版本。

ARM 模板参考

ARM 模板参考是有关适用于 Azure 资源的 ARM 模板结构、资源类型、API 版本和属性定义的信息源。 该文档提供 Bicep 和 JSON 格式的示例。

可以选择特定的资源提供程序和资源类型（例如 Microsoft.Web/serverfarms）及其 API 版本。 你可以查看哪些资源属性是必需的，哪些是可选的。 你还可以查看属性说明，以便了解属性的用途。

Azure 快速入门模板

Azure 快速入门模板存储库是社区贡献模板的集合。 可在此存储库中搜索模板，里面提供了许多 Azure 资源和解决方案的示例。 在某些快速入门中，JSON ARM 模板和 Bicep ARM 模板都可查看。 可以将这些模板用作参考点，以便生成和验证用于部署的模板。

假设要查找生成 Azure 应用服务计划和应用的模板。 每个快速入门模板都提供了将模板直接部署到 Azure 或在 GitHub 上查看模板的选项。

Screenshot that shows an Azure Quickstart Template that deploys a basic Linux web app.

请记住，Azure 快速入门模板由社区贡献。 某些示例可能已经过时，因为 Azure 服务会定期增加一些功能。 这些示例还可能包括在使用模板时不需要的资源和属性。 但是，快速启动模板存储库是有用的资源，可帮助你了解如何使用 ARM 模板部署资源。