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

  • Статья

Спецификация шаблона — это особый тип ресурса для хранения шаблона 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 для настройки интерфейса развертывания на портале.
  • Bicep предоставляет ограниченную поддержку для внедрения других артефактов проекта, включая файлы, отличные от Bicep, и файлы, отличные от файлов шаблонов ARM (например, скрипты PowerShell, скрипты CLI и другие двоичные файлы), с помощью функций loadTextContent и loadFileAsBase64. Спецификации шаблонов не умеют упаковывать такие артефакты.

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

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

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

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

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

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

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

  • Для спецификаций шаблонов используются стандартные шаблоны ARM или файлы Bicep.
  • Управление доступом к ним осуществляется посредством Azure RBAC, а не с помощью маркеров SAS.
  • Пользователи могут развернуть спецификацию шаблона без доступа на запись к файлу 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@2021-04-01' = {
  name:  'store${uniqueString(resourceGroup().id)}'
  location: resourceGroup().location
  sku: {
    name: storageAccountType
  }
  kind:'StorageV2'
}

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

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

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

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

resource createTemplateSpec 'Microsoft.Resources/templateSpecs@2021-05-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@2021-05-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': '2019-06-01'
          'name': 'store$uniquestring(resourceGroup().id)'
          'location': resourceGroup().location
          'kind': 'StorageV2'
          'sku': {
            'name': '[parameters(\'storageAccountType\')]'
          }
        }
      ]
    }
  }
}

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

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

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

Get-AzTemplateSpec

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

Get-AzTemplateSpec -ResourceGroupName templateSpecsRG -Name storageSpec

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

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

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

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

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

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

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

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

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

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

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

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $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. Добавляйте значения параметров либо внутрь строк, либо из файла параметров.

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

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

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

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

  • Использование файла параметров Bicep

    Чтобы создать файл параметров Bicep, необходимо указать инструкцию using . Рассмотрим пример:

    using 'using 'ts:<subscription-id>/<resource-group-name>/<template-spec-name>:<tag>'

param StorageAccountType = 'Standard_GRS'

    Дополнительные сведения см . в файле параметров Bicep.

    Передача файла параметров с помощью:

    В настоящее время невозможно развернуть спецификацию шаблона с помощью Bicepparam-файла с помощью Azure PowerShell.

  • Использование файла параметров JSON

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сведения о создании псевдонимов для спецификаций шаблонов, предназначенных для связывания модулей, см. в разделе "Псевдонимы" для модулей.

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

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