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

  • 3 мин

Рассмотрим, как создать и опубликовать спецификацию шаблона.

Создать шаблон

Чтобы создать шаблон для использования в качестве спецификации шаблона, необходимо написать шаблон Azure Resource Manager (шаблон ARM), как обычно. Можно включить параметры, переменные, ресурсы и выходные данные.

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

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "environmentType": {
      "type": "string",
      "allowedValues": [
        "Production",
        "NonProduction"
      ],
      "metadata": {
        "description": "The type of the environment to deploy. This will determine the SKUs and cost of the resources."
      }
    },
    "key": {
      "type": "secureString",
      "metadata": {
        "description": "The secret key to use."
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "The Azure region into which the resources should be deployed."
      }
    },
    "sqlServerCount": {
      "type": "int",
      "maxValue": 5,
      "metadata": {
        "description": "The number of Azure SQL logical servers to create."
      }
    }
  },
  "resources": []
}

В этом примере параметры шаблона используют allowedValuesmaxValueсвойства и description свойства, чтобы определить, какие параметры предназначены и какие эффекты настройки их значений. В шаблон также включен тип secureString, который указывает, что параметр key содержит данные секрета.

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

@description('The type of the environment to deploy. This will determine the SKUs and cost of the resources.')
@allowed([
  'Production'
  'NonProduction'
])
param environmentType string

@secure()
@description('The secret key to use.')
param key string

@description('The Azure region into which the resources should be deployed.')
param location string

@description('The number of Azure SQL logical servers to create.')
@maxValue(5)
param sqlServerCount int

В этом примере параметры шаблона используют @allowedатрибуты , @maxValueа @description также декораторы, чтобы определить, какие параметры предназначены и какие эффекты настройки их значений. Шаблон также включает декоратор secure, указывающий, что параметр key содержит данные секрета.

Когда кто-то развертывает спецификацию шаблона с помощью портала Azure, на портале происходит следующее.

  • Отображается имя и описание параметра.
  • Скрывается текст для защищенных параметров.
  • Обеспечивает соблюдение допустимых значений, ограничений длины и определяемых значений.

На этом снимке экрана показана запись значений параметров.

Screenshot that shows the Azure portal interface for entering parameter values for a template spec deployment.

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

Публикация спецификации шаблона в Azure

После написания шаблона вместо отправки шаблона в Azure для развертывания вы публикуете спецификацию шаблона.

Важно!

При публикации файла Bicep как спецификации шаблона код Bicep преобразуется в шаблон JSON. В процессе преобразования кода Bicep в JSON часть данных из файла Bicep удаляется. Например, комментарии, символьные имена ресурсов и порядок, в котором определяются ресурсы, могут отсутствовать или отличаться в файле JSON. Это означает, что не получится легко опубликовать файл Bicep как спецификацию шаблона, а затем вернуть исходный файл Bicep (эта возможность называется многократным преобразованием). Рекомендуется хранить копию исходного кода Bicep в репозитории кода, например Git, особенно при работе со спецификациями шаблонов.

Чтобы создать спецификацию шаблона, используйте командлет New-AzTemplateSpec. В следующем примере показано, как создать спецификацию шаблона для шаблона учетной записи хранения.

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile main.bicep

New-AzTemplateSpec `
  -Name StorageWithoutSAS `
  -Location westus `
  -DisplayName 'Storage account with SAS disabled' `
  -Description 'This template spec creates a storage account, which is preconfigured to disable SAS authentication.' `
  -Version '1.0' `
  -TemplateFile azuredeploy.json

Рассмотрим каждый из этих параметров.

  • -Name — имя ресурса спецификации шаблона, которое не может содержать пробелы.
  • -Location — расположение, в котором должны быть созданы метаданные спецификации шаблона. Спецификацию шаблона можно развернуть в любом регионе.
  • -DisplayName — понятное для человека имя, которое может содержать пробелы.
  • -Description — понятное для человека описание, которое можно использовать, чтобы предоставить подробную информацию о содержимом спецификации шаблона и о том, когда его можно использовать.
  • -Version — это версия спецификации шаблона. Вы узнаете о версиях далее в этом модуле.
  • -TemplateFile — путь к шаблону ARM, для которого требуется создать спецификацию шаблона.

Чтобы создать спецификацию шаблона, используйте командлет az ts create. В следующем примере показано, как создать спецификацию шаблона для шаблона учетной записи хранения.

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file main.bicep

az ts create \
  --name StorageWithoutSAS \
  --location westus \
  --display-name "Storage account with SAS disabled" \
  --description "This template spec creates a storage account, which is preconfigured to disable SAS authentication." \
  --version 1.0 \
  --template-file azuredeploy.json

Рассмотрим каждый из этих аргументов.

  • --name — имя ресурса спецификации шаблона, которое не может содержать пробелы.
  • --location — расположение, в котором должны быть созданы метаданные спецификации шаблона. Спецификацию шаблона можно развернуть в любом регионе.
  • --display-name — понятное для человека имя, которое может содержать пробелы.
  • --description — понятное для человека описание, которое можно использовать, чтобы предоставить подробную информацию о содержимом спецификации шаблона и о том, когда его можно использовать.
  • --version — это версия спецификации шаблона. Вы узнаете о версиях далее в этом модуле.
  • --template-file — путь к шаблону ARM, для которого требуется создать спецификацию шаблона.

Совет

Также можно определить спецификацию шаблона в шаблоне ARM. Поскольку спецификация шаблона сама по себе является ресурсом Azure, можно развернуть шаблон, определяющий ресурс с типом Microsoft.Deployments/templateSpecs.