Использование сценариев развертывания в Bicep
С помощью ресурса 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свойства поддерживается только управляемое удостоверение, назначаемое пользователем. Чтобы войти с помощью другого удостоверения, используйте второй способ из списка. - Передайте учетные данные субъекта-службы в качестве безопасных переменных среды, а затем вызовите Connect-AzAccount или az login в скрипте развертывания.
Если вы используете управляемое удостоверение, субъект развертывания должен назначить встроенную роль оператора управляемого удостоверения, назначенную ресурсу управляемого удостоверения.
- Укажите управляемое удостоверение, назначаемое пользователем, в свойстве
В настоящее время встроенная роль не настроена для настройки разрешений скрипта развертывания.
Создание скриптов развертывания
В следующем примере показан простой файл Bicep с ресурсом скрипта развертывания. Сценарий принимает один строковый параметр и создает другую строку.
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
Дополнительные сведения о создании ресурсов скриптов развертывания см. в статье "Создание скриптов развертывания". Для создания скриптов для ресурса скрипта развертывания рекомендуется установить выделенную среду разработки скриптов, например экземпляр контейнера 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 ..."
Использование управляемого удостоверения
В следующем примере показано, как использовать управляемое удостоверение для взаимодействия с Azure из скрипта развертывания.
@description('The location of the resources.')
param location string = resourceGroup().location
@description('The storage account to list blobs from.')
param storageAccountData {
name: string
container: string
}
@description('The role id of Storage Blob Data Reader.')
var storageBlobDataReaderRoleId = '2a2b9908-6ea1-4ae2-8e65-a410df84e7d1'
@description('The storage account to read blobs from.')
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' existing = {
name: storageAccountData.name
}
@description('The Storage Blob Data Reader Role definition from [Built In Roles](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles).')
resource storageBlobDataReaderRoleDef 'Microsoft.Authorization/roleDefinitions@2022-05-01-preview' existing = {
scope: subscription()
name: storageBlobDataReaderRoleId
}
@description('The user identity for the deployment script.')
resource scriptIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-07-31-preview' = {
name: 'script-identity'
location: location
}
@description('Assign permission for the deployment scripts user identity access to the read blobs from the storage account.')
resource dataReaderRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
scope: storageAccount
name: guid(storageBlobDataReaderRoleDef.id, scriptIdentity.id, storageAccount.id)
properties: {
principalType: 'ServicePrincipal'
principalId: scriptIdentity.properties.principalId
roleDefinitionId: storageBlobDataReaderRoleDef.id
}
}
@description('The deployment script.')
resource script 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
name: 'script'
location: location
kind: 'AzureCLI'
identity: {
type: 'UserAssigned'
userAssignedIdentities: {
'${scriptIdentity.id}': {}
}
}
properties: {
azCliVersion: '2.59.0'
retentionInterval: 'PT1H'
arguments: '${storageAccount.properties.primaryEndpoints.blob} ${storageAccountData.container}'
scriptContent: '''
#!/bin/bash
set -e
az storage blob list --auth-mode login --blob-endpoint $1 --container-name $2
'''
}
}
Мониторинг и устранение неполадок скрипта развертывания
При развертывании ресурса скрипта развертывания требуется учетная запись хранения для хранения пользовательского сценария, результатов выполнения и stdout файла. Вы можете указать собственную учетную запись хранения. Дополнительные сведения см. в статье "Использование существующей учетной записи хранения".
Альтернатива указанию собственной учетной записи хранения.cleanupPreference OnExpiration Затем вы настраиваете retentionInterval длительность, которая позволяет достаточно времени для проверки выходных данных перед удалением учетной записи хранения. Дополнительные сведения см. в разделе "Очистка ресурсов скрипта развертывания".
Добавьте свойство в cleanupPreference предыдущий Bicep-файл и задайте значение OnExpiration. Значение по умолчанию — Always. Кроме того, установите значение rentalInterval PT1H (один час) или короче.
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
После успешного развертывания файла 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlinePS
ResourceGroupName : dsDemo
Location : centralus
SubscriptionId : aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/ee5o4rmoo6ilmazscripts
ContainerInstanceId : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
},
"outputs": {
"text": "Hello John Dole"
},
"cleanupPreference": "OnSuccess"
},
"id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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. |
Доступ к частной виртуальной сети
Скрипты развертывания можно запускать в частных сетях с некоторыми дополнительными конфигурациями. Дополнительные сведения см. в статье Access a private virtual network using service endpoint or Run Bicep deployment scriptly over a private endpoint.
Следующие шаги
В этой статье вы узнали, как использовать сценарии развертывания. Дополнительные сведения см. на следующих ресурсах: