Использование сценариев развертывания в Bicep

Статья
01/03/2024

С помощью ресурса deploymentScripts можно запускать сценарии в развертываниях Bicep и просматривать результаты выполнения. Эти скрипты можно использовать для выполнения пользовательских действий, таких как:

Добавить пользователей в каталог.
Выполнение операций плоскости данных; например, скопируйте большие двоичные объекты или заполните базу данных.
Найти и проверить ключ лицензии.
Создать самозаверяющий сертификат.
Создайте объект в идентификаторе Microsoft Entra.
Поиск блоков IP-адресов из пользовательской системы.

К преимуществам сценариев развертывания относятся следующие преимущества:

Они легко кодируют, используют и отлаживать. Сценарии развертывания можно разрабатывать в средах разработки на свой выбор. Эти сценарии можно внедрять в файлы Bicep или во внешние файлы сценариев.
Можно указать язык и платформу сценария. В настоящее время поддерживаются сценарии развертывания Azure PowerShell и Azure CLI в среде Linux.
Вы можете разрешить передачу аргументов командной строки в скрипт.
Вы можете указать выходные данные скрипта и передать их обратно в развертывание.

Ресурс скрипта развертывания доступен только в регионах, где доступно Экземпляры контейнеров Azure. Дополнительные сведения см. в статье "Доступность ресурсов" для Экземпляры контейнеров Azure в регионах Azure.

Предупреждение

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

Сведения о ценах см. в Экземпляры контейнеров ценах и служба хранилища Azure ценах. Дополнительные сведения в разделе об очистке ресурсов скриптов развертывания.

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

Если вы предпочитаете узнать о сценариях развертывания с помощью пошагового руководства, см . статью "Расширение Bicep" и шаблонов ARM с помощью скриптов развертывания.

Настройка минимальных разрешений

Для API сценариев развертывания или более поздней версии 2020-10-01 два субъекта участвуют в выполнении скрипта развертывания:

Субъект развертывания: этот субъект используется для развертывания Bicep-файла. Он создает базовые ресурсы, необходимые для запуска ресурса скрипта развертывания — учетной записи хранения и экземпляра контейнера Azure. Чтобы настроить разрешения с минимальными привилегиями, назначьте субъекту развертывания настраиваемую роль со следующими свойствами:
```
{
  "roleName": "deployment-script-minimum-privilege-for-deployment-principal",
  "description": "Configure least privilege for the deployment principal in deployment script",
  "type": "customRole",
  "IsCustom": true,
  "permissions": [
    {
      "actions": [
        "Microsoft.Storage/storageAccounts/*",
        "Microsoft.ContainerInstance/containerGroups/*",
        "Microsoft.Resources/deployments/*",
        "Microsoft.Resources/deploymentScripts/*"
      ],
    }
  ],
  "assignableScopes": [
    "[subscription().id]"
  ]
}
```
Если поставщики ресурсов служба хранилища Azure и Экземпляры контейнеров Azure не зарегистрированы, обязательно добавьте Microsoft.Storage/register/action иMicrosoft.ContainerInstance/register/action.
Субъект сценария развертывания. Этот субъект необходим, только если скрипт развертывания должен пройти проверку подлинности в Azure и вызвать Azure CLI или PowerShell. Существует два способа указать субъект скрипта развертывания.
- Укажите управляемое удостоверение, назначаемое пользователем, в свойствеidentity. (См. синтаксис ресурса скрипта развертывания.) При указании управляемого удостоверения, назначаемого пользователем, служба скриптов вызывается Connect-AzAccount -Identity перед вызовом скрипта развертывания. Управляемое удостоверение должно иметь доступ для завершения операции в скрипте. В настоящее время для identity свойства поддерживается только управляемое удостоверение, назначаемое пользователем. Чтобы войти с помощью другого удостоверения, используйте второй способ из списка.
- Передайте учетные данные субъекта-службы в качестве безопасных переменных среды, а затем вызовите Подключение-AzAccount или az login в скрипте развертывания.
Если вы используете управляемое удостоверение, субъект развертывания должен назначить встроенную роль оператора управляемого удостоверения, назначенную ресурсу управляемого удостоверения.

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

Создание скриптов развертывания

В следующем примере показан простой файл Bicep с ресурсом скрипта развертывания. Сценарий принимает один строковый параметр и создает другую строку.

CLI
PowerShell

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlineCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'echo "The argument is ${name}."; jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      Write-Host 'The argument is {0}' -f $name
      $output = 'Hello {0}' -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'PT1H'
  }
}

output result string = deploymentScript.properties.outputs.text

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

Сохраните скрипт в файле inlineScript.bicep и разверните ресурс с помощью следующего сценария:

$resourceGroupName = Read-Host -Prompt "Enter the name of the resource group to be created"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateFile "inlineScript.bicep"

Write-Host "Press [ENTER] to continue ..."

Мониторинг и устранение неполадок скрипта развертывания

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

Альтернатива указанию собственной учетной записи хранения.cleanupPreferenceOnExpiration Затем вы настраиваете retentionInterval длительность, которая позволяет достаточно времени для проверки выходных данных перед удалением учетной записи хранения. Дополнительные сведения см. в разделе "Очистка ресурсов скрипта развертывания".

Добавьте свойство в cleanupPreference предыдущий Bicep-файл и задайте значение OnExpiration. Значение по умолчанию — Always. Кроме того, установите значение rentalIntervalPT1H (один час) или короче.

CLI
PowerShell

param name string = 'John Dole'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlineCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'echo "The argument is ${name}."; jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    cleanupPreference: 'OnExpiration'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

param name string = '\\"John Dole\\"'
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      Write-Output "The argument is {0}." -f $name
      $output = "Hello {0}." -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    cleanupPreference: 'OnExpiration'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

После успешного развертывания файла Bicep используйте портал Azure, Azure CLI, Azure PowerShell или REST API для проверка результатов.

Портал Azure

После развертывания ресурса скрипта развертывания он будет отображаться в группе ресурсов на портале Azure. На странице обзора перечислены два вспомогательных ресурса в дополнение к ресурсу скрипта развертывания. Вспомогательные ресурсы будут удалены после истечения срока хранения.

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

Снимок экрана: группа ресурсов скрипта развертывания.

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

Снимок экрана: сведения о ресурсе скрипта развертывания.

Выберите выходные данные для отображения выходных данных скрипта.

Снимок экрана: выходные данные скрипта развертывания.

Вернитесь в группу ресурсов, выберите учетную запись хранения, выберите общие папки и выберите общую папку с azscripts , добавленной к имени общей папки. В списке отображаются две папки: azscriptinput и azscriptoutput. В выходной папке содержится файл executionresult.json и выходной файл скрипта. Файл executionresult.json содержит сообщение об ошибке выполнения скрипта. Выходной файл создается только при успешном запуске скрипта.

Снимок экрана: содержимое выходной папки скрипта развертывания.

Входная папка содержит файл системного скрипта и файл скрипта развертывания пользователя. Вы можете заменить файл скрипта развертывания пользователей измененным и повторно запустить скрипт развертывания из экземпляра контейнера Azure.

Azure CLI

С помощью Azure CLI можно управлять скриптами развертывания в подписке или группе ресурсов область:

az deployment-scripts delete: удаление скрипта развертывания.
az deployment-scripts list: вывод списка всех скриптов развертывания.
az deployment-scripts show: получение скрипта развертывания.
az deployment-scripts show-log: отображение журналов скриптов развертывания.

Выходные данные команды списка похожи на этот пример:

{
  "arguments": "John Dole",
  "azCliVersion": "2.52.0",
  "cleanupPreference": "OnExpiration",
  "containerSettings": {
    "containerGroupName": null
  },
  "environmentVariables": null,
  "forceUpdateTag": null,
  "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
  "identity": null,
  "kind": "AzureCLI",
  "location": "centralus",
  "name": "inlineCLI",
  "outputs": {
    "text": "Hello John Dole"
  },
  "primaryScriptUri": null,
  "provisioningState": "Succeeded",
  "resourceGroup": "dsDemo",
  "retentionInterval": "1:00:00",
  "scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
  "status": {
    "containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
    "endTime": "2023-12-11T20:20:12.149468+00:00",
    "error": null,
    "expirationTime": "2023-12-11T21:20:12.149468+00:00",
    "startTime": "2023-12-11T20:18:26.674492+00:00",
    "storageAccountId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
  },
  "storageAccountSettings": null,
  "supportingScriptUris": null,
  "systemData": {
    "createdAt": "2023-12-11T19:45:32.239063+00:00",
    "createdBy": "johndole@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
    "lastModifiedBy": "johndole@contoso.com",
    "lastModifiedByType": "User"
  },
  "tags": null,
  "timeout": "1 day, 0:00:00",
  "type": "Microsoft.Resources/deploymentScripts"
}

Azure PowerShell

Azure PowerShell можно использовать для управления сценариями развертывания в подписке или группе ресурсов область:

Get-AzDeploymentScript: получение или перечисление скриптов развертывания.
Get-AzDeploymentScriptLog: получение журнала выполнения скрипта развертывания.
Remove-AzDeploymentScript: удалите скрипт развертывания и связанные с ней ресурсы.
Save-AzDeploymentScriptLog: сохраните журнал выполнения скрипта развертывания на диск.

Выходные Get-AzDeploymentScript данные похожи на этот пример:

Name                : inlinePS
Id                  : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlinePS
ResourceGroupName   : dsDemo
Location            : centralus
SubscriptionId      : 01234567-89AB-CDEF-0123-456789ABCDEF
ProvisioningState   : Succeeded
Identity            :
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 10.0
StartTime           : 12/11/2023 9:45:50 PM
EndTime             : 12/11/2023 9:46:59 PM
ExpirationDate      : 12/11/2023 10:46:59 PM
CleanupPreference   : OnExpiration
StorageAccountId    : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/ee5o4rmoo6ilmazscripts
ContainerInstanceId : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/ee5o4rmoo6ilmazscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole.

RetentionInterval   : PT1H
Timeout             : P1D

REST API

С помощью REST API можно получить сведения о ресурсе скрипта развертывания на уровне группы ресурсов и уровне подписки:

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>?api-version=2020-10-01

/subscriptions/<SubscriptionID>/providers/microsoft.resources/deploymentScripts?api-version=2020-10-01

В следующем примере используется ARMClient. ARMClient не является поддерживаемым средством Майкрософт.

armclient login
armclient get /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

Выходные данные похожи на этот пример:

{
  "kind": "AzureCLI",
  "identity": null,
  "location": "centralus",
  "systemData": {
    "createdAt": "2023-12-11T19:45:32.239063+00:00",
    "createdBy": "johndole@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
    "lastModifiedBy": "johndole@contoso.com",
    "lastModifiedByType": "User"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "azCliVersion": "2.52.0",
    "scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "arguments": "John Dole",
    "retentionInterval": "1:00:00",
    "timeout": "1 day, 0:00:00",
    "containerSettings": {
      "containerGroupName": null
    },
    "status": {
      "containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
      "endTime": "2023-12-11T20:20:12.149468+00:00",
      "error": null,
      "expirationTime": "2023-12-11T21:20:12.149468+00:00",
      "startTime": "2023-12-11T20:18:26.674492+00:00",
      "storageAccountId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "inlineCLI",
}

Приведенный ниже REST API возвращает журнал.

/subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/microsoft.resources/deploymentScripts/<DeploymentScriptResourceName>/logs?api-version=2020-10-01

Он работает только перед удалением ресурсов скрипта развертывания.

Коды ошибок скрипта развертывания

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

Код ошибки	Description
`DeploymentScriptInvalidOperation`	Определение ресурса сценария развертывания в файле Bicep содержит недопустимые имена свойств.
`DeploymentScriptResourceConflict`	Невозможно удалить ресурс скрипта развертывания, если он находится в нетерминальном состоянии, и выполнение не превысило один час. Кроме того, вы не можете повторно запустить один и тот же скрипт развертывания с одинаковым идентификатором ресурса (одной подпиской, именем группы ресурсов и именем ресурса), но с другим текстом скрипта одновременно.
`DeploymentScriptOperationFailed`	Внутренняя ошибка при выполнении операции скрипта развертывания. Обращение в службу поддержки Майкрософт.
`DeploymentScriptStorageAccountAccessKeyNotSpecified`	Ключ доступа не указан для существующей учетной записи хранения.
`DeploymentScriptContainerGroupContainsInvalidContainers`	Группа контейнеров, созданная службой скриптов развертывания, была изменена внешняя, и добавлены недопустимые контейнеры.
`DeploymentScriptContainerGroupInNonterminalState`	Два или несколько ресурсов скриптов развертывания используют одинаковое имя экземпляра контейнера Azure в одной группе ресурсов, и один из них еще не завершил выполнение.
`DeploymentScriptExistingStorageNotInSameSubscriptionAsDeploymentScript`	Существующее хранилище, предоставленное в развертывании, не найдено в подписке, в которой развертывается скрипт.
`DeploymentScriptStorageAccountInvalidKind`	Существующая учетная запись `BlobBlobStorage` хранения типа не `BlobStorage` поддерживает общие папки и не может использоваться.
`DeploymentScriptStorageAccountInvalidKindAndSku`	Существующая учетная запись хранения не поддерживает общие папки. Список поддерживаемых типов учетных записей хранения см. в разделе "Использование существующей учетной записи хранения".
`DeploymentScriptStorageAccountNotFound`	Учетная запись хранения не существует, или внешний процесс или средство его удаления.
`DeploymentScriptStorageAccountWithServiceEndpointEnabled`	Указанная учетная запись хранения имеет конечную точку службы. Учетная запись хранения с конечной точкой службы не поддерживается.
`DeploymentScriptStorageAccountInvalidAccessKey`	Недопустимый ключ доступа был указан для существующей учетной записи хранения.
`DeploymentScriptStorageAccountInvalidAccessKeyFormat`	Ключ учетной записи хранения имеет недопустимый формат. См. статью Управление ключами доступа к учетной записи хранения.
`DeploymentScriptExceededMaxAllowedTime`	Время выполнения скрипта развертывания превысило время ожидания, указанное в определении ресурса скрипта развертывания.
`DeploymentScriptInvalidOutputs`	Выходные данные скрипта развертывания являются недопустимым объектом JSON.
`DeploymentScriptContainerInstancesServiceLoginFailure`	Управляемое удостоверение, назначаемое пользователем, не может войти после 10 попыток с интервалами в одну минуту.
`DeploymentScriptContainerGroupNotFound`	Внешнее средство или процесс удалили группу контейнеров, созданную службой скриптов развертывания.
`DeploymentScriptDownloadFailure`	Сбой скачивания вспомогательного скрипта. См . раздел "Использование вспомогательных сценариев".
`DeploymentScriptError`	Пользовательский скрипт вызвал ошибку.
`DeploymentScriptBootstrapScriptExecutionFailed`	Скрипт начальной загрузки вызвал ошибку. Скрипт начальной загрузки — это системный скрипт, который управляет выполнением скрипта развертывания.
`DeploymentScriptExecutionFailed`	Во время выполнения скрипта развертывания произошла неизвестная ошибка.
`DeploymentScriptContainerInstancesServiceUnavailable`	Во время создания экземпляра контейнера служба Экземпляры контейнеров Azure вызвала ошибку "служба недоступна".
`DeploymentScriptContainerGroupInNonterminalState`	Во время создания экземпляра контейнера другой сценарий развертывания использовал то же имя экземпляра контейнера в том же область (та же подписка, имя группы ресурсов и имя ресурса).
`DeploymentScriptContainerGroupNameInvalid`	Указанное имя экземпляра контейнера не соответствует требованиям Экземпляры контейнеров Azure. См. раздел Устранение распространенных неполадок в экземплярах контейнеров Azure.

Доступ к частной виртуальной сети

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

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

В этой статье вы узнали, как использовать сценарии развертывания. Дополнительные сведения см. на следующих ресурсах: