创建和使用 Bicep 模块

  • 10 分钟

模块是独立的 Bicep 文件。 它们通常包含一同部署的资源集。 可从任何其他 Bicep 模板中使用模块。

通过使用模块，可重用 Bicep 代码，使 Bicep 文件更容易阅读和理解，因为它们都侧重于特定作业。 然后，main 模板将多个模块组合在一起。

模块的优势

在你的玩具公司中，你一直在使用许多单独的 Bicep 文件预配云资源。 随着时间的推移，这些模板会显著增多。 最终，你会获得难以读取和导航，甚至难以维护的单片代码。

当你想要在其他模板中重复使用部分代码时，此方法还会强制复制这些代码部分。 更改某些内容时，需要搜索并更新多个文件。

Bicep 模块将代码拆分为多个模板可引用的更小、更易于管理的文件，从而帮助你应对这些难题。 模块为你提供了一些关键优势。

可重用性

创建模块后，可在多个 Bicep 文件中重复使用它，即使这些文件用于不同的项目或工作负载。 例如，生成一个解决方案时，可能会为应用组件、数据库和网络相关资源创建单独的模块。 然后，当你开始处理具有类似网络要求的另一项目时，可重复使用相关模块。

Diagram that shows a template referencing three modules: application, database, and networking. The networking module is then reused in another template.

甚至可在团队、组织内部或 Azure 社区中共享模块。 你将在未来的 Microsoft Learn 模块中详细了解如何共享 Bicep 模块。

封装

模块有助于将相关资源定义放在一起。 例如，定义 Azure Functions 应用时，通常会部署应用、应用的托管计划，以及应用元数据的存储帐户。 这三个组件是单独定义的，但它们表示资源的逻辑分组，因此，建议将它们定义为模块。

这样一来，main 模板便无需了解函数应用部署方式的详细信息。 模块负责了解这一点。

可组合性

创建一组模块后，可将它们组合在一起。 例如，可创建一个部署虚拟网络的模块和另一个部署虚拟机的模块。 为每个模块定义参数和输出，以便可从一个模块获取重要信息并将其发送到另一模块。

Diagram that shows a template referencing two modules and passing the output from one to the parameter of another.

提示

将 Bicep 模块视为可以不同方式组合来支持部署的构建基块是很有帮助的。

功能

有时，可能需要使用模块来访问某些功能。 例如，可将模块和循环一起用于多组资源的部署。 还可在一个部署中使用模块来定义不同范围的资源。

创建模块

一个模块是一个普通的 Bicep 文件。 创建 Bicep 模块的方式与创建任何其他 Bicep 文件相同。

通常，为部署的每个资源创建模块并不是一个好做法。 一个良好的 Bicep 模块通常可定义多个相关资源。 但是，如果你有一个具有大量配置的复杂资源，创建一个单一的模块来封装复杂性可能是合理的。 此方法可使 main 模板保持简单且不杂乱。

将现有 Bicep 模板拆分为模块

你可以构建一个大型 Bicep 模板，然后再决定是否应将它拆分为模块。 有时，应如何拆分大型 Bicep 文件是很显而易见的。 你可能有一组明确属于某一模块的资源。 而其他时候，确定是否应将资源分组到一个模块并不那么简单。

Bicep 可视化工具可帮助你将整个 Bicep 文件置于透视中。 可视化工具包含在适用于 Visual Studio Code 的 Bicep 扩展中。

若要查看可视化工具，请打开“Visual Studio Code 资源管理器”，选择并按住（或右键单击）Bicep 文件，然后选择“打开 Bicep 可视化工具”。 可视化工具显示 Bicep 文件中资源的图形表示形式。 它包含资源之间的行，用于显示 Bicep 检测到的依赖项。

可使用可视化工具帮助你拆分文件。 查看可视化效果是否说明了任何资源群集。 建议将这些群集一起移动到模块中。

例如，请看以下 Bicep 文件的可视化效果。 定义了两组不同的资源。 建议将它们分组到单独的 database 和 networking 模块中。

嵌套模块

模块中可包含其他模块。 通过使用此嵌套技术，可创建一些部署小型资源集的模块，然后将这些模块组合成定义复杂资源拓扑的较大型模块。 模板将这些部分合并为一个可部署的项目。

提示

虽然可嵌套多个模块层，但可能会变得复杂。 如果出现错误或其他问题，则当有许多嵌套层时，会更难找出需要修复的问题。

对于复杂的部署，有时使用部署管道来部署多个模板是合理的，而不是创建一个使用嵌套完成所有操作的模板。 你将在未来的 Microsoft Learn 模块中详细了解部署管道。

选择好的文件名

请务必对每个模块使用描述性文件名。 文件名实际上成为了模块的标识符。 请务必确保你的同事只需查看文件名，就可了解模块的用途。

在 Bicep 模板中使用模块

通过使用 module 关键字在 Bicep 模板中使用模块，如下所示：

module appModule 'modules/app.bicep' = {
  name: 'myApp'
  params: {
    location: location
    appServiceAppName: appServiceAppName
    environmentType: environmentType
  }
}

模块定义包括以下组件：

  • module 关键字。
  • 符号名称，比如 appModule。 每当要引用模块时，都会在此 Bicep 文件内使用此名称。 符号名称永远不会显示在 Azure 中。
  • 模块路径，比如 modules/app.bicep。 这通常是本地文件系统上 Bicep 文件的路径。 在未来的 Microsoft Learn 模块中，你将了解如何使用注册表和模板规格（它们具有其自己的模块路径格式）来共享模块。

    提示

    还可将 JSON Azure 资源管理器模板（ARM 模板）用作模块。 如果你有一组尚未迁移到 Bicep 的模板，此功能会很有帮助。

  • name 属性，可指定部署名称。 你将在下一部分详细了解部署。
  • params 属性，可在其中为模块期望的参数指定值。 你将在下一单元详细了解模块参数。

模块的工作原理

了解模块的的工作原理并不是使用它们的必要条件，但这有助于你调查部署中的问题或有助于解释意外行为。

部署

Azure 中的“部署”是一种表示部署操作的特殊资源。 部署是资源类型为 Microsoft.Resources/deployments 的 Azure 资源。 提交 Bicep 部署时，要创建或更新部署资源。 同样，在 Azure 门户中创建资源时，该门户会代表你创建部署资源。

但是，并非所有针对 Azure 资源的更改都要创建或使用部署。 例如，使用 Azure 门户修改现有资源时，通常不需要创建部署来做出更改。 使用 Terraform 等第三方工具部署或配置资源时，它们可能不会创建部署。

使用 Azure CLI 或 Azure PowerShell 部署 Bicep 文件时，可选择指定部署的名称。 如不指定名称，则 Azure CLI 或 Azure PowerShell 会自动根据模板的文件名创建部署名称。 例如，如果部署名为“main.bicep”的文件，则默认部署名称为 main。

使用模块时，Bicep 会为每个模块创建单独的部署。 你为模块指定的 name 属性将成为部署的名称。 部署包含模块的 Bicep 文件时，会创建多个部署资源：其中一个用于父模板，其他的用于每个模块。

例如，假设创建名为“main.bicep”的 Bicep 文件。 它会定义一个名为 myApp 的模块。 部署“main.bicep”文件时，将创建两个部署。 第一个部署名为 main，它创建的另一个部署名为 myApp，其中包含应用程序资源。

Diagram that shows two Bicep files, each of which has a separate deployment name.

你可以列出并查看部署资源的详细信息，以监视 Bicep 部署的状态，或查看部署的历史记录。 但是，当你对部署重复使用同一名称时，Azure 将覆盖同名的上一个部署。 如果需要维护部署历史记录，请确保针对每个部署使用唯一名称。 可在名称中包括部署的日期和时间，以帮助确保其唯一性。

生成的 JSON ARM 模板

部署 Bicep 文件时，Bicep 将其转换为 JSON ARM 模板。 此转换也称为“转译”。 模板使用的模块将嵌入到 JSON 文件中。 无论模板中包括多少个模块，都只会创建一个 JSON 文件。

在上一部分讨论的示例中，即使最初有两个 Bicep 文件，Bicep 也只生成一个 JSON 文件。

Diagram that shows two Bicep files, which are transpiled into a single JSON file.