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

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

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

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

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

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

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

В редких случаях может возникнуть ошибка "Учетная запись хранения с именем <storage-account-name> уже взята". Обычно это происходит, когда учетная запись хранения, созданная предыдущим выполнением того же скрипта развертывания, не была успешно удалена.

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

Для версии 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 в скрипте развертывания.

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

  Important

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

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

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

В следующем примере показан простой файл 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

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: '14.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

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

Сохраните скрипт в файле 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@2025-06-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@2025-01-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

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: '14.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/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 : 14.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

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

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

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

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

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

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

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

• Разработка скрипта развертывания в Bicep
• Получите доступ к частной виртуальной сети из скрипта развертывания Bicep
• Запуск скрипта развертывания Bicep в частном режиме через частную конечную точку
• Настройка среды разработки для сценариев развертывания в файлах Bicep