Поделиться через

Руководство: Используйте скрипты развертывания для создания самоподписного сертификата

Узнайте, как использовать сценарии развертывания в шаблонах Azure Resource Manager (шаблоны ARM). Скрипты развертывания можно использовать для выполнения пользовательских действий, которые не могут выполняться шаблонами ARM. Например, создание самозаверяющего сертификата. В этом руководстве вы создадите шаблон для развертывания хранилища ключей Azure, а затем используйте Microsoft.Resources/deploymentScripts ресурс в том же шаблоне, чтобы создать сертификат, а затем добавить сертификат в хранилище ключей. Дополнительные сведения о скрипте развертывания см. в статье "Использование сценариев развертывания" в шаблонах ARM.

Это важно

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

В этом руководстве рассматриваются следующие задачи:

  • Открытие шаблона быстрого запуска
  • Изменение шаблона
  • Развертывание шаблона
  • Отладка неудачного скрипта
  • Очистите ресурсы

Модуль Learn, охватывающий сценарии развертывания, см. в статье "Расширение шаблонов ARM с помощью сценариев развертывания".

Предпосылки

Для работы с этой статьей необходимо иметь следующее.

  • Visual Studio Code.

  • Управляемое удостоверение пользователя. Этот идентификатор используется в скрипте для выполнения действий, специфичных для Azure. Чтобы создать его, см. управляемое удостоверение, назначаемое пользователем. При развертывании шаблона вам потребуется идентификатор удостоверения. Формат удостоверения:

    /subscriptions/<SubscriptionID>/resourcegroups/<ResourceGroupName>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<IdentityID>

    Используйте следующий скрипт командной строки (CLI), чтобы получить идентификатор, указав имя группы ресурсов и имя удостоверения.

    echo "Enter the Resource Group name:" &&
read resourceGroupName &&
az identity list -g $resourceGroupName

Открытие шаблона быстрого запуска

Вместо создания шаблона с нуля вы открываете шаблон из шаблонов быстрого запуска Azure. Шаблоны быстрого запуска Azure — это репозиторий для шаблонов ARM.

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

  1. В Visual Studio Code выберите"Открыть файл>".

  2. В имени файла вставьте следующий URL-адрес:

    https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.keyvault/key-vault-create/azuredeploy.json

  3. Нажмите кнопку "Открыть ", чтобы открыть файл.

  4. Выберите Файл>Сохранить как, чтобы сохранить файл на локальном компьютере как azuredeploy.json.

Изменение шаблона

Внесите следующие изменения в шаблон:

Очистка шаблона (необязательно)

Исходный шаблон добавляет секрет в хранилище ключей. Чтобы упростить учебник, удалите следующий ресурс:

  • Microsoft.KeyVault/vaults/secrets

Удалите следующие два определения параметров:

  • secretName
  • secretValue

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

Настройка политик доступа к хранилищу ключей

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

  1. Добавьте параметр, чтобы получить идентификатор управляемого удостоверения.

    "identityId": {
  "type": "string",
  "metadata": {
    "description": "Specifies the ID of the user-assigned managed identity."
  }
},

  2. Добавьте параметр для настройки политик доступа к хранилищу ключей, чтобы управляемое удостоверение может добавлять сертификаты в хранилище ключей:

    "certificatesPermissions": {
  "type": "array",
  "defaultValue": [
    "get",
    "list",
    "update",
    "create"
  ],
  "metadata": {
  "description": "Specifies the permissions to certificates in the vault. Valid values are: all, get, list, update, create, import, delete, recover, backup, restore, manage contacts, manage certificate authorities, get certificate authorities, list certificate authorities, set certificate authorities, delete certificate authorities."
  }
}

  3. Обновите существующие политики доступа к хранилищу ключей Microsoft.KeyVault/vaults ресурса, чтобы:

    "accessPolicies": [
  {
    "objectId": "[parameters('objectId')]",
    "tenantId": "[parameters('tenantId')]",
    "permissions": {
      "keys": "[parameters('keysPermissions')]",
      "secrets": "[parameters('secretsPermissions')]",
      "certificates": "[parameters('certificatesPermissions')]"
    }
  },
  {
    "objectId": "[reference(parameters('identityId'), '2018-11-30').principalId]",
    "tenantId": "[parameters('tenantId')]",
    "permissions": {
      "keys": "[parameters('keysPermissions')]",
      "secrets": "[parameters('secretsPermissions')]",
      "certificates": "[parameters('certificatesPermissions')]"
    }
  }
],

    Определены две политики: одна для авторизованного пользователя, другая — для управляемого удостоверения. Для проверки развертывания пользователю, вошедшего в систему, требуется только разрешение списка . Чтобы упростить руководство, один и тот же сертификат назначается как для управляемого удостоверения, так и для пользователей, вошедших в систему.

Добавление скрипта развертывания

  1. Добавьте три параметра, которые используются скриптом развертывания:

    "certificateName": {
  "type": "string",
  "defaultValue": "DeploymentScripts2019"
},
"subjectName": {
  "type": "string",
  "defaultValue": "CN=contoso.com"
},
"utcValue": {
  "type": "string",
  "defaultValue": "[utcNow()]"
}

  2. Добавьте ресурс deploymentScripts.

    Замечание

    Так как встроенные сценарии развертывания заключены в двойные кавычки, строки внутри скриптов развертывания должны быть заключены в одинарные кавычки. Экранный символ PowerShell — это обратный апостроф (`).

    {
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2023-08-01",
  "name": "createAddCertificate",
  "location": "[resourceGroup().location]",
  "dependsOn": [
    "[resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))]"
  ],
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "[parameters('identityId')]": {
      }
    }
  },
  "kind": "AzurePowerShell",
  "properties": {
    "forceUpdateTag": "[parameters('utcValue')]",
    "azPowerShellVersion": "3.0",
    "timeout": "PT30M",
    "arguments": "[format(' -vaultName {0} -certificateName {1} -subjectName {2}', parameters('keyVaultName'), parameters('certificateName'), parameters('subjectName'))]", // can pass an argument string, double quotes must be escaped
    "scriptContent": "
      param(
        [string] [Parameter(Mandatory=$true)] $vaultName,
        [string] [Parameter(Mandatory=$true)] $certificateName,
        [string] [Parameter(Mandatory=$true)] $subjectName
      )

      $ErrorActionPreference = 'Stop'
      $DeploymentScriptOutputs = @{}

      $existingCert = Get-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName

      if ($existingCert -and $existingCert.Certificate.Subject -eq $subjectName) {

        Write-Host 'Certificate $certificateName in vault $vaultName is already present.'

        $DeploymentScriptOutputs['certThumbprint'] = $existingCert.Thumbprint
        $existingCert | Out-String
      }
      else {
        $policy = New-AzKeyVaultCertificatePolicy -SubjectName $subjectName -IssuerName Self -ValidityInMonths 12 -Verbose

        # private key is added as a secret that can be retrieved in the Resource Manager template
        Add-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName -CertificatePolicy $policy -Verbose

        # it takes a few seconds for KeyVault to finish
        $tries = 0
        do {
          Write-Host 'Waiting for certificate creation completion...'
          Start-Sleep -Seconds 10
          $operation = Get-AzKeyVaultCertificateOperation -VaultName $vaultName -Name $certificateName
          $tries++

          if ($operation.Status -eq 'failed')
          {
            throw 'Creating certificate $certificateName in vault $vaultName failed with error $($operation.ErrorMessage)'
          }

          if ($tries -gt 120)
          {
            throw 'Timed out waiting for creation of certificate $certificateName in vault $vaultName'
          }
        } while ($operation.Status -ne 'completed')

        $newCert = Get-AzKeyVaultCertificate -VaultName $vaultName -Name $certificateName
        $DeploymentScriptOutputs['certThumbprint'] = $newCert.Thumbprint
        $newCert | Out-String
      }
    ",
    "cleanupPreference": "OnSuccess",
    "retentionInterval": "P1D"
  }
}

    Ресурс deploymentScripts зависит от ресурса хранилища ключей и ресурса назначения ролей. Он имеет следующие свойства:

    • identity: сценарий развертывания использует управляемое удостоверение, назначаемое пользователем, для выполнения операций в скрипте.
    • kind: укажите тип скрипта. В настоящее время поддерживаются только скрипты PowerShell.
    • forceUpdateTag: определите, следует ли выполнять скрипт развертывания, даже если источник скрипта не изменился. Может быть текущей меткой времени или GUID. Дополнительные сведения см. в статье "Многократный запуск скрипта".
    • azPowerShellVersion: указывает используемую версию модуля Azure PowerShell. В настоящее время скрипт развертывания поддерживает версию 2.7.0, 2.8.0 и 3.0.0.
    • timeout: укажите максимально допустимое время выполнения скрипта, указанное в формате ISO 8601. Значение по умолчанию — P1D.
    • arguments: укажите значения параметров. Значения разделяются пробелами.
    • scriptContent: укажите содержимое скрипта. Чтобы запустить внешний скрипт, используйте primaryScriptURI вместо этого. Дополнительные сведения см. в разделе "Использование внешнего скрипта". Объявление $DeploymentScriptOutputs требуется только при тестировании скрипта на локальном компьютере. Объявление переменной позволяет запускать скрипт на локальном компьютере и ресурсе deploymentScript без внесения изменений. Значение, присвоенное $DeploymentScriptOutputs, доступно как результаты в развертываниях. Дополнительные сведения см. в статье "Работа с выходными данными из скриптов развертывания PowerShell " или "Работа с выходными данными из скриптов развертывания CLI".
    • cleanupPreference: укажите предпочтения по удалению ресурсов скрипта развертывания. Значением по умолчанию является Always, то есть ресурсы скрипта развертывания удаляются, несмотря на состояние терминала (успешно, сбой, отмена). В этом руководстве используется OnSuccess , чтобы получить возможность просмотреть результаты выполнения скрипта.
    • retentionInterval: укажите интервал, для которого служба сохраняет ресурсы скрипта после достижения состояния терминала. Ресурсы будут удалены при истечении срока действия. Длительность основана на шаблоне ISO 8601. В этом руководстве используется P1D, что означает один день. Это свойство используется, если cleanupPreference задано значение OnExpiration. Сейчас это свойство не включено.

    Сценарий развертывания принимает три параметра: keyVaultName, certificateNameи subjectName. Он создает сертификат, а затем добавляет сертификат в хранилище ключей.

    $DeploymentScriptOutputs используется для хранения выходных значений. Дополнительные сведения см. в статье "Работа с выходными данными из скриптов развертывания PowerShell " или "Работа с выходными данными из скриптов развертывания CLI".

    Полный шаблон можно найти здесь.

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

    Write-Output1 $keyVaultName

    Правильная команда — это Write-Output, вместо Write-Output1.

  4. Нажмите кнопку"Сохранить>", чтобы сохранить файл.

Развертывание шаблона

  1. Вход в Azure Cloud Shell

  2. Выберите предпочитаемую среду, выбрав PowerShell или Bash (для CLI) в левом верхнем углу. Перезапуск оболочки требуется при переключении.

    Загрузка файла в Azure Cloud Shell через портал

  3. Выберите " Отправить и скачать файлы", а затем нажмите кнопку "Отправить". См. предыдущий снимок экрана. Выберите файл, сохраненный в предыдущем разделе. После отправки файла можно использовать ls команду и cat команду для проверки успешной отправки файла.

  4. Выполните следующий скрипт Azure CLI или Azure PowerShell, чтобы развернуть шаблон.

    echo "Enter a project name that is used to generate resource names:" &&
read projectName &&
echo "Enter the location (i.e. centralus):" &&
read location &&
echo "Enter your email address used to sign in to Azure:" &&
read upn &&
echo "Enter the user-assigned managed identity ID:" &&
read identityId &&
adUserId=$((az ad user show --id ${upn}) | jq -r '.id') &&
resourceGroupName="${projectName}rg" &&
keyVaultName="${projectName}kv" &&
az group create --name $resourceGroupName --location $location &&
az deployment group create --resource-group $resourceGroupName --template-file "$HOME/azuredeploy.json" --parameters identityId=$identityId keyVaultName=$keyVaultName objectId=$adUserId

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

    Сбой развертывания, так как в скрипте используется недопустимая команда Write-Output1 . Вы получите сообщение об ошибке:

    The term 'Write-Output1' is not recognized as the name of a cmdlet, function, script file, or operable
program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

    Результат выполнения скрипта развертывания хранится в ресурсах скрипта развертывания для устранения неполадок.

Отладка неудачного скрипта

  1. Войдите на портал Azure.

  2. Откройте группу ресурсов. Это имя проекта с добавленным rg . В группе ресурсов вы увидите два дополнительных ресурса. Эти ресурсы называются ресурсами скрипта развертывания.

    Ресурсы скрипта развертывания шаблона Resource Manager

    Оба файла имеют суффикс azscripts . Одна из них — это аккаунт для хранения данных, а другая — контейнер-инстанс.

    Выберите "Показать скрытыеdeploymentScripts типы", чтобы перечислить ресурс.

  3. Выберите учетную запись хранения с суффиксом azscripts .

  4. Выберите плитку общих папок . Вы увидите папку azscripts , содержащую файлы выполнения скрипта развертывания.

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

Удалите строку Write-Output1 и повторно разверните шаблон.

При успешном выполнении второго развертывания ресурсы скрипта развертывания будут удалены службой скриптов, так как cleanupPreference свойство имеет значение OnSuccess.

Очистите ресурсы

Если ресурсы Azure больше не нужны, очистите развернутые ресурсы, удалив группу ресурсов.

  1. На портале Azure выберите группу ресурсов в меню слева.
  2. Введите имя группы ресурсов в поле "Фильтр по имени ".
  3. Выберите имя группы ресурсов.
  4. Выберите "Удалить группу ресурсов " в верхнем меню.

Дальнейшие шаги

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

Условия использования

  • Last updated on