Tutorial: Usar scripts de implantação para criar um certificado autoassinado

Artigo
06/20/2024

Saiba como usar scripts de implantação em modelos do Azure Resource Manager (modelos ARM). Os scripts de implantação podem ser usados para executar etapas personalizadas que não podem ser feitas por modelos ARM. Por exemplo, criar um certificado autoassinado. Neste tutorial, você cria um modelo para implantar um cofre de chaves do Azure e, em seguida, usa um recurso no mesmo modelo para criar um Microsoft.Resources/deploymentScripts certificado e, em seguida, adicionar o certificado ao cofre de chaves. Para saber mais sobre script de implantação, consulte Usar scripts de implantação em modelos ARM.

Importante

Dois recursos de script de implantação, uma conta de armazenamento e uma instância de contêiner, são criados no mesmo grupo de recursos para execução de script e solução de problemas. Esses recursos geralmente são excluídos pelo serviço de script quando a execução do script fica em um estado terminal. Você será cobrado pelos recursos até que os recursos sejam excluídos. Para saber mais, consulte Limpar recursos de script de implantação.

Este tutorial abrange as seguintes tarefas:

Abrir um modelo de início rápido
Editar o modelo
Implementar o modelo
Depurar o script com falha
Clean up resources (Limpar recursos)

Para obter um módulo do Learn que aborda scripts de implantação, consulte Estender modelos ARM usando scripts de implantação.

Pré-requisitos

Para concluir este artigo, precisa de:

Código do Visual Studio com a extensão Resource Manager Tools. Consulte Guia de início rápido: criar modelos ARM com o Visual Studio Code.

Uma identidade gerenciada atribuída pelo usuário. Essa identidade é usada para executar ações específicas do Azure no script. Para criar uma, consulte Identidade gerenciada atribuída pelo usuário. Você precisa do ID de identidade ao implantar o modelo. O formato da identidade é:

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

Use o seguinte script da CLI para obter a ID fornecendo o nome do grupo de recursos e o nome da identidade.

CLI
PowerShell

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

$resourceGroupName = Read-Host -Prompt "Enter the Resource Group name"
(Get-AzUserAssignedIdentity -ResourceGroupName $resourceGroupname).id

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

Abrir um modelo de Início Rápido

Em vez de criar um modelo de raiz, pode abrir um modelo dos Modelos de Início Rápido do Azure. Os Modelos de Início Rápido do Azure são um repositório para modelos ARM.

O modelo usado neste início rápido é chamado Criar um Cofre de Chaves do Azure e um segredo. O modelo cria um cofre de chaves e, em seguida, adiciona um segredo ao cofre de chaves.

No Visual Studio Code, selecione Ficheiro>Abrir Ficheiro.

em Nome de ficheiro, cole o seguinte URL:

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

Selecione Abrir para abrir o ficheiro.
Selecione Ficheiro>Guardar Como para guardar o ficheiro como azuredeploy.json no computador local.

Editar o modelo

Faça as seguintes alterações no modelo:

Limpar o modelo (opcional)

O modelo original adiciona um segredo ao cofre de chaves. Para simplificar o tutorial, remova o seguinte recurso:

Microsoft.KeyVault/vaults/secrets

Remova as duas definições de parâmetro a seguir:

secretName
secretValue

Se você optar por não remover essas definições, precisará especificar os valores dos parâmetros durante a implantação.

Configurar as políticas de acesso ao cofre de chaves

O script de implantação adiciona um certificado ao cofre de chaves. Configure as políticas de acesso ao cofre de chaves para dar permissão à identidade gerenciada:

Adicione um parâmetro para obter o ID de identidade gerenciado:
```
"identityId": {
  "type": "string",
  "metadata": {
    "description": "Specifies the ID of the user-assigned managed identity."
  }
},
```
Nota

A extensão de modelo do Gerenciador de Recursos do Visual Studio Code ainda não é capaz de formatar scripts de implantação. Não use Shift+Alt+F para formatar os deploymentScripts recursos, como o seguinte.

Adicione um parâmetro para configurar as políticas de acesso ao cofre de chaves para que a identidade gerenciada possa adicionar certificados ao cofre de chaves:

"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."
  }
}

Atualize as políticas de acesso ao cofre de chaves existentes para:

"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')]"
    }
  }
],

Há duas políticas definidas, uma para o usuário conectado e outra para a identidade gerenciada. O usuário conectado só precisa da permissão de lista para verificar a implantação. Para simplificar o tutorial, o mesmo certificado é atribuído à identidade gerenciada e aos usuários conectados.

Adicionar o script de implantação

Adicione três parâmetros que são usados pelo script de implantação:

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

Adicionar um deploymentScripts recurso:

Nota

Como os scripts de implantação embutidos são colocados entre aspas duplas, as cadeias de caracteres dentro dos scripts de implantação precisam ser colocadas entre aspas simples. O caractere de escape do PowerShell é o backtick (`).
```
{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-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"
  }
}
```
O deploymentScripts recurso depende do recurso de cofre de chave e do recurso de atribuição de função. Tem as seguintes propriedades:
- identity: O script de implantação usa uma identidade gerenciada atribuída pelo usuário para executar as operações no script.
- kind: Especifique o tipo de script. Atualmente, apenas scripts do PowerShell são suportados.
- forceUpdateTag: Determine se o script de implantação deve ser executado mesmo que a origem do script não tenha sido alterada. Pode ser um carimbo de data/hora atual ou um GUID. Para saber mais, consulte Executar script mais de uma vez.
- azPowerShellVersion: Especifica a versão do módulo do Azure PowerShell a ser usada. Atualmente, o script de implantação suporta as versões 2.7.0, 2.8.0 e 3.0.0.
- timeout: Especifique o tempo máximo permitido de execução do script especificado no formato ISO 8601. O valor padrão é P1D.
- arguments: Especifique os valores dos parâmetros. Os valores são separados por espaços.
- scriptContent: Especifique o conteúdo do script. Para executar um script externo, use primaryScriptURI em vez disso. Para obter mais informações, consulte Usar script externo. A declaração $DeploymentScriptOutputs só é necessária ao testar o script em uma máquina local. Declarar a variável permite que o script seja executado em uma máquina local e em um deploymentScript recurso sem ter que fazer alterações. O valor atribuído a $DeploymentScriptOutputs está disponível como saídas nas implantações. Para obter mais informações, consulte Trabalhar com saídas de scripts de implantação do PowerShell ou Trabalhar com saídas de scripts de implantação da CLI.
- cleanupPreference: Especifique a preferência sobre quando excluir os recursos do script de implantação. O valor padrão é Always, o que significa que os recursos do script de implantação são excluídos apesar do estado do terminal (Succeeded, Failed, Canceled). Neste tutorial, OnSuccess é usado para que você tenha a chance de visualizar os resultados da execução do script.
- retentionInterval: Especifique o intervalo para o qual o serviço retém os recursos de script depois de atingir um estado terminal. Os recursos serão excluídos quando essa duração expirar. A duração é baseada no padrão ISO 8601. Este tutorial usa P1D, o que significa um dia. Esta propriedade é usada quando cleanupPreference é definida como OnExpiration. Esta propriedade não está habilitada atualmente.
O script de implantação usa três parâmetros: keyVaultName, certificateNamee subjectName. Ele cria um certificado e, em seguida, adiciona o certificado ao cofre de chaves.

$DeploymentScriptOutputs é usado para armazenar o valor de saída. Para saber mais, consulte Trabalhar com saídas de scripts de implantação do PowerShell ou Trabalhar com saídas de scripts de implantação da CLI.

O modelo completo pode ser encontrado aqui.
Para ver o processo de depuração, coloque um erro no código adicionando a seguinte linha ao script de implantação:
```
Write-Output1 $keyVaultName
```
O comando correto é Write-Output em vez de Write-Output1.
Selecione Ficheiro>Guardar para guardar o ficheiro.

Implementar o modelo

Entre no Azure Cloud Shell
Escolha seu ambiente preferido selecionando PowerShell ou Bash (para CLI) no canto superior esquerdo. É necessário reiniciar o Shell quando mudar.
Selecione Carregar/transferir ficheiros e, em seguida, selecione Carregar. Veja a captura de ecrã anterior. Selecione o ficheiro que guardou na secção anterior. Depois de carregar o arquivo, você pode usar o comando e o comando para verificar se o ls cat arquivo foi carregado com êxito.

Execute o seguinte script da CLI do Azure ou do Azure PowerShell para implantar o modelo.

CLI
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

$projectName = Read-Host -Prompt "Enter a project name that is used to generate resource names"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"
$upn = Read-Host -Prompt "Enter your email address used to sign in to Azure"
$identityId = Read-Host -Prompt "Enter the user-assigned managed identity ID"

$adUserId = (Get-AzADUser -UserPrincipalName $upn).Id
$resourceGroupName = "${projectName}rg"
$keyVaultName = "${projectName}kv"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateFile "$HOME/azuredeploy.json" -identityId $identityId -keyVaultName $keyVaultName -objectId $adUserId

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

O serviço de script de implantação precisa criar recursos de script de implantação adicionais para a execução de script. O processo de preparação e limpeza pode levar até um minuto para ser concluído, além do tempo real de execução do script.

A implantação falhou porque o comando Write-Output1 inválido é usado no script. Você receberá um erro dizendo:

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.

O resultado da execução do script de implantação é armazenado nos recursos do script de implantação para a finalidade de solução de problemas.

Depurar o script com falha

Inicie sessão no portal do Azure.
Abra o grupo de recursos. É o nome do projeto com rg anexado. Você verá dois recursos adicionais no grupo de recursos. Esses recursos são chamados de recursos de script de implantação.

Ambos os arquivos têm o sufixo azscripts . Uma é uma conta de armazenamento e a outra é uma instância de contêiner.

Selecione Mostrar tipos ocultos para listar o deploymentScripts recurso.
Selecione a conta de armazenamento com o sufixo azscripts .
Selecione o bloco Compartilhamentos de arquivos. Você verá uma pasta azscripts que contém os arquivos de execução do script de implantação.
Selecione azscripts. Você verá duas pastas azscriptinput e azscriptoutput. A pasta de entrada contém um arquivo de script do PowerShell do sistema e os arquivos de script de implantação do usuário. A pasta de saída contém um executionresult.json e o arquivo de saída de script. Você pode ver a mensagem de erro em executionresult.json. O arquivo de saída não está lá porque a execução falhou.

Remova a Write-Output1 linha e reimplante o modelo.

Quando a segunda implantação for executada com êxito, os recursos de script de implantação serão removidos pelo serviço de script, porque a cleanupPreference propriedade está definida como OnSuccess.

Clean up resources (Limpar recursos)

Quando os recursos do Azure já não forem necessários, limpe os recursos implementados ao eliminar o grupo de recursos.

No portal do Azure, selecione Grupo de recursos no menu à esquerda.
Introduza o nome do grupo de recursos no campo Filtrar por nome.
Selecione o nome do grupo de recursos.
Selecione Eliminar grupo de recursos no menu superior.

Próximos passos

Neste tutorial, você aprendeu como usar um script de implantação em modelos ARM. Para saber como implementar recursos do Azure com base em condições, veja:

Condições de utilização

Partilhar via