Azure 资源管理器模板规格(预览版)Azure Resource Manager template specs (Preview)

模板规格是一种资源类型,用于在 Azure 中存储 Azure 资源管理器模板(ARM 模板),以便之后进行部署。A template spec is a resource type for storing an Azure Resource Manager template (ARM template) in Azure for later deployment. 通过该资源类型,你可以与组织中的其他用户共享 ARM 模板。This resource type enables you to share ARM templates with other users in your organization. 与其他任何 Azure 资源一样,也可使用 Azure 基于角色的访问控制 (Azure RBAC) 来共享模板规格。Just like any other Azure resource, you can use Azure role-based access control (Azure RBAC) to share the template spec.

Microsoft.Resources/templateSpecs 是模板规格的资源类型。Microsoft.Resources/templateSpecs is the resource type for template specs. 它包含一个主模板和任意数量的链接模板。It consists of a main template and any number of linked templates. Azure 将模板规格安全存储在资源组中。Azure securely stores template specs in resource groups. 模板规格支持版本控制Template Specs support versioning.

若要部署模板规格,请使用标准 Azure 工具(如 PowerShell)、Azure CLI、Azure 门户、REST 和其他受支持的 SDK 和客户端。To deploy the template spec, you use standard Azure tools like PowerShell, Azure CLI, Azure portal, REST, and other supported SDKs and clients. 请使用针对模板使用的相同命令。You use the same commands as you would for the template.

备注

模板规格当前提供预览版。Template Specs is currently in preview. 若要将其与 Azure PowerShell 一起使用,必须安装版本 5.0.0 或更高版本To use it with Azure PowerShell, you must install version 5.0.0 or later. 若要将其与 Azure CLI 一起使用,请使用版本 2.14.2 或更高版本To use it with Azure CLI, use version 2.14.2 or later.

为什么使用模板规格?Why use template specs?

如果 GitHub 存储库或存储帐户中当前有模板,在尝试共享和使用这些模板时会遇到一些困难。If you currently have your templates in a GitHub repo or storage account, you run into several challenges when trying to share and use the templates. 如果用户要部署这些模板,要么模板必须是本地模板,要么它的 URL 必须是可公开访问的。For a user to deploy it, the template must either be local or the URL for the template must be publicly accessible. 为应对此限制,你可能要与需要部署模板的用户共享该模板的副本,或者开放对存储库或存储帐户的访问权限。To get around this limitation, you might share copies of the template with users who need to deploy it, or open access to the repo or storage account. 如果用户拥有模板的本地副本,这些副本最终可能会与原始模板有所不同。When users own local copies of a template, these copies can eventually diverge from the original template. 当将存储库或存储帐户设置为可公开访问时,可能会导致非预期用户能够访问模板。When you make a repo or storage account publicly accessible, you may allow unintended users to access the template.

使用模板规格的好处是,可以创建规范化的模板并与组织中的团队共享。The benefit of using template specs is that you can create canonical templates and share them with teams in your organization. 模板规格是安全的,因为 Azure 资源管理器可使用它进行部署,而没有 Azure RBAC 权限的用户则无法访问。The template specs are secure because they're available to Azure Resource Manager for deployment, but not accessible to users without Azure RBAC permission. 用户只需具有模板规格的读取访问权限即可部署模板,因此可以在不允许其他人进行修改的情况下共享该模板。Users only need read access to the template spec to deploy its template, so you can share the template without allowing others to modify it.

模板规格中包含的模板应由组织中的管理员按照组织的要求和指南进行验证。The templates you include in a template spec should be verified by administrators in your organization to follow the organization's requirements and guidance.

创建模板规格Create template spec

以下示例显示了一个用于在 Azure 中创建存储帐户的简单模板。The following example shows a simple template for creating a storage account in Azure.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "storageAccountType": {
            "type": "string",
            "defaultValue": "Standard_LRS",
            "allowedValues": [
                "Standard_LRS",
                "Standard_GRS",
                "Premium_LRS"
            ]
        }
    },
    "resources": [
        {
            "type": "Microsoft.Storage/storageAccounts",
            "apiVersion": "2019-06-01",
            "name": "[concat('store', uniquestring(resourceGroup().id))]",
            "location": "[resourceGroup().location]",
            "kind": "StorageV2",
            "sku": {
                "name": "[parameters('storageAccountType')]"
            }
        }
    ]
}

创建模板规格时,会将 PowerShell 或 CLI 命令传递给主模板文件。When you create the template spec, the PowerShell or CLI commands are passed the main template file. 如果主模板引用链接模板,则命令将查找并打包它们以创建模板规格。若要了解详细信息,请参阅创建具有链接模板的模板规格If the main template references linked templates, the commands will find and package them to create the template spec. To learn more, see Create a template spec with linked templates.

使用以下命令创建模板规格:Create a template spec by using:

New-AzTemplateSpec -Name storageSpec -Version 1.0a -ResourceGroupName templateSpecsRg -Location chinanorth2 -TemplateFile ./mainTemplate.json

可以使用以下命令查看订阅中的所有模板规格:You can view all template specs in your subscription by using:

Get-AzTemplateSpec

可以使用以下命令查看模板规格的详细信息(包括其版本):You can view details of a template spec, including its versions with:

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

部署模板规格Deploy template spec

创建模板规格后,具有对模板规格的读取访问权限的用户可以部署它。After you've created the template spec, users with read access to the template spec can deploy it. 有关授予访问权限的信息,请参阅教程:使用 Azure PowerShell 授予组对 Azure 资源的访问权限For information about granting access, see Tutorial: Grant a group access to Azure resources using Azure PowerShell.

可通过门户、PowerShell、Azure CLI 部署模板规格,或者在更大型的模板部署中将其作为链接模板进行部署。Template specs can be deployed through the portal, PowerShell, Azure CLI, or as a linked template in a larger template deployment. 组织中的用户可以将模板规格部署到 Azure 中的任何范围(资源组、订阅、管理组或租户)。Users in an organization can deploy a template spec to any scope in Azure (resource group, subscription, management group, or tenant).

可通过提供模板规格的资源 ID 来部署该模板规格,而无需传递模板的路径或 URI。Instead of passing in a path or URI for a template, you deploy a template spec by providing its resource ID. 资源 ID 采用以下格式:The resource ID has the following format:

/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Resources/templateSpecs/{template-spec-name}/versions/{template-spec-version}

请注意,资源 ID 包括模板规格的版本名称。Notice that the resource ID includes a version name for the template spec.

例如,可以使用以下命令部署模板规格。For example, you deploy a template spec with the following command.

$id = "/subscriptions/11111111-1111-1111-1111-111111111111/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG

实际上,通常需要运行 Get-AzTemplateSpecaz ts show 来获取要部署的模板规格的 ID。In practice, you'll typically run Get-AzTemplateSpec or az ts show to get the ID of the template spec you want to deploy.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0a).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

参数Parameters

将参数传递到模板规格与将参数传递到 ARM 模板的过程是完全相同的。Passing in parameters to template spec is exactly like passing parameters to an ARM template. 以内联方式添加参数值或将参数值添加到参数文件中。Add the parameter values either inline or in a parameter file.

若要以内联方式传递参数,请使用:To pass a parameter inline, use:

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -StorageAccountType Standard_GRS

若要创建本地参数文件,请使用:To create a local parameter file, use:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "StorageAccountType": {
      "value": "Standard_GRS"
    }
  }
}

并使用以下命令传递该参数文件:And, pass that parameter file with:

New-AzResourceGroupDeployment `
  -TemplateSpecId $id `
  -ResourceGroupName demoRG `
  -TemplateParameterFile ./mainTemplate.parameters.json

创建具有链接模板的模板规格Create a template spec with linked templates

如果模板规格的主模板引用了链接模板,则 PowerShell 和 CLI 命令可以自动查找并打包本地驱动器中的链接模板。If the main template for your template spec references linked templates, the PowerShell and CLI commands can automatically find and package the linked templates from your local drive. 无需手动配置存储帐户或存储库即可托管模板规格 - 模板规格资源中包含了所有内容。You don't need to manually configure storage accounts or repositories to host the template specs - everything is self-contained in the template spec resource.

以下示例中包含了具有两个链接模板的主模板。The following example consists of a main template with two linked templates. 该示例只是模板的摘录。The example is only an excerpt of the template. 请注意,它使用名为 relativePath 的属性链接到其他模板。Notice that it uses a property named relativePath to link to the other templates. 必须为部署资源使用 2020-06-01apiVersion 或更高版本。You must use apiVersion of 2020-06-01 or later for the deployments resource.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/webapp.json"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "relativePath": "artifacts/database.json"
        }
      }
    }
  ],
  "outputs": {}
}

在上一个示例中执行用于创建模板规格的 PowerShell 或 CLI 命令时,该命令会查找三个文件 - 主模板、Web 应用模板 (webapp.json) 和数据库模板 (database.json) - 并将它们打包到模板规格中。When the PowerShell or CLI command to create the template spec is executed for the preceding example, the command finds three files - the main template, the web app template (webapp.json), and the database template (database.json) - and packages them into the template spec.

有关详细信息,请参阅教程:创建具有链接模板的模板规格For more information, see Tutorial: Create a template spec with linked templates.

将模板规格部署为链接模板Deploy template spec as a linked template

创建模板规格之后,可以轻松从 ARM 模板或其他模板规格中重复使用它。可以通过将模板规格的资源 ID 添加到模板来链接该模板规范。Once you've created a template spec, it's easy to reuse it from an ARM template or another template spec. You link to a template spec by adding its resource ID to your template. 部署主模板时,会自动部署链接的模板规格。The linked template spec is automatically deployed when you deploy the main template. 此行为使你能够开发模块化模板规范并根据需要重复利用。This behavior lets you develop modular template specs, and reuse them as needed.

例如,可以创建一个用于部署网络资源的模板模板规格和一个用于部署存储资源的模板规格。For example, you can create a template spec that deploys networking resources, and another template spec that deploys storage resources. 在 ARM 模板中,可随时在需要配置网络或存储资源时链接到这两个模板规格。In ARM templates, you link to these two template specs anytime you need to configure networking or storage resources.

以下示例与前面的示例的类似,不同的是使用 id 属性链接到模板规格,而不是使用 relativePath 属性链接到本地模板。The following example is similar to the earlier example, but you use the id property to link to a template spec rather than the relativePath property to link to a local template. 使用 2020-06-01 作为部署资源的 API 版本。Use 2020-06-01 for API version for the deployments resource. 在此示例中,模板规格位于名为 templateSpecsRG 的资源组中。In the example, the template specs are in a resource group named templateSpecsRG.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  ...
  "resources": [
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "networkingDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'networkingSpec', '1.0a')]"
        }
      }
    },
    {
      "type": "Microsoft.Resources/deployments",
      "apiVersion": "2020-06-01",
      "name": "storageDeployment",
      ...
      "properties": {
        "mode": "Incremental",
        "templateLink": {
          "id": "[resourceId('templateSpecsRG', 'Microsoft.Resources/templateSpecs/versions', 'storageSpec', '1.0a')]"
        }
      }
    }
  ],
  "outputs": {}
}

有关链接模板规格的详细信息,请参阅教程:将模板规格部署为链接模板For more information about linking template specs, see Tutorial: Deploy a template spec as a linked template.

版本控制Versioning

创建模板规格时,需要为其提供版本名称。When you create a template spec, you provide a version name for it. 循环访问模板代码时,可以更新现有版本(获取修补程序)或发布新版本。As you iterate on the template code, you can either update an existing version (for hotfixes) or publish a new version. 版本是文本字符串。The version is a text string. 可以选择遵循任意版本控制系统,包括语义化版本控制。You can choose to follow any versioning system, including semantic versioning. 模板规格的用户可提供部署模板规格时要使用的版本名称。Users of the template spec can provide the version name they want to use when deploying it.

后续步骤Next steps