Как использовать шаблоны развертывания Azure Resource Manager (ARM) с Azure CLI

  • Статья

В этой статье объясняется, как использовать Azure CLI и шаблоны Azure Resource Manager (ARM) для развертывания ресурсов в Azure. Если вы не знакомы с концепциями развертывания решений Azure и управления ими, см. статью Общие сведения о развертывании шаблонов.

В Azure CLI версии 2.2.0 команды развертывания были изменены. Для работы примеров в этой статье требуется Azure CLI версии 2.20.0 или более поздней.

Чтобы выполнить этот пример, установите последнюю версию Azure CLI. Перед началом выполните команду az login, чтобы создать подключение к Azure.

Примеры для Azure CLI написаны для оболочки bash. Чтобы запустить этот пример в Windows PowerShell или командной строке, может потребоваться изменить элементы скрипта.

Если у вас не установлен интерфейс командной строки Azure, можно использовать Cloud Shell. Дополнительные сведения см. в статье Развертывание шаблонов ARM из Azure Cloud Shell.

Совет

Мы рекомендуем использовать Bicep, так как он предоставляет те же возможности, что и шаблоны ARM, и имеет более простой синтаксис. Подробнее см. статью Развертывание ресурсов с помощью Bicep и Azure CLI.

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

Для развертывания файла Bicep или шаблона ARM необходим доступ с правом записи для развертываемых ресурсов и доступ ко всем операциям с типом ресурсов Microsoft.Resources/deployments. Например, для развертывания виртуальной машины необходимы разрешения Microsoft.Compute/virtualMachines/write и Microsoft.Resources/deployments/*. Операция what-if имеет те же требования к разрешениям.

Список ролей и разрешений см. в статье Встроенные роли Azure.

Область развертывания

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

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

Развертывание локального шаблона

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

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

az group create --name ExampleGroup --location "Central US"

Чтобы развернуть локальный шаблон, используйте параметр --template-file в команде развертывания. В рассмотренном ниже примере также демонстрируется настройка значений параметра.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-template> \
  --parameters storageAccountType=Standard_GRS

Значением параметра --template-file должен быть файл Bicep или же файл .json или .jsonc. Расширение файла .jsonc указывает на то, что этот файл может содержать комментарии в стиле //. Система ARM принимает комментарии // в файлах .json. Для нее расширение файла не имеет значения. Дополнительные сведения о комментариях и метаданных см. в статье Общие сведения о структуре и синтаксисе шаблонов ARM.

Обработка шаблона развертывания Azure может занять несколько минут. По завершении появится сообщение, содержащее результат:

"provisioningState": "Succeeded",

Развертывание шаблона из удаленного расположения

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

Примечание.

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

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

az group create --name ExampleGroup --location "Central US"

Для развертывания внешнего шаблона используйте параметр template-uri.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

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

Для развертывания связанных шаблонов из удаленных источников с относительным путем, которые хранятся в учетной записи хранилища, используйте параметр query-string для указания маркера SAS:

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

Дополнительные сведения см. в разделе Использование относительного пути для связанных шаблонов.

Имя шаблона развертывания Azure

При развертывании шаблона ARM вы можете присвоить шаблону развертывания Azure имя. Это имя можно использовать, чтобы получить нужное развертывание из журнала развертываний. Если имя не указано, по умолчанию используется имя файла шаблона. Например, если вы развертываете шаблон azuredeploy.json и не указываете имя развертывания, развертывание будет называться azuredeploy.

Каждый раз при выполнении развертывания в журнал развертывания группы ресурсов добавляется запись с именем развертывания. Если запустить другое развертывание и присвоить ему такое же имя, то предыдущая запись будет заменена текущим развертыванием. Если требуется создать уникальные записи в журнале развертывания, присвойте каждому развертыванию уникальное имя.

Чтобы создать уникальное имя, можно добавить к нему случайное число.

deploymentName='ExampleDeployment'$RANDOM

Также можно добавить дату.

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

При выполнении параллельных развертываний в одной группе ресурсов с тем же именем развертывания завершается только последнее развертывание. Все развертывания с тем же именем, которые не были завершены, заменяются последним развертыванием. Например, если вы запускаете развертывание с именем newStorage, которое развертывает учетную запись хранения с именем storage1 и в то же время запускает другое развертывание с именем newStorage, которое развертывает учетную запись хранения с именем storage2, развертывается только одна учетная запись хранения. Созданная учетная запись хранения получает имя storage2.

Однако если вы запустите развертывание с именем newStorage, которое развертывает учетную запись хранения с именем storage1, и сразу после завершения работы запустите другое развертывание с именем newStorage, которое развертывает учетную запись хранения с именем storage2, то будут созданы две учетные записи хранения. Одна получит имя storage1, а другая — storage2. Но в журнал развертывания будет внесена только одна запись.

Если для каждого развертывания указано уникальное имя, их можно запускать параллельно без возникновения конфликтов. Например, если вы запустите развертывание с именем newStorage1, которое развертывает учетную запись хранения с именем storage1, и в то же время запустите другое развертывание с именем newStorage2, которое развертывает учетную запись хранения с именем storage2, будут созданы две учетные записи хранения и две записи в журнале развертывания.

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

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

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

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

Сначала создайте спецификацию шаблона, выбрав шаблон ARM.

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

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

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

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

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

Просмотр изменений

Перед развертыванием шаблона ARM можно просмотреть изменения, внесенные в среду. Используйте операцию what-if, чтобы убедиться в том, что необходимые изменения будут внесены. Операция what-if также служит для проверки шаблона на наличие ошибок.

Параметры

Для передачи значений параметров можно использовать встроенные параметры или файл параметров. Файл параметров может быть файлом параметров Bicep или файлом параметров JSON.

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

Чтобы передать встроенные параметры, укажите значения в parameters. Например, строки и массив передаются в шаблон из оболочки Bash следующим образом.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString='inline string' exampleArray='("value1", "value2")'

Если вы используете Azure CLI в командной строке Windows (CMD) или PowerShell, передайте массив в формате: exampleArray="['value1','value2']".

Можно также получить содержимое файла и предоставлять его в виде встроенного параметра.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

Получение значения параметра из файла полезно в тех случаях, когда есть необходимость предоставить значения конфигурации. Например, вы можете предоставить значения cloud-init для виртуальной машины Linux.

Файл ArrayContent.json имеет следующий формат:

[
  "value1",
  "value2"
]

Чтобы передать объект, например, для установки тегов, используйте JSON. Например, шаблон может содержать параметр, подобный приведенному ниже:

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

В этом случае можно передать строку JSON, чтобы задать параметр, как показано в следующем bash-скрипте:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $templateFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

Поместите строку JSON, которую необходимо передать в объект, в двойные кавычки.

Для хранения значений параметров можно использовать переменную. В Bash задайте для переменной все значения параметров и добавьте ее в команду развертывания.

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters $params

Однако если вы используете Azure CLI в командной строке Windows (CMD) или PowerShell, задайте для переменной строку JSON. Не используйте двойные кавычки: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

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

Вместо передачи параметров в качестве встроенных значений в скрипте может быть проще использовать файл параметров, .bicepparam файл или файл параметров JSON, содержащий значения параметров. Файл параметров должен быть локальным файлом. Файлы внешних параметров не поддерживаются в Azure CLI.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters 'storage.parameters.json'

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

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

С помощью Azure CLI версии 2.53.0 или более поздней версии и Bicep CLI версии 0.22.6 или более поздней можно развернуть файл Bicep, используя файл параметров Bicep. using При использовании инструкции в файле параметров Bicep параметр не требуется указывать --template-file при указании файла параметров Bicep для коммутатора--parameters. --template-file Включение параметра приводит к ошибке "Допускается только шаблон Bicep с ошибкой Bicepparam".

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

Файл параметров должен быть локальным файлом. Файлы внешних параметров не поддерживаются в Azure CLI. Дополнительные сведения о файле параметров см. в разделе "Создание файла параметров Resource Manager".

Комментарии и расширенный формат JSON

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

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters '@storage.parameters.jsonc'

Дополнительные сведения о комментариях и метаданных см. в разделе "Общие сведения о структуре и синтаксисе шаблонов ARM".

Если вы используете Azure CLI версии 2.3.0 или более ранней, можно развернуть шаблон с многострочными строками или комментариями с помощью переключателя --handle-extended-json-format. Например:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

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