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

Статья
01/10/2025

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

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

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

Примечание.

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

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

Совет

Выбор между реестром модулей и спецификациями шаблонов определяется в основном личными предпочтениями. Но при выборе между этими двумя вариантами следует учитывать ряд моментов.

Реестр модулей поддерживается только для Bicep. Если вы пока не используете Bicep, выбирайте спецификации шаблонов.
Содержимое в реестре модулей Bicep можно развернуть только из другого файла Bicep. Спецификации шаблонов можно развертывать непосредственно из API, Azure PowerShell, Azure CLI или на портале Azure. Вы можете даже использовать UiFormDefinition для настройки портал Azure развертывания.
Bicep предоставляет ограниченную поддержку для внедрения других артефактов проекта, включая файлы, отличные от Bicep, и файлы, отличные от файлов шаблонов ARM (например, скрипты PowerShell, скрипты CLI и другие двоичные файлы), с помощью функций loadTextContent и loadFileAsBase64. Спецификации шаблонов не умеют упаковывать такие артефакты.

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

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

Кроме того, вам также требуются разрешения для развертывания Bicep-файла. См. статью "Развертывание Bicep-файлов с помощью Azure CLI " или Azure PowerShell.

Почему используются спецификации шаблонов

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

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

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

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

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

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

В следующем примере показан простой файл Bicep для создания учетной записи хранения в Azure.

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

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

Azure PowerShell
Azure CLI

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

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

Вы также можете использовать файлы Bicep для создания спецификаций шаблонов. Однако содержимое mainTemplate должно находиться в ФОРМАТЕ JSON. Приведенный ниже шаблон создает спецификацию шаблона для развертывания учетной записи хранения:

param templateSpecName string = 'CreateStorageAccount'
param templateSpecVersionName string = '0.1'
param location string = resourceGroup().location

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2022-02-01' = {
  name: templateSpecName
  location: location
  properties: {
    description: 'A basic templateSpec - creates a storage account.'
    displayName: 'Storage account (Standard_LRS)'
  }
}

resource createTemplateSpecVersion 'Microsoft.Resources/templateSpecs/versions@2022-02-01' = {
  parent: createTemplateSpec
  name: templateSpecVersionName
  location: location
  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': '2023-04-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

В шаблон JSON, внедренный в файл Bicep, необходимо внести такие изменения:

Удалите запятые в конце строк.
Замените двойные кавычки одними кавычками.
Экранируйте одинарные кавычки в выражениях. Например, так: 'name': '[parameters(\'storageAccountType\')]'.
Для обращения к параметрам и переменным, определенным в файле Bicep, можно напрямую использовать их имена. Чтобы получить доступ к параметрам и переменным, определенным в mainTemplate, необходимо использовать синтаксис шаблона JSON ARM. Например, так: 'name': '[parameters(\'storageAccountType\')]'.
Для вызова функций Bicep используйте синтаксис Bicep. Например, 'location': resourceGroup().location.

Размер спецификации шаблона ограничен приблизительно 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.

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

Azure PowerShell
Azure CLI

Get-AzTemplateSpec

az ts list

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

Azure PowerShell
Azure CLI

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

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

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

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

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

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

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

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

Azure PowerShell
Azure 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, чтобы получить идентификатор спецификации шаблона, которую вы будете развертывать.

Azure PowerShell
Azure 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}

Параметры

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

Встроенные параметры

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

Azure PowerShell
Azure CLI

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

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

Файлы параметров

Используйте файлы параметров Bicep.

Необходимо указать инструкцию using для создания файла параметров Bicep. Например:
```
using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'
```
Дополнительные сведения см. в разделе "Создание файлов параметров для развертывания Bicep".

Передайте файлы параметров с помощью:
- Azure PowerShell
- Azure CLI
Вы не можете использовать PowerShell для развертывания спецификации шаблона с файлом .bicepparam в настоящее время.
```
az deployment group create \
  --resource-group demoRG \
  --parameters "./mainTemplate.bicepparam"
```
Не нужно указывать --template-spec параметр из-за using инструкции .bicepparam в файле.

Используйте файлы параметров JSON.

Ниже приведен пример файла параметров JSON:

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

Вы также можете передать файл параметров с помощью:

Azure PowerShell
Azure 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 для добавления тегов в спецификации шаблонов. В следующем примере показано, как указать теги при создании спецификации шаблона:

Azure PowerShell
Azure CLI

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

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

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

Azure PowerShell
Azure CLI

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

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

Как шаблон, так и его версии могут иметь теги. Теги применяются или наследуются в зависимости от указанных параметров:

Спецификация шаблона	Версия	Параметр версии	Параметр тега	Значения тегов
Exists	Н/П	Не указано	Указано	применяется к спецификации шаблона
Exists	Новый	Указано	Не указано	наследуется от спецификации шаблона к версии
Новый	Новый	Указано	Указано	применяется как к спецификации шаблона, так и к версии
Exists	Новый	Указано	Указано	применяется к версии
Exists	Exists	Указано	Указано	применяется к версии

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

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

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

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

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