Разработка скрипта развертывания в Bicep

В этой статье приведены примеры, показывающие, как разработать скрипт развертывания в Bicep.

Ресурсы скрипта развертывания могут иметь длительность развертывания. Для эффективной разработки и тестирования этих скриптов рекомендуется установить выделенную среду разработки, например экземпляр контейнера Azure (ACI) или экземпляр Docker. Дополнительные сведения см. в разделе "Создание среды разработки".

Синтаксис

Ниже приведён файл Bicep, в котором представлен пример ресурса скрипта развертывания. Дополнительные сведения см. в последней схеме скрипта развертывания.

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzureCLI'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azCliVersion: '2.52.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

resource <symbolic-name> 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: '<resource-name>'
  location: resourceGroup().location
  tags: {}
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '<user-assigned-identity-id>': {}
    }
  }
  kind: 'AzurePowerShell'
  properties: {
    storageAccountSettings: {
      storageAccountName: '<storage-account-name>'
      storageAccountKey: '<storage-account-key>'
    }
    containerSettings: {
      containerGroupName: '<container-group-name>'
      subnetIds: [
        {
          id: '<subnet-id>'
        }
      ]
    }
    environmentVariables: []
    azPowerShellVersion: '10.0'
    arguments: '<script-arguments>'
    scriptContent: '''<azure-cli-or-azure-powershell-script>''' // or primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/inlineScript.ps1'
    supportingScriptUris: []
    timeout: 'P1D'
    cleanupPreference: 'OnSuccess'
    retentionInterval: 'P1D'
    forceUpdateTag: '1'
  }
}

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

• tags: укажите теги скрипта развертывания. Если служба скриптов развертывания создает два вспомогательных ресурса (учетную запись хранения и экземпляр контейнера), теги передаются обоим ресурсам. Теги можно использовать для идентификации ресурсов. Еще один способ определить эти вспомогательные ресурсы — по их суффиксам, которые содержат azscripts. Дополнительные сведения см. в статье "Мониторинг и устранение неполадок сценариев развертывания".

• identity: для версии 2020-10-01 API сценариев развертывания или более поздней, назначаемое пользователем управляемое удостоверение является необязательным, если вам не нужно выполнять какие-либо действия , связанные с Azure, в скрипте или выполняете скрипт развертывания в частной сети. Версия API 2019-10-01-preview требует управляемого идентификатора, так как служба сценариев развертывания использует его для выполнения сценариев.

  При указании свойства identity служба скриптов вызывает Connect-AzAccount -Identity перед вызовом пользовательского скрипта. В настоящее время поддерживается только управляемая идентификация, назначенная пользователем. Чтобы войти в сценарии развертывания под другой учётной записью, можно вызвать Connect-AzAccount. Дополнительные сведения см. в разделе "Настройка минимальных разрешений".

• kind: Укажите тип скрипта: AzurePowerShell или AzureCLI. Кроме того, помимо kind, необходимо указать свойство azPowerShellVersion или azCliVersion.

• storageAccountSettings: укажите параметры для использования имеющейся учетной записи хранения. Если storageAccountName не указано, учетная запись хранения создается автоматически. Дополнительные сведения см. в статье "Использование существующей учетной записи хранения".

• containerSettings: Настройте имя экземпляра контейнера Azure. Сведения о настройке имени группы контейнера см. далее в этой статье в разделе «Настройка экземпляра контейнера». Сведения о настройке subnetIds для запуска скрипта развертывания в частной сети см. в статье Доступ к частной виртуальной сети.

• environmentVariables: Укажите переменные среды, которые нужно передать скрипту.

• azPowerShellVersion / azCliVersion: укажите используемую версию модуля.

  • CLI
  • PowerShell

  См. список поддерживаемые версии Azure CLI.

  Внимание

  Скрипт развертывания использует доступные образы CLI из реестра артефактов Microsoft. Обычно требуется около одного месяца для сертификации образа ИНТЕРФЕЙСА командной строки для сценария развертывания. Не используйте версии CLI, выпущенные за последние 30 дней. Чтобы найти даты выпуска образов, ознакомьтесь с заметками о выпуске Azure CLI. Если вы используете неподдерживаемую версию, в сообщении об ошибке выводится список поддерживаемых версий.

• arguments: укажите значения параметров. Значения разделяются пробелами.

  Скрипт развертывания разбивает аргументы на массив строк путем вызова системного вызова CommandLineToArgvW . Этот шаг необходим, так как аргументы передаются в Экземпляры контейнеров Azure как свойство command, а свойство command представляет собой массив строк.

  Если аргументы содержат экранированные символы, экранируйте эти символы дважды. Например, в предыдущем примере синтаксиса Bicep аргумент имеет значение -name \"John Dole\". Escape-строка имеет значение -name \\"John Dole\\".

  Чтобы передать параметр Bicep типа object в качестве аргумента, преобразуйте объект в строку с помощью функции string(), а затем используйте функцию replace(), чтобы заменить все кавычки () двойными экранированными кавычками (). Например:

  replace(string(parameters('tables')), '"', '\\"')
  

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

• scriptContent: укажите содержимое сценария. Это может быть встроенный скрипт или внешний файл скрипта, импортированный с помощью функции loadTextContent . Дополнительные сведения см. в разделе Встроенные и внешние файлы далее в этой статье. Чтобы запустить внешний сценарий, используйте primaryScriptUri.

• primaryScriptUri: укажите общедоступный URL-адрес основного скрипта развертывания с поддерживаемыми расширениями файлов. Дополнительные сведения см. в разделе "Использование внешних скриптов " далее в этой статье.

• supportingScriptUris: укажите массив общедоступных URL-адресов для вспомогательных файлов, которые вызываются посредством scriptContent либо primaryScriptUri. Дополнительные сведения см. в разделе Встроенные и внешние файлы далее в этой статье.

• timeout: укажите максимально допустимое время выполнения скрипта в формате ISO 8601. Значение по умолчанию — P1D.

• forceUpdateTag: изменение этого значения при последующих развертываниях файла Bicep приводит к повторному запуску скрипта развертывания. При использовании newGuid() или utcNow() функции его можно использовать только в значении по умолчанию для параметра. Дополнительные сведения см. далее в этой статье: Запуск скрипта несколько раз.

• cleanupPreference. Укажите, следует ли очищать два вспомогательных ресурса развертывания (учетную запись хранения и экземпляр контейнера), когда выполнение скрипта переходит в конечное состояние. Значение по умолчанию — Always, которое предусматривает удаление вспомогательных ресурсов независимо от конечного состояния (Succeeded, Failed или Canceled). Дополнительные сведения см. в статье "Очистка ресурсов скрипта развертывания" далее в этой статье.

• retentionInterval: укажите интервал времени, в течение которого служба сохраняет ресурс скрипта развертывания после того, как выполнение скрипта развертывания достигает конечного состояния. Ресурс скрипта развертывания удаляется при истечении этого срока действия. Длительность основывается на методике ISO 8601. Интервал хранения составляет от 1 часа (PT1H) до 26 часов (PT26H). Это свойство используется, если cleanupPreference задано значение OnExpiration. Дополнительные сведения см. в статье "Очистка ресурсов скрипта развертывания" далее в этой статье.

Другие примеры

• Пример 1. Создание хранилища ключей и использование скрипта развертывания для назначения сертификата хранилищу ключей.
• Пример 2. Создание группы ресурсов на уровне подписки, создание хранилища ключей в группе ресурсов и использование скрипта развертывания для назначения сертификата хранилищу ключей.
• Пример 3. Создание управляемого удостоверения, назначаемого пользователем, назначьте удостоверению роль участника на уровне группы ресурсов, создайте хранилище ключей, а затем используйте скрипт развертывания для назначения сертификата хранилищу ключей.
• Пример 4. Вручную создайте управляемое удостоверение, назначаемое пользователем, и назначьте ему разрешение на использование API Microsoft Graph для создания приложений Microsoft Entra. В файле Bicep используйте скрипт развертывания для создания приложения Microsoft Entra и субъекта-службы, а также для вывода идентификаторов объектов и идентификатора клиента.

Встроенный или внешний файл

Скрипт развертывания может находиться в файле Bicep, или его можно хранить отдельно, в виде отдельного файла.

Использование встроенного скрипта

В следующем файле 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: 'set -e; output="Hello $1"; echo $output'
    retentionInterval: 'P1D'
  }
}

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)
      $ErrorActionPreference = 'Stop'
      $output = "Hello {0}" -f $name
      Write-Output "Output is: '$output'."
    '''
    retentionInterval: 'P1D'
  }
}

Загрузка файла скрипта

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

output="Hello $1"
echo $output

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: loadTextContent('./scripts/hello.sh')
    retentionInterval: 'P1D'
  }
}

param([string] $name)
$output = "Hello {0}" -f $name
Write-Output "Output is: '$output'."

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'loadTextContentPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: loadTextContent('./scripts/hello.ps1')
    retentionInterval: 'P1D'
  }
}

Использование внешних сценариев

Вы можете использовать внешние файлы скриптов вместо встроенных скриптов. Поддерживаются только основные скрипты PowerShell с расширением .ps1. Для сценариев CLI первичные скрипты могут содержать любые допустимые расширения скриптов Bash или вообще не имеют расширения. Чтобы использовать внешние файлы скриптов, замените scriptContent на primaryScriptUri.

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.sh'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'externalScriptPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    primaryScriptUri: 'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/main/samples/deployment-script/hello.ps1'
    arguments: '-name ${name}'
    retentionInterval: 'P1D'
  }
}

Внешние файлы сценария должны быть доступны. Чтобы защитить файлы скриптов, хранящиеся в учетных записях хранения Azure, создайте маркер подписанного URL-адреса (SAS) и включите его в URI шаблона. Задайте срок действия, чтобы разрешить достаточно времени для завершения развертывания. Дополнительные сведения см. в статье "Развертывание частного шаблона ARM с помощью маркера SAS".

Вы несете ответственность за обеспечение целостности скрипта, ссылающегося на скрипт развертывания ( primaryScriptUri или supportingScriptUris). Ссылайтесь только на те скрипты, которым вы доверяете.

Использование вспомогательных сценариев

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

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'output="Hello $1"; echo $output; ./hello.sh "$1"'
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.sh'
    ]
    retentionInterval: 'P1D'
  }
}

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'supportingScriptPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $output = "Hello {0}" -f $name
      Write-Output "Output is: '$output'."
      ./hello.ps1 -name $name
    '''
    supportingScriptUris: [
      'https://raw.githubusercontent.com/Azure/azure-docs-bicep-samples/master/samples/deployment-script/hello.ps1'
    ]
    retentionInterval: 'P1D'
  }
}

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

Вспомогательные файлы копируются в azscripts/azscriptinput во время выполнения. Используйте относительный путь для ссылки на вспомогательные файлы из встроенных скриптов и основных файлов скриптов.

Доступ к ресурсам Azure

Чтобы получить доступ к ресурсам Azure, необходимо настроить identity элемент. В следующем файле Bicep показано, как получить список хранилищ ключей Azure. Кроме того, необходимо предоставить удостоверение управления назначениями пользователей для доступа к хранилищу ключей.

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvCLI'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'result=$(az keyvault list); echo $result | jq -c \'{Result: map({id: .id})}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

param identity string
param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listKvPS'
  location: location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${identity}': {}
    }
  }
  properties: {
    azPowerShellVersion: '10.0'
    scriptContent: '''
      $kvs=Get-AzKeyVault

      $output = @()
      foreach($kv in $kvs){
        $newKv = @{
          id = $kv.resourceId
        }
        $output = $output + $newKv
      }
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs["kvs"] = $output
    '''
    retentionInterval: 'P1D'
  }
}

output result object = deploymentScript.properties.outputs

Работа с выходными данными

Подход к обработке выходных данных зависит от типа скрипта, который вы используете с помощью Azure CLI или Azure PowerShell.

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

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

output text string = deploymentScript.properties.outputs.text

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

resource deploymentScript1 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputPS1'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      $output = 'Hello {0}' -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'P1D'
  }
}

resource deploymentScript2 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'outputPS2'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    arguments: '-textToEcho \\"${deploymentScript1.properties.outputs.text}\\"'
    scriptContent: '''
      param([string] $textToEcho)
      Write-Output $textToEcho
    '''
    retentionInterval: 'P1D'
  }
}

Использование переменных среды

Передача защищенных строк в скрипт развертывания

Переменные среды (EnvironmentVariable) можно задать в экземплярах контейнеров, чтобы обеспечить динамическую конфигурацию приложения или скрипта, запущенного контейнером. Сценарий развертывания обрабатывает обычные и защищенные переменные среды так же, как в Экземпляры контейнеров Azure. Узнайте больше об определении переменных среды для экземпляров контейнеров.

Максимальный допустимый размер переменных среды составляет 64 КБ.

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: 'echo "Username is :$Username"; echo "Password is: $Password"'
    retentionInterval: 'P1D'
  }
}

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'passEnvVariablesPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    environmentVariables: [
      {
        name: 'UserName'
        value: 'jdole'
      }
      {
        name: 'Password'
        secureValue: 'jDolePassword'
      }
    ]
    scriptContent: '''
      Write-output "Username is :$Username"
      Write-output "Password is: $Password"
    '''
    retentionInterval: 'P1D'
  }
}

Системные переменные среды

В следующей таблице перечислены системные переменные среды:

Пример использования AZ_SCRIPTS_OUTPUT_PATHсм. в статье "Работа с выходными данными " выше в этой статье.

Чтобы получить доступ к переменным среды, используйте следующий код.

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    scriptContent: 'echo "AZ_SCRIPTS_AZURE_ENVIRONMENT is : $AZ_SCRIPTS_AZURE_ENVIRONMENT",echo "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : $AZ_SCRIPTS_CLEANUP_PREFERENCE",echo "AZ_SCRIPTS_OUTPUT_PATH	is : $AZ_SCRIPTS_OUTPUT_PATH",echo "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_INPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : $AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY",echo "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : $AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME",echo "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : $AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME",echo "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : $AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME",echo "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : $AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME",echo "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : $AZ_SCRIPTS_USER_ASSIGNED_IDENTITY"'
    retentionInterval: 'P1D'
  }
}

param location string = resourceGroup().location

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'listEnvVariablesPS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '10.0'
    scriptContent: '''
      Write-Output "AZ_SCRIPTS_AZURE_ENVIRONMENT is : ${Env:AZ_SCRIPTS_AZURE_ENVIRONMENT}"
      Write-Output "AZ_SCRIPTS_CLEANUP_PREFERENCE	is : ${Env:AZ_SCRIPTS_CLEANUP_PREFERENCE}"
      Write-Output "AZ_SCRIPTS_OUTPUT_PATH	is : ${Env:AZ_SCRIPTS_OUTPUT_PATH}"
      Write-Output "AZ_SCRIPTS_PATH_INPUT_DIRECTORY is : ${Env:AZ_SCRIPTS_PATH_INPUT_DIRECTORY}"
      Write-Output "AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY is : ${Env:AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY}"
      Write-Output "AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME is : ${Env:AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME	is : ${Env:AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME}"
      Write-Output "AZ_SCRIPTS_USER_ASSIGNED_IDENTITY	is : ${Env:AZ_SCRIPTS_USER_ASSIGNED_IDENTITY}"
    '''
    retentionInterval: 'P1D'
  }
}

Использование имеющейся учетной записи хранения

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

Ниже приведены требования к использованию существующей учетной записи хранения:

• В следующей таблице перечислены поддерживаемые типы учетных записей. Столбец уровней относится к значению параметра -SkuName или --sku. Столбец поддерживаемых типов ссылается на -Kind или --kind параметр.

  Уровень	Поддерживаемый тип
  Premium_LRS	FileStorage
  Premium_ZRS	FileStorage
  Standard_GRS	Storage, StorageV2
  Standard_GZRS	StorageV2
  Standard_LRS	Storage, StorageV2
  Standard_RAGRS	Storage, StorageV2
  Standard_RAGZRS	StorageV2
  Standard_ZRS	StorageV2

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

• Правила брандмауэра для учетных записей хранения пока не поддерживаются. Дополнительные сведения см. в статье Настройка брандмауэров службы хранилища Azure и виртуальных сетей.

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

• Свойство allowSharedKeyAccess учетной записи хранения должно иметь значение true. Единственный способ подключить учетную запись хранения в Azure Container Instance (ACI) — с помощью ключа доступа.

Чтобы указать существующую учетную запись хранения, добавьте следующий код Bicep в элемент свойства Microsoft.Resources/deploymentScripts:

param storageAccountName string = 'myStorageAccount'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    storageAccountSettings: {
      storageAccountName: storageAccountName
      storageAccountKey: listKeys(resourceId('Microsoft.Storage/storageAccounts', storageAccountName), '2023-01-01').keys[0].value
    }
  }
}

Полный Microsoft.Resources/deploymentScripts пример определения см. в разделе Синтаксис выше в этой статье.

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

Настройка экземпляра контейнера

Для скрипта развертывания требуется новый экземпляр контейнера Azure. Невозможно указать существующий экземпляр контейнера. Однако можно настроить имя группы контейнера с помощью containerGroupName. Если имя группы не указано, он создается автоматически. Для создания этого экземпляра контейнера требуются дополнительные конфигурации. Дополнительные сведения см. в разделе "Настройка минимальных разрешений".

Можно также указать subnetId значения для запуска скрипта развертывания в частной сети. Дополнительные сведения см. в статье "Доступ к частной виртуальной сети".

param containerGroupName string = 'mycustomaci'
param subnetId string = '/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myVnet/subnets/mySubnet'

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  ...
  properties: {
    ...
    containerSettings: {
      containerGroupName: containerGroupName
      subnetIds: [
        {
          id: subnetId
        }
      ]
    }
  }
}

Выполнение скрипта более одного раза

Выполнение сценария развертывания является идемпотентной операцией. Если нет изменений в каких-либо deploymentScripts свойствах ресурса, включая встроенный скрипт, скрипт не запускается при повторном развертывании файла Bicep.

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

• Измените имя ресурсаdeploymentScripts. Например, используйте функцию UTCNow в качестве имени ресурса или в составе имени ресурса. Функцию utcNow можно использовать только в значении параметра по умолчанию.

  При изменении имени ресурса создается новый ресурс deploymentScripts. Целесообразно сохранить журнал выполнения сценария.

• Укажите другое значение в свойстве forceUpdateTag. Например, используйте значение utcNow.

Пишите скрипты развертывания с учетом идемпотентности, чтобы случайный повторный запуск не приводил к изменению состояния системы. Например, при создании ресурса Azure с помощью скрипта развертывания проверьте его отсутствие перед созданием, чтобы убедиться, что скрипт успешно выполнен или избегает избыточного создания ресурсов.

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

Скрипт развертывания может использовать Microsoft Graph для создания и работы с объектами в идентификаторе Microsoft Entra.

Команды

При использовании сценариев развертывания Azure CLI можно использовать команды в az ad группе команд для работы с приложениями, субъектами-службами, группами и пользователями. Вы также можете напрямую вызывать API Microsoft Graph с помощью az rest команды.

Когда вы используете скрипты развертывания Azure PowerShell, вы можете использовать командлет Invoke-RestMethod для прямого вызова API Microsoft Graph.

Разрешения

Учетная запись, которую использует скрипт развертывания, должна иметь разрешение на работу с API Microsoft Graph с соответствующими правами для операций, которые он выполняет. Необходимо авторизовать эту идентичность вне файла Bicep, например, предварительно создав управляемую идентичность, назначаемую пользователем, и назначив ей роль приложения для Microsoft Graph. Дополнительные сведения см. в этом примере краткого руководства.

Очистка ресурсов сценария развертывания

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

• cleanupPreference: Укажите параметр очистки для двух вспомогательных ресурсов, когда выполнение скрипта переходит в терминальное состояние. Поддерживаются такие значения:

  • Always: Удалите два вспомогательных ресурса после перехода выполнения скрипта в конечное состояние. При использовании существующей учетной записи хранения служба скриптов удаляет общую папку, созданную службой. deploymentScripts Так как ресурс по-прежнему может присутствовать после очистки вспомогательных ресурсов, служба скриптов сохраняет результаты выполнения скрипта (например, stdout), выходные данные и возвращаемое значение перед удалением ресурсов.

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

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

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

  Экземпляр контейнера и учетная запись хранения удаляются в соответствии со значением cleanupPreference . Однако, если в скрипте происходит сбой и для cleanupPreference не задано значение Always, процесс развертывания автоматически оставляет контейнер запущенным на один час или до тех пор, пока контейнер не будет очищен. Вы можете использовать время для устранения неполадок скрипта.

  Чтобы контейнер запускался после успешного развертывания, добавьте в скрипт шаг "спящий режим". Например, добавьте Start-Sleep в конце скрипта. Если вы не добавите этап ожидания, контейнер перейдет в конечное состояние, и к нему нельзя будет получить доступ, даже если вы его еще не удалили.

• retentionInterval: укажите интервал времени, в течение которого deploymentScript ресурс будет сохранен до истечения срока действия и удаления.

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

Из этой статьи вы узнали, как создать ресурсы скрипта развертывания. Подробнее: