Спецификации шаблонов Azure Resource Manager

Статья
03/20/2024

Спецификация шаблона — это тип ресурса для хранения шаблонов Azure Resource Manager (шаблонов ARM) в Azure для развертывания в дальнейшем. Этот тип ресурсов позволяет предоставлять общий доступ к шаблонам ARM другим пользователям в вашей организации. Как и с любым другим ресурсом Azure, для него можно применять управление доступом на основе ролей Azure (Azure RBAC), чтобы предоставить общий доступ к спецификациям шаблонов.

Microsoft.Resources/templateSpecs — тип ресурса для спецификаций шаблонов. Он состоит из основного шаблона и любого количества связанных шаблонов. Azure безопасно хранит спецификации шаблонов в группах ресурсов. Спецификации шаблонов поддерживают управление версиями.

Для развертывания спецификации шаблона используются стандартные инструменты Azure, такие как: PowerShell, Azure CLI, портал Azure, REST и другие поддерживаемые пакеты SDK и клиенты. Для них используются те же команды, что и для шаблонов.

Примечание.

Чтобы использовать спецификацию шаблона с Azure PowerShell, необходимо установить версию 5.0.0 или более новую. Чтобы использовать их с Azure CLI, воспользуйтесь версией 2.14.2 или более новой.

При разработке развертывания всегда учитывайте жизненный цикл ресурсов и группируйте ресурсы, которые совместно используют аналогичный жизненный цикл в одну спецификацию шаблона. Например, развертывания включают несколько экземпляров Azure Cosmos DB с каждым экземпляром, содержащим собственные базы данных и контейнеры. Учитывая, что базы данных и контейнеры не изменяются много, необходимо создать одну спецификацию шаблона, чтобы включить экземпляр Cosmos DB и его базовые базы данных и контейнеры. Затем с помощью условных операторов в шаблонах вместе с циклами копирования можно создать несколько экземпляров этих ресурсов.

Обучающие материалы

Дополнительные информацию о спецификациях шаблонов и практические инструкции см. в руководстве по публикации библиотек кода инфраструктуры для повторного использования с помощью спецификаций шаблонов.

Совет

Мы рекомендуем использовать Bicep, так как он предоставляет те же возможности, что и шаблоны ARM, и имеет более простой синтаксис. Дополнительные сведения см. в статье Спецификации шаблонов Azure Resource Manager.

Зачем использовать спецификации шаблонов?

Спецификации шаблонов обеспечивают следующие преимущества:

Для спецификаций шаблонов используются стандартные шаблоны ARM.
Управление доступом к ним осуществляется посредством Azure RBAC, а не с помощью маркеров SAS.
Пользователи могут развернуть спецификацию шаблона без доступа на запись к шаблону.
Спецификацию шаблона можно интегрировать в существующий процесс развертывания, например в сценарий PowerShell или конвейер DevOps.

Спецификации шаблонов позволяют создавать канонические шаблоны и использовать их совместно с командами разработчиков в вашей организации. Спецификации шаблонов безопасны, поскольку они доступны в Azure Resource Manager для развертывания, но недоступны пользователям, у которых нет правильных разрешений. Пользователям необходим только доступ на чтение к спецификации шаблона, чтобы развернуть по ней шаблон, так что к шаблону можно предоставить общий доступ, не позволяя никому вносить в него изменения.

Если у вас есть шаблоны в репозитории GitHub или учетной записи хранения, то при попытках совместного использования шаблонов и предоставления общего доступа к ним возникают некоторые сложности. Чтобы развернуть шаблон, нужно либо сделать шаблон общедоступным, либо управлять доступом к нему с помощью маркеров SAS. Чтобы обойти это ограничение, пользователи могут создавать локальные копии, которые со временем расходятся с оригинальным шаблоном. Спецификации шаблонов упрощают общий доступ к шаблонам.

Шаблоны, включаемые в спецификацию шаблона, должны быть проверены администраторами вашей организации на соответствие требованиям и рекомендациям организации.

Необходимые разрешения

Для спецификации шаблона определены две роли сборки Azure:

Кроме того, вам также требуются разрешения для развертывания Bicep-файла. См. статью "Развертывание — ИНТЕРФЕЙС командной строки " или "Развертывание" — PowerShell.

Создание спецификации шаблона

В следующем примере показан простой шаблон для создания учетной записи хранения в 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",
        "Standard_ZRS",
        "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 передаются в основной файл шаблона. Если основной шаблон ссылается на связанные шаблоны, команды обнаружат их и упакуют, чтобы создать спецификацию шаблона. Дополнительные сведения см. в разделе Создание спецификации шаблона со связанными шаблонами.

Создание спецификации шаблона с помощью:

PowerShell
CLI

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

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

Спецификации шаблонов можно также создавать с помощью шаблонов ARM. Приведенный ниже шаблон создает спецификацию шаблона для развертывания учетной записи хранения:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "templateSpecName": {
      "type": "string",
      "defaultValue": "CreateStorageAccount"
    },
    "templateSpecVersionName": {
      "type": "string",
      "defaultValue": "0.1"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/templateSpecs",
      "apiVersion": "2021-05-01",
      "name": "[parameters('templateSpecName')]",
      "location": "[parameters('location')]",
      "properties": {
        "description": "A basic templateSpec - creates a storage account.",
        "displayName": "Storage account (Standard_LRS)"
      }
    },
    {
      "type": "Microsoft.Resources/templateSpecs/versions",
      "apiVersion": "2021-05-01",
      "name": "[format('{0}/{1}', parameters('templateSpecName'), parameters('templateSpecVersionName'))]",
      "location": "[parameters('location')]",
      "dependsOn": [
        "[resourceId('Microsoft.Resources/templateSpecs', parameters('templateSpecName'))]"
      ],
      "properties": {
        "mainTemplate": {
          "$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",
                "Standard_ZRS",
                "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')]"
              }
            }
          ]
        }
      }
    }
  ]
}

Размер спецификации шаблона ограничен примерно на уровне 2 МБ. Если размер спецификации шаблона превысит это ограничение, вы получите ошибку с кодом TemplateSpecTooLarge. Сообщение об ошибке будет следующим:

The size of the template spec content exceeds the maximum limit. For large template specs with many artifacts, the recommended course of action is to split it into multiple template specs and reference them modularly via TemplateLinks.

Все спецификации шаблонов в подписке можно просмотреть с помощью:

PowerShell
CLI

Get-AzTemplateSpec

az ts list

Подробные сведения о спецификации шаблона, в том числе о ее версиях, можно просмотреть с помощью:

PowerShell
CLI

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

az ts show \
    --name storageSpec \
    --resource-group templateSpecRG \
    --version "1.0a"

Развертывание спецификации шаблона

После создания спецификации шаблона пользователи с ролью читателя спецификаций шаблона могут развернуть его. Кроме того, вам также требуются разрешения для развертывания шаблона ARM. См. статью "Развертывание — ИНТЕРФЕЙС командной строки " или "Развертывание" — PowerShell.

Спецификации шаблонов можно развернуть с помощью портала, PowerShell, Azure CLI или в виде связанного шаблона в более крупном шаблоне развертывания. Пользователи в организации могут развернуть спецификацию шаблона в любой области в Azure (в группе ресурсов, подписке, группе управления или на клиенте).

Вместо передачи пути или URI для шаблона спецификация шаблона развертывается посредством указания ее идентификатора ресурса. Идентификатор ресурса имеет следующий формат:

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

Обратите внимание, что идентификатор ресурса включает имя версии для спецификации шаблона.

Например, вы развертываете спецификацию шаблона с помощью следующей команды:

PowerShell
CLI

$id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

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

id = "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/templateSpecsRG/providers/Microsoft.Resources/templateSpecs/storageSpec/versions/1.0a"

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

На практике вы обычно выполняете команду Get-AzTemplateSpec или az ts show, чтобы получить идентификатор спецификации шаблона, которую вы будете развертывать.

PowerShell
CLI

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

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

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0a" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

Также, чтобы развернуть спецификацию шаблона, можно открыть URL-адрес в следующем формате:

https://portal.azure.com/#create/Microsoft.Template/templateSpecVersionId/%2fsubscriptions%2f{subscription-id}%2fresourceGroups%2f{resource-group-name}%2fproviders%2fMicrosoft.Resources%2ftemplateSpecs%2f{template-spec-name}%2fversions%2f{template-spec-version}

Параметры

Передача параметров в спецификацию шаблона в точности совпадает с передачей параметров в шаблон ARM. Добавляйте значения параметров либо внутрь строк, либо из файла параметров.

Чтобы передать параметры внутри строк, используйте:

PowerShell
CLI

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters storageAccountType='Standard_GRS'

Чтобы создать локальный файл параметров, используйте:

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

Затем передайте этот файл параметров, используя:

PowerShell
CLI

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

az deployment group create \
  --resource-group demoRG \
  --template-spec $id \
  --parameters "./mainTemplate.parameters.json"

Управление версиями

При создании спецификации шаблона вы задаете для нее имя версии. При дальнейших итерациях разработки кода шаблона можно либо обновлять существующую версию (для оперативных исправлений), либо опубликовать новую версию. Версия задается в текстовой строке. Можно выбрать любую систему обозначения версий, включая семантическое версионирование. Пользователи спецификации шаблона могут задавать имя версии, которую они хотят использовать, при развертывании спецификации. У вас может быть неуправляемое количество версий.

Использование тегов

Теги помогают логически упорядочивать ресурсы. Теги можно добавить в спецификацию шаблона с помощью Azure PowerShell или Azure CLI.

PowerShell
CLI

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.json `
  -Tag @{Dept="Finance";Environment="Production"}

az ts create \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json" \
  --tags Dept=Finance Environment=Production

PowerShell
CLI

Set-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0a `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateFile ./mainTemplate.json `
  -Tag @{Dept="Finance";Environment="Production"}

az ts update \
  --name storageSpec \
  --version "1.0a" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json" \
  --tags Dept=Finance Environment=Production

При создании или изменении спецификации шаблона с указанным параметром версии, но без параметра тега (-ов):

Если спецификация шаблона существует и содержит теги, но указанная версия не существует, новая версия наследует те же теги, что были у существующей спецификации шаблона.

При создании или изменении спецификации шаблона, у которой указаны и параметр тега (-ов), и параметр версии:

Если не существуют ни спецификация шаблона, ни версия, то теги добавляются как в новую спецификацию шаблона, так и в новую версию.
Если спецификация шаблона существует, но версия не существует, теги добавляются только в новую версию.
Если существует и спецификация шаблона, и версия, теги применяются только к этой версии.

При изменении шаблона с указанным параметром тега (-ов), но без указанного параметра версии, теги добавляются только к спецификации шаблона.

Создание спецификации шаблона со связанными шаблонами

Если основной шаблон для спецификации шаблона ссылается на связанные шаблоны, команды PowerShell и CLI могут автоматически находить и упаковывать связанные шаблоны с локального диска. Настраивать вручную учетные записи или репозитории для размещения спецификаций шаблонов не требуется — все необходимое автономно реализовано в ресурсе спецификации шаблона.

Следующий пример состоит из основного шаблона с двумя связанными шаблонами. Этот пример содержит только выдержку из шаблона. Обратите внимание, что в нем используется свойство relativePath связи с другими шаблонами. Для ресурса развертываний необходимо использовать apiVersion от 2020-06-01 или более позднюю версию.

{
  "$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 создания спецификации шаблона из предыдущего примера эта команда обнаружит три файла — основной шаблон, шаблон веб-приложения (webapp.json) и шаблон базы данных (database.json), а затем упакует их в спецификацию шаблона.

Дополнительные сведения см. в статье Учебник. Создание спецификации шаблона со связанными шаблонами.

Развертывание спецификации шаблона как связанного шаблона

После создания спецификации шаблона ее можно легко использовать повторно из шаблона ARM или другой спецификации шаблона. Чтобы добавить ссылку на спецификацию шаблона, добавьте ее идентификатор ресурса в шаблон, с которым вы работаете. Спецификация связанного шаблона автоматически развертывается при развертывании основного шаблона. Эта схема работы позволяет разрабатывать модульные спецификации шаблонов и повторно использовать их по мере необходимости.

Например, можно создать спецификацию шаблона, которая развертывает сетевые ресурсы, и другую спецификацию шаблона, которая развертывает ресурсы хранилища. В шаблонах ARM можно ссылаться на эти две спецификации шаблонов в любой момент, когда понадобится настроить сетевые ресурсы или ресурсы хранилища.

Следующий пример схож с предыдущим, но в нем вместо использования свойства relativePath для связывания с локальным шаблоном используется свойство id для связывания со спецификацией шаблона. Используйте API версии 2020-06-01 для ресурсов развертываний. В этом примере спецификации шаблонов находятся в группе ресурсов под именем 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": {}
}

Дополнительные сведения о связывании спецификаций шаблонов см. в статье Учебник. Развертывание спецификации шаблона как связанного шаблона.

Следующие шаги

Сведения о создании и развертывании спецификаций шаблонов см. в статье Краткое руководство. Создание и развертывание спецификации шаблона.
Дополнительные сведения о связывании шаблонов в спецификациях шаблонов см. в статье Учебник. Создание спецификации шаблона со связанными шаблонами.
Дополнительные сведения о развертывании спецификации шаблона в качестве связанного шаблона см. в разделе Учебник. Развертывание спецификации шаблона в качестве связанного шаблона.

Поделиться через