Использование сценариев развертывания в шаблонах ARM

Узнайте, как использовать сценарии развертывания в шаблонах Azure Resource Manager (ARM). deploymentScripts С помощью ресурса пользователи могут выполнять скрипты в развертываниях ARM и просматривать результаты выполнения.

Эти сценарии можно использовать для выполнения настраиваемых действий, в том числе с их помощью можно:

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

Преимущества сценария развертывания:

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

Ресурс сценария развертывания доступен только в регионах, где доступен экземпляр контейнера Azure. См. сведения о доступности ресурсов для экземпляров контейнеров Azure в регионах Azure. В настоящее время сценарий развертывания использует только общедоступные сети.

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

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

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

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

• Субъект развертывания (субъект, используемый для развертывания шаблона): этот субъект используется для создания базовых ресурсов, необходимых для выполнения ресурса сценария развертывания — учетной записи хранения и экземпляра контейнера 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/*"
        ],
       "dataActions": [
          "Microsoft.Storage/storageAccounts/fileServices/*"
        ]
      }
    ],
    "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 в скрипте развертывания.

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

Шаблоны с примерами

Ниже приведен пример файла JSON. Дополнительные сведения см. в последней схеме шаблона.

{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "runPowerShellInline",
  "location": "[resourceGroup().location]",
  "tags": {
    "tagName1": "tagValue1",
    "tagName2": "tagValue2"
  },
  "kind": "AzurePowerShell", // or "AzureCLI"
  "identity": {
    "type": "userAssigned",
    "userAssignedIdentities": {
      "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID": {}
    }
  },
  "properties": {
    "forceUpdateTag": "1",
    "containerSettings": {
      "containerGroupName": "mycustomaci"
    },
    "storageAccountSettings": {
      "storageAccountName": "myStorageAccount",
      "storageAccountKey": "myKey"
    },
    "azPowerShellVersion": "9.7",  // or "azCliVersion": "2.47.0",
    "arguments": "-name \\\"John Dole\\\"",
    "environmentVariables": [
      {
        "name": "UserName",
        "value": "jdole"
      },
      {
        "name": "Password",
        "secureValue": "jDolePassword"
      }
    ],
    "scriptContent": "
      param([string] $name)
      $output = 'Hello {0}. The username is {1}, the password is {2}.' -f $name,${Env:UserName},${Env:Password}
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    ", // or "primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",
    "supportingScriptUris":[],
    "timeout": "PT30M",
    "cleanupPreference": "OnSuccess",
    "retentionInterval": "P1D"
  }
}

Сведения о значениях свойств.

• identity: Для API скрипта развертывания версии 2020-10-01 или более поздней пользовательская управляемая идентификация является необязательной, если вам не нужно выполнять какие-либо специфические действия Azure в скрипте. Для программного интерфейса версии 2019-10-01 (предварительная версия) требуется управляемое удостоверение, так как служба сценариев развертывания использует его для выполнения сценариев. Если задано свойство идентификации, служба скрипта вызывает Connect-AzAccount -Identity перед вызовом пользовательского скрипта. Сейчас поддерживаются только управляемые удостоверения, назначаемые пользователем. Чтобы войти с помощью другого удостоверения, можно вызвать Connect-AzAccount в скрипте.

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

• kind. Укажите тип скрипта. В настоящее время поддерживаются скрипты Azure PowerShell и Azure CLI. Значения: AzurePowerShell и AzureCLI.

• forceUpdateTag: изменение этого значения между развертываниями шаблона приводит к повторному выполнению сценария развертывания. Функции newGuid() и utcNow() можно использовать только со значением параметра по умолчанию. Дополнительные сведения см. в статье Запуск скрипта более одного раза.

• containerSettings: укажите параметры для настройки экземпляра контейнера Azure. Для скрипта развертывания требуется новый экземпляр контейнера Azure. Нельзя указать уже существующий экземпляр контейнера Azure. Имя группы контейнеров можно настроить с помощью containerGroupName. Если этот параметр не указан, имя группы создается автоматически.

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

• azPowerShellVersion / azCliVersion: укажите используемую версию модуля. Список поддерживаемых версий Azure PowerShell. Версия определяет, какой образ контейнера следует использовать:

  • Az версия 9 и выше использует Ubuntu 22.04.
  • Версия Az больше или равна 6, но меньше 9 использует Ubuntu 20.04.
  • Версия Az меньше 6 использует Ubuntu 18.04.

  Внимание

  Рекомендуется обновить до последней версии Ubuntu, так как Ubuntu 18.04 приближается к концу его существования и больше не будет получать обновления для системы безопасности после 31 мая 2023 года.

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

  Внимание

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

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

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

  Если аргументы содержат escape-символы, используйте JsonEscaper для двойного экранирования этих символов. Вставьте исходную экранированную строку в инструмент, а затем нажмите кнопку Escape. Инструмент выводит строку с двойным преобразованием символов. Например, в предыдущем примере шаблона аргумент имеет значение -name \"John Dole\". Escape-строка имеет значение -name \\\"John Dole\\\".

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

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

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

• environmentVariables: укажите переменные среды, передаваемые в скрипт. Дополнительные сведения см. в статье "Разработка сценариев развертывания".

• scriptContent: укажите содержимое сценария. Чтобы запустить внешний сценарий, используйте primaryScriptUri. Примеры см. в разделе "Использование встроенного скрипта " и "Использование внешнего скрипта".

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

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

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

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

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

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

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

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

В приведенном ниже шаблоне определен один ресурс с типом Microsoft.Resources/deploymentScripts. Выделенная часть — встроенный сценарий.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "\\\"John Dole\\\""
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runPowerShellInlineWithOutput",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "scriptContent": "
          param([string] $name)
          $output = \"Hello {0}\" -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "arguments": "[concat('-name', ' ', parameters('name'))]",
        "timeout": "PT1H",
        "cleanupPreference": "OnSuccess",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('runPowerShellInlineWithOutput').outputs.text]",
      "type": "string"
    }
  }
}

Сценарий принимает один параметр и выводит значение параметра. DeploymentScriptOutputs используется для хранения выходных данных. В разделе выходных данных строка value показывает, как получить доступ к сохраненным значениям. Write-Output используется для отладки. Сведения о том, как получить доступ к выходному файлу, см. в статье "Мониторинг и устранение неполадок сценариев развертывания". Описание свойств см. в разделе "Примеры шаблонов".

Чтобы запустить скрипт, выберите " Попробовать открыть Cloud Shell", а затем вставьте следующий код в область оболочки.

$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 -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.json"

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

Выходные данные выглядят следующим образом.

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

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

"primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",

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

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

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

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

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

"scriptContent": "
    ...
    ./Create-Cert.ps1
    ...
"

"supportingScriptUris": [
  "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/create-cert.ps1"
],

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

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

Работа с выходными данными из скриптов PowerShell

В следующем шаблоне показана передача значений между двумя ресурсами deploymentScripts:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "John Dole"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate1",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-name', ' ', concat('\\\"', parameters('name'), '\\\"'))]",
        "scriptContent": "
          param([string] $name)
          $output = 'Hello {0}' -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    },
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate2",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "dependsOn": [
        "scriptInTemplate1"
      ],
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-textToEcho', ' ', concat('\\\"', reference('scriptInTemplate1').outputs.text, '\\\"'))]",
        "scriptContent": "
          param([string] $textToEcho)
          Write-Output $textToEcho
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $textToEcho
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('scriptInTemplate2').outputs.text]",
      "type": "string"
    }
  }
}

В первом ресурсе необходимо определить переменную $DeploymentScriptOutputs и использовать ее для хранения выходных значений. Чтобы получить доступ к выходному значению из другого ресурса в шаблоне, используйте следующий код.

reference('<ResourceName>').outputs.text

Работа с выходными данными из скриптов CLI

В отличие от сценариев развертывания Azure PowerShell, CLI/bash не предоставляет общую переменную для хранения выходных данных скрипта. Вместо этого она использует переменную среды с именем AZ_SCRIPTS_OUTPUT_PATH , чтобы указать расположение файла выходных данных скрипта. При выполнении скрипта развертывания в шаблоне ARM оболочка Bash автоматически настраивает эту переменную среды. Его предопределенное значение задается как /mnt/azscripts/azscriptoutput/scriptoutputs.json. Выходные данные необходимы для соответствия допустимой структуре объекта строки JSON. Содержимое файла должно быть отформатировано как пара "ключ-значение". Например, массив строк следует сохранить как {"MyResult": ["foo", "bar"]}. Хранение только результатов массива, таких как [foo", "bar" ], считается недопустимым.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "identity": {
      "type": "string"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runBashWithOutputs",
      "location": "[resourceGroup().location]",
      "kind": "AzureCLI",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "[parameters('identity')]": {
          }
        }
      },
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "AzCliVersion": "2.40.0",
        "timeout": "PT30M",
        "arguments": "'foo' 'bar'",
        "environmentVariables": [
          {
            "name": "UserName",
            "value": "jdole"
          },
          {
            "name": "Password",
            "secureValue": "jDolePassword"
          }
        ],
        "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo \"arg2 is: $2\"; echo \"Username is: $UserName\"; echo \"password is: $Password\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
        "cleanupPreference": "OnExpiration",
        "retentionInterval": "P1D"

jq используется в предыдущем примере. Он поставляется с образами контейнеров. См . раздел "Настройка среды разработки".

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

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

• Поддерживаемые типы учетных записей хранения:

  Артикул	Поддерживаемый вид
  Premium_LRS	Хранилище файлов
  Premium_ZRS	Хранилище файлов
  Стандарт_GRS	Хранилище, StorageV2
  Standard_GZRS	StorageV2
  Standard_LRS	Хранилище, StorageV2
  Standard_RAGRS	Хранилище, StorageV2
  Standard_RAGZRS	StorageV2
  Standard_ZRS	StorageV2

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

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

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

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

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

"storageAccountSettings": {
  "storageAccountName": "myStorageAccount",
  "storageAccountKey": "myKey"
},

• storageAccountName: задайте имя учетной записи хранения.

• storageAccountKey: задайте один из ключей учетной записи хранения. Функцию listKeys() можно использовать для извлечения ключа. Например:

  "storageAccountSettings": {
      "storageAccountName": "[variables('storageAccountName')]",
      "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
  }
  

Полный пример определения приведен в разделе Microsoft.Resources/deploymentScripts.

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

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

Обработка нетерминации ошибок

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

Служба скриптов задает состояние подготовки ресурсов как Сбой, когда происходит ошибка, вне зависимости от настройки $ErrorActionPreference.

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

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

Дополнительные сведения об использовании AZ_SCRIPTS_OUTPUT_PATHсм. в статье "Работа с выходными данными из скрипта CLI".

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

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

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

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

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

Пользовательский сценарий, результаты выполнения и файл stdout хранятся в общих папках учетной записи хранения. Существует папка с именем azscripts. В ней есть еще две папки для входных и выходных файлов: azscriptinput и azscriptoutput.

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

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

После развертывания ресурса скрипта развертывания он будет отображаться в группе ресурсов на портале Azure. На следующем снимке экрана показана страница Обзора ресурса скрипта развертывания.

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

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

С помощью PowerShell

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

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

Выходные данные Get-AzDeploymentScript должны иметь следующий вид:

Name                : runPowerShellInlineWithOutput
Id                  : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput
ResourceGroupName   : myds0618rg
Location            : centralus
SubscriptionId      : aaaabbbb-0000-cccc-1111-dddd2222eeee
ProvisioningState   : Succeeded
Identity            : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mydentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 9.7
StartTime           : 5/11/2023 7:46:45 PM
EndTime             : 5/11/2023 7:49:45 PM
ExpirationDate      : 5/12/2023 7:49:45 PM
CleanupPreference   : OnSuccess
StorageAccountId    : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Storage/storageAccounts/ftnlvo6rlrvo2azscripts
ContainerInstanceId : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.ContainerInstance/containerGroups/ftnlvo6rlrvo2azscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole

RetentionInterval   : P1D
Timeout             : PT1H

Использование Azure CLI

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

• az deployment-scripts delete: Удалить сценарий развертывания.
• az deployment-scripts list: Перечислить все сценарии развертывания.
• az deployment-scripts show: Получение скрипта развертывания.
• az deployment-scripts show-log: показать журналы скриптов развертывания.

Выходные данные команды list похожи на:

[
  {
    "arguments": "'foo' 'bar'",
    "azCliVersion": "2.40.0",
    "cleanupPreference": "OnExpiration",
    "containerSettings": {
      "containerGroupName": null
    },
    "environmentVariables": null,
    "forceUpdateTag": "20231101T163748Z",
    "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runBashWithOutputs",
    "identity": {
      "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
      "type": "userAssigned",
      "userAssignedIdentities": {
        "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myidentity/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
          "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
          "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
        }
      }
    },
    "kind": "AzureCLI",
    "location": "centralus",
    "name": "runBashWithOutputs",
    "outputs": {
      "Result": [
        {
          "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mytest/providers/Microsoft.KeyVault/vaults/mykv1027",
          "resourceGroup": "mytest"
        }
      ]
    },
    "primaryScriptUri": null,
    "provisioningState": "Succeeded",
    "resourceGroup": "mytest",
    "retentionInterval": "1 day, 0:00:00",
    "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "status": {
      "containerInstanceId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mytest/providers/Microsoft.ContainerInstance/containerGroups/eg6n7wvuyxn7iazscripts",
      "endTime": "2023-11-01T16:39:12.080950+00:00",
      "error": null,
      "expirationTime": "2023-11-02T16:39:12.080950+00:00",
      "startTime": "2023-11-01T16:37:53.139700+00:00",
      "storageAccountId": null
    },
    "storageAccountSettings": {
      "storageAccountKey": null,
      "storageAccountName": "dsfruro267qwb4i"
    },
    "supportingScriptUris": null,
    "systemData": {
      "createdAt": "2023-10-31T19:06:57.060909+00:00",
      "createdBy": "[email protected]",
      "createdByType": "User",
      "lastModifiedAt": "2023-11-01T16:37:51.859570+00:00",
      "lastModifiedBy": "[email protected]",
      "lastModifiedByType": "User"
    },
    "tags": null,
    "timeout": "0:30:00",
    "type": "Microsoft.Resources/deploymentScripts"
  }
]

Использование 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 login
armclient get /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

Выходные данные должны иметь следующий вид:

{
  "kind": "AzurePowerShell",
  "identity": {
    "type": "userAssigned",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "userAssignedIdentities": {
      "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myidentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
        "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444"
      }
    }
  },
  "location": "centralus",
  "systemData": {
    "createdBy": "[email protected]",
    "createdByType": "User",
    "createdAt": "2023-05-11T02:59:04.7501955Z",
    "lastModifiedBy": "[email protected]",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2023-05-11T02:59:04.7501955Z"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "forceUpdateTag": "20220625T025902Z",
    "azPowerShellVersion": "9.7",
    "scriptContent": "\r\n          param([string] $name)\r\n          $output = \"Hello {0}\" -f $name\r\n          Write-Output $output\r\n          $DeploymentScriptOutputs = @{}\r\n          $DeploymentScriptOutputs['text'] = $output\r\n        ",
    "arguments": "-name \\\"John Dole\\\"",
    "retentionInterval": "P1D",
    "timeout": "PT1H",
    "containerSettings": {},
    "status": {
      "containerInstanceId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.ContainerInstance/containerGroups/64lxews2qfa5uazscripts",
      "storageAccountId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Storage/storageAccounts/64lxews2qfa5uazscripts",
      "startTime": "2023-05-11T02:59:07.5951401Z",
      "endTime": "2023-05-11T03:00:16.7969234Z",
      "expirationTime": "2023-05-12T03:00:16.7969234Z"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "runPowerShellInlineWithOutput"
}

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

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

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

Чтобы просмотреть ресурс deploymentScripts на портале, выберите "Показать скрытые типы":

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

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

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

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

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

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

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

  Экземпляр контейнера и учетная запись хранения удаляются в соответствии с cleanupPreference. Однако если скрипт завершается ошибкой и cleanupPreference не задано значение Always, процесс развертывания автоматически сохраняет контейнер в течение одного часа или до очистки контейнера. Вы можете использовать время для устранения неполадок скрипта. Чтобы контейнер запускался после успешного развертывания, добавьте в скрипт шаг "спящий режим". Например, добавьте start-Sleep в конец скрипта. Если не добавить шаг спящего режима, контейнер будет находиться терминальном состоянии, и к нему нельзя будет получить доступ, даже если он еще не удален.

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

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

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

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

• Измените имя ресурсаdeploymentScripts. Например, используйте функцию шаблона UTCNow в качестве имени ресурса или в составе имени ресурса. При изменении имени ресурса создается новый ресурс deploymentScripts. Целесообразно сохранить журнал выполнения сценария.

  Примечание.

  Функция utcNow может использоваться только в значении параметра по умолчанию.

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

Настройка среды разработки

В качестве среды разработки скрипта развертывания можно использовать предварительно настроенный образ контейнера. Дополнительные сведения см. в статье "Настройка среды разработки для сценариев развертывания" в шаблонах.

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

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

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

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

Команды

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

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

Разрешения

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

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

С помощью Microsoft.Resources/deploymentScripts версии 2023-08-01 можно запускать сценарии развертывания в частных сетях с некоторыми дополнительными конфигурациями.

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

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

  1. Откройте учетную запись хранения на портале Azure.

  2. В меню слева выберите элемент Управления доступом (IAM) и перейдите на вкладку "Назначения ролей ".

  3. Добавьте роль Storage File Data Privileged Contributor к управляемому удостоверению назначения пользователя.

  4. В меню слева в разделе "Безопасность и сеть" выберите "Сеть" и выберите "Брандмауэры" и "Виртуальные сети".

  5. Выберите "Включено" из выбранных виртуальных сетей и IP-адресов.

     

  6. В разделе "Виртуальные сети" добавьте подсеть. На снимке экрана подсеть называется dspvnVnet.

  7. В разделе "Исключения" выберите "Разрешить службам Azure" в списке доверенных служб доступ к этой учетной записи хранения.

В следующем шаблоне ARM показано, как настроить среду для запуска скрипта развертывания:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string",
      "maxLength": 10
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "userAssignedIdentityName": {
      "type": "string",
      "defaultValue": "[format('{0}Identity', parameters('prefix'))]"
    },
    "storageAccountName": {
      "type": "string",
      "defaultValue": "[format('{0}stg{1}', parameters('prefix'), uniqueString(resourceGroup().id))]"
    },
    "vnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Vnet', parameters('prefix'))]"
    },
    "subnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Subnet', parameters('prefix'))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2023-09-01",
      "name": "[parameters('vnetName')]",
      "location": "[parameters('location')]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "10.0.0.0/16"
          ]
        },
        "enableDdosProtection": false,
        "subnets": [
          {
            "name": "[parameters('subnetName')]",
            "properties": {
              "addressPrefix": "10.0.0.0/24",
              "serviceEndpoints": [
                {
                  "service": "Microsoft.Storage"
                }
              ],
              "delegations": [
                {
                  "name": "Microsoft.ContainerInstance.containerGroups",
                  "properties": {
                    "serviceName": "Microsoft.ContainerInstance/containerGroups"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2023-01-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {
        "networkAcls": {
          "bypass": "AzureServices",
          "virtualNetworkRules": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]",
              "action": "Allow",
              "state": "Succeeded"
            }
          ],
          "defaultAction": "Deny"
        },
        "allowSharedKeyAccess": true
      },
      "dependsOn": [
        "[resourceId('Microsoft.Network/virtualNetworks', parameters('vnetName'))]"
      ]
    },
    {
      "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
      "apiVersion": "2023-07-31-preview",
      "name": "[parameters('userAssignedIdentityName')]",
      "location": "[parameters('location')]"
    },
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2022-04-01",
      "scope": "[format('Microsoft.Storage/storageAccounts/{0}', parameters('storageAccountName'))]",
      "name": "[guid(tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd'), resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName')))]",
      "properties": {
        "principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), '2023-07-31-preview').principalId]",
        "roleDefinitionId": "[tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd')]",
        "principalType": "ServicePrincipal"
      },
      "dependsOn": [
        "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
      ]
    }
  ]
}

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    },
    "storageAccountName": {
      "type": "string"
    },
    "vnetName": {
      "type": "string"
    },
    "subnetName": {
      "type": "string"
    },
    "userAssignedIdentityName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2023-08-01",
      "name": "[format('{0}DS', parameters('prefix'))]",
      "location": "[parameters('location')]",
      "identity": {
        "type": "userAssigned",
        "userAssignedIdentities": {
          "[format('{0}', resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')))]": {}
        }
      },
      "kind": "AzureCLI",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azCliVersion": "2.47.0",
        "storageAccountSettings": {
          "storageAccountName": "[parameters('storageAccountName')]"
        },
        "containerSettings": {
          "subnetIds": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]"
            }
          ]
        },
        "scriptContent": "echo \"Hello world!\"",
        "retentionInterval": "P1D",
        "cleanupPreference": "OnExpiration"
      }
    }
  ]
}

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

В этой статье вы узнали, как использовать сценарии развертывания. Теперь вы можете изучить учебник по сценариям развертывания: