Compartilhar via


Usar scripts de implantação no Bicep

Usando o recurso deploymentScripts, você pode executar scripts em implantações do Bicep e examinar os resultados da execução. Você pode usar esses scripts para executar etapas personalizadas, como:

  • adicionar usuários a um diretório.
  • Executar operações do plano de dados; por exemplo, copiar blobs ou propagar um banco de dados.
  • pesquisar e validar uma chave de licença.
  • Crie um certificado autoassinado.
  • Crie um objeto no Microsoft Entra ID.
  • Procure blocos de endereço IP de um sistema personalizado.

Os benefícios dos scripts de implantação incluem:

  • Eles são fáceis de codificar, usar e depurar. Você pode desenvolver scripts de implantação em seus ambientes de desenvolvimento preferidos. Os scripts podem ser inseridos em arquivos Bicep ou em arquivos de script externos.
  • Você pode especificar a linguagem de script e a plataforma. Atualmente, há suporte para scripts de implantação do Azure PowerShell e da CLI do Azure no ambiente Linux.
  • Você pode permitir a passagem de argumentos de linha de comando para o script.
  • Você pode especificar saídas de script e passá-las de volta para a implantação.

O recurso de script de implantação só está disponível nas regiões em que as Instâncias de Contêiner do Azure estão disponíveis. Para obter mais informações, confira Disponibilidade de recursos para Instâncias de Contêiner do Azure nas regiões do Azure.

Aviso

O serviço de script de implantação requer dois recursos extras para executar e solucionar problemas de scripts: uma conta de armazenamento e uma instância de contêiner. Em geral, o serviço limpa esses recursos após a conclusão do script de implantação. Você incorre em encargos para esses recursos até que eles sejam removidos.

Para obter informações sobre preços, consulte o preço das Instâncias de Contêiner e os preços do Armazenamento do Microsoft Azure. Para saber mais, confira Limpar recursos do script de implantação.

Recursos de treinamento

Se você preferir saber mais sobre scripts de implantação por meio de diretrizes passo a passo, consulte Estender modelos Bicep e ARM usando scripts de implantação.

Configurar as permissões mínimas

Para a versão 2020-10-01 da API de script de implantação ou posterior, duas entidades de segurança estão envolvidas na execução do script de implantação:

  • Entidade de implantação: essa entidade de segurança é usada para implantar o arquivo Bicep. Ele cria recursos subjacentes necessários para que o recurso de script de implantação seja executado— uma conta de armazenamento e uma instância de contêiner do Azure. Para configurar as permissões de privilégios mínimos, atribua uma função personalizada com as seguintes propriedades à entidade de implantação:

    {
      "roleName": "deployment-script-minimum-privilege-for-deployment-principal",
      "description": "Configure least privilege for the deployment principal in deployment script",
      "type": "customRole",
      "IsCustom": true,
      "permissions": [
        {
          "actions": [
            "Microsoft.Storage/storageAccounts/*",
            "Microsoft.ContainerInstance/containerGroups/*",
            "Microsoft.Resources/deployments/*",
            "Microsoft.Resources/deploymentScripts/*"
          ],
        }
      ],
      "assignableScopes": [
        "[subscription().id]"
      ]
    }
    

    Se os provedores de recursos do Armazenamento do Microsoft Azure e das Instâncias de Contêiner do Azure não estiverem registrados, adicione Microsoft.Storage/register/action e Microsoft.ContainerInstance/register/action.

  • Entidade de script de implantação: essa entidade de segurança será necessária somente se o script de implantação precisar se autenticar no Azure e chamar a CLI do Azure ou o PowerShell. Há duas maneiras de especificar o script de implantação principal:

    • Especifique uma identidade gerenciada atribuída pelo usuário na propriedade identity. (Consulte a sintaxe do recurso de script de implantação.) Quando você especifica uma identidade gerenciada atribuída pelo usuário, o serviço de script chama Connect-AzAccount -Identity antes de invocar o script de implantação. A identidade gerenciada deve ter o acesso necessário para concluir a operação no script. Atualmente, há suporte apenas para uma identidade gerenciada atribuída pelo usuário para a propriedade identity. Para fazer logon com uma identidade diferente, use o segundo método nessa lista.
    • Passe as credenciais da entidade de serviço como variáveis de ambiente seguras e chame Connect-AzAccount ou az login no script de implantação.

    Se você usar uma identidade gerenciada, a entidade de implantação precisará da função de Operador de Identidade Gerenciada interna atribuída ao recurso de identidade gerenciada.

Atualmente, nenhuma função interna é adaptada para configurar permissões de script de implantação.

Criar scripts de implantação

O exemplo a seguir demonstra um arquivo Bicep simples com um recurso de script de implantação. O script usa um parâmetro de cadeia de caracteres e cria outra cadeia de caracteres.

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

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

output text string = deploymentScript.properties.outputs.text

Para obter mais informações sobre como criar recursos de script de implantação, consulte Criar scripts de implantação. Para a criação de scripts para o recurso de script de implantação, aconselhamos que você estabeleça um ambiente de desenvolvimento de script dedicado, como uma instância de contêiner do Azure ou uma imagem do Docker. Depois de desenvolver e testar completamente os scripts, você pode integrar ou invocar os arquivos de script do recurso de script de implantação. Para obter mais informações, consulte Configurar ambientes de desenvolvimento de script.

Salve o script em um arquivo inlineScript.bicep e implante o recurso usando o seguinte script:

$resourceGroupName = Read-Host -Prompt "Enter the name of the resource group to be created"
$location = Read-Host -Prompt "Enter the location (i.e. centralus)"

New-AzResourceGroup -Name $resourceGroupName -Location $location

New-AzResourceGroupDeployment -ResourceGroupName $resourceGroupName -TemplateFile "inlineScript.bicep"

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

Usar identidade gerenciada

O exemplo a seguir demonstra como usar a identidade gerenciada para interagir com o Azure de dentro do script de implantação.

@description('The location of the resources.')
param location string = resourceGroup().location

@description('The storage account to list blobs from.')
param storageAccountData {
  name: string
  container: string
}

@description('The role id of Storage Blob Data Reader.')
var storageBlobDataReaderRoleId = '2a2b9908-6ea1-4ae2-8e65-a410df84e7d1'

@description('The storage account to read blobs from.')
resource storageAccount 'Microsoft.Storage/storageAccounts@2023-04-01' existing = {
  name: storageAccountData.name
}

@description('The Storage Blob Data Reader Role definition from [Built In Roles](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles).')
resource storageBlobDataReaderRoleDef 'Microsoft.Authorization/roleDefinitions@2022-05-01-preview' existing = {
  scope: subscription()
  name: storageBlobDataReaderRoleId
}

@description('The user identity for the deployment script.')
resource scriptIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-07-31-preview' = {
  name: 'script-identity'
  location: location
}

@description('Assign permission for the deployment scripts user identity access to the read blobs from the storage account.')
resource dataReaderRoleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  scope: storageAccount
  name: guid(storageBlobDataReaderRoleDef.id, scriptIdentity.id, storageAccount.id)
  properties: {
    principalType: 'ServicePrincipal'
    principalId: scriptIdentity.properties.principalId
    roleDefinitionId: storageBlobDataReaderRoleDef.id
  }
}

@description('The deployment script.')
resource script 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'script'
  location: location
  kind: 'AzureCLI'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${scriptIdentity.id}': {}
    }
  }
  properties: {
    azCliVersion: '2.59.0'
    retentionInterval: 'PT1H'
    arguments: '${storageAccount.properties.primaryEndpoints.blob} ${storageAccountData.container}'
    scriptContent: '''
      #!/bin/bash
      set -e
      az storage blob list --auth-mode login --blob-endpoint $1 --container-name $2
    '''
  }
}

Monitorar e solucionar problemas de um script de implantação

Ao implantar um recurso de script de implantação, você precisa de uma conta de armazenamento para armazenar o script do usuário, os resultados da execução e o arquivo stdout. Você pode especificar a sua conta de armazenamento. Para obter mais informações, consulte Usar uma conta de armazenamento existente.

Uma alternativa para especificar sua própria conta de armazenamento envolve a configuração cleanupPreference para OnExpiration. Em seguida, você configura retentionInterval por uma duração que permite tempo suficiente para revisar as saídas antes que a conta de armazenamento seja removida. Para obter mais informações, consulte Limpar recursos de script de implantação.

Adicione a propriedade cleanupPreference ao arquivo Bicep anterior e defina o valor como OnExpiration. O valor padrão é Always. Além disso, defina rentalInterval como PT1H (uma hora) ou menor.

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlineCLI'
  location: location
  kind: 'AzureCLI'
  properties: {
    azCliVersion: '2.52.0'
    arguments: name
    scriptContent: 'echo "The argument is ${name}."; jq -n -c --arg st "Hello ${name}" \'{"text": $st}\' > $AZ_SCRIPTS_OUTPUT_PATH'
    cleanupPreference: 'OnExpiration'
    retentionInterval: 'PT1H'
  }
}

output text string = deploymentScript.properties.outputs.text

Depois de implantar o arquivo Bicep com êxito, use o portal do Azure, a CLI do Azure, o Azure PowerShell ou a API REST para verificar os resultados.

Portal do Azure

Depois de implantar um recurso de script de implantação, o recurso é listado no grupo de recursos no portal do Azure. A página de Visão geral lista os dois recursos de suporte, além do recurso de script de implantação. Os recursos de suporte serão excluídos depois que o intervalo de retenção expirar.

Observe que ambos os recursos de suporte têm o sufixo azscripts em seus nomes porque esses recursos são criados automaticamente. A outra maneira de identificar os recursos de suporte é usando marcas.

Captura de tela de um grupo de recursos de script de implantação.

Selecione o recurso de script de implantação na lista. A página Visão geral de um recurso de script de implantação exibe informações importantes sobre o recurso, como o Estado de provisionamento e os dois recursos de suporte (conta de armazenamento e instância de contêiner). A área Logs mostra o texto de impressão do script.

Captura de tela das informações sobre um recurso de script de implantação.

Selecione Saídas para exibir saídas do script.

Captura de tela das saídas de script de implantação.

Volte para o grupo de recursos, selecione a conta de armazenamento, selecione Compartilhamentos de arquivos e selecione o compartilhamento de arquivos com azscripts anexados ao nome do compartilhamento. Duas pastas aparecem na lista: azscriptinput e azscriptoutput. A pasta de saída contém um arquivo executionresult.json e o arquivo de saída de script. O arquivo executionresult.json contém a mensagem de erro de execução de script. O arquivo de saída é criado somente quando você executa o script com êxito.

Captura de tela do conteúdo da pasta de saída de um script de implantação.

A pasta de entrada contém o arquivo de script do sistema e o arquivo de script de implantação do usuário. Você pode substituir o arquivo de script de implantação do usuário por um revisado e executar novamente o script de implantação da instância de contêiner do Azure.

CLI do Azure

Você pode usar a CLI do Azure para gerenciar scripts de implantação no escopo da assinatura ou do grupo de recursos:

A saída do comando de lista é semelhante a este exemplo:

{
  "arguments": "John Dole",
  "azCliVersion": "2.52.0",
  "cleanupPreference": "OnExpiration",
  "containerSettings": {
    "containerGroupName": null
  },
  "environmentVariables": null,
  "forceUpdateTag": null,
  "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
  "identity": null,
  "kind": "AzureCLI",
  "location": "centralus",
  "name": "inlineCLI",
  "outputs": {
    "text": "Hello John Dole"
  },
  "primaryScriptUri": null,
  "provisioningState": "Succeeded",
  "resourceGroup": "dsDemo",
  "retentionInterval": "1:00:00",
  "scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
  "status": {
    "containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
    "endTime": "2023-12-11T20:20:12.149468+00:00",
    "error": null,
    "expirationTime": "2023-12-11T21:20:12.149468+00:00",
    "startTime": "2023-12-11T20:18:26.674492+00:00",
    "storageAccountId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
  },
  "storageAccountSettings": null,
  "supportingScriptUris": null,
  "systemData": {
    "createdAt": "2023-12-11T19:45:32.239063+00:00",
    "createdBy": "johndole@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
    "lastModifiedBy": "johndole@contoso.com",
    "lastModifiedByType": "User"
  },
  "tags": null,
  "timeout": "1 day, 0:00:00",
  "type": "Microsoft.Resources/deploymentScripts"
}

PowerShell do Azure

Você pode usar o Azure PowerShell para gerenciar scripts de implantação no escopo da assinatura ou do grupo de recursos:

A saída Get-AzDeploymentScript é semelhante a este exemplo:

Name                : inlinePS
Id                  : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlinePS
ResourceGroupName   : dsDemo
Location            : centralus
SubscriptionId      : 01234567-89AB-CDEF-0123-456789ABCDEF
ProvisioningState   : Succeeded
Identity            :
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 10.0
StartTime           : 12/11/2023 9:45:50 PM
EndTime             : 12/11/2023 9:46:59 PM
ExpirationDate      : 12/11/2023 10:46:59 PM
CleanupPreference   : OnExpiration
StorageAccountId    : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/ee5o4rmoo6ilmazscripts
ContainerInstanceId : /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/ee5o4rmoo6ilmazscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole.

RetentionInterval   : PT1H
Timeout             : P1D

API REST

Você pode usar a API REST para obter informações sobre o recurso de script de implantação no nível do grupo de recursos e no nível da assinatura:

/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

O exemplo a seguir usa ARMClient. O ARMClient não é uma ferramenta com suporte da Microsoft.

armclient login
armclient get /subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

A saída é semelhante a este exemplo:

{
  "kind": "AzureCLI",
  "identity": null,
  "location": "centralus",
  "systemData": {
    "createdAt": "2023-12-11T19:45:32.239063+00:00",
    "createdBy": "johndole@contoso.com",
    "createdByType": "User",
    "lastModifiedAt": "2023-12-11T20:18:26.183565+00:00",
    "lastModifiedBy": "johndole@contoso.com",
    "lastModifiedByType": "User"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "azCliVersion": "2.52.0",
    "scriptContent": "echo \"The argument is John Dole.\"; jq -n -c --arg st \"Hello John Dole\" '{\"text\": $st}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "arguments": "John Dole",
    "retentionInterval": "1:00:00",
    "timeout": "1 day, 0:00:00",
    "containerSettings": {
      "containerGroupName": null
    },
    "status": {
      "containerInstanceId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.ContainerInstance/containerGroups/jgczqtxom5oreazscripts",
      "endTime": "2023-12-11T20:20:12.149468+00:00",
      "error": null,
      "expirationTime": "2023-12-11T21:20:12.149468+00:00",
      "startTime": "2023-12-11T20:18:26.674492+00:00",
      "storageAccountId": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/01234567-89AB-CDEF-0123-456789ABCDEF/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "inlineCLI",
}

A API REST a seguir retorna o log:

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

Ele funciona somente antes que os recursos de script de implantação sejam excluídos.


Códigos de erro de script de implantação

A tabela a seguir lista os códigos de erro para o script de implantação:

Código do erro Descrição
DeploymentScriptInvalidOperation A definição de recurso de script de implantação no arquivo Bicep contém nomes de propriedade inválidos.
DeploymentScriptResourceConflict Você não poderá excluir um recurso de script de implantação se ele estiver em um estado não terminal e a execução não tiver excedido uma hora. Ou você não pode executar novamente o mesmo script de implantação com o mesmo identificador de recurso (mesma assinatura, nome do grupo de recursos e nome do recurso), mas conteúdo do corpo do script diferente ao mesmo tempo.
DeploymentScriptOperationFailed A operação de script de implantação falhou internamente. Entre em contato com o Suporte da Microsoft.
DeploymentScriptStorageAccountAccessKeyNotSpecified A chave de acesso não foi especificada para a conta de armazenamento existente.
DeploymentScriptContainerGroupContainsInvalidContainers Um grupo de contêineres que o serviço de script de implantação criou foi modificado externamente e contêineres inválidos foram adicionados.
DeploymentScriptContainerGroupInNonterminalState Dois ou mais recursos de script de implantação usam o mesmo nome de instância de contêiner do Azure no mesmo grupo de recursos e um deles ainda não terminou sua execução.
DeploymentScriptExistingStorageNotInSameSubscriptionAsDeploymentScript O armazenamento existente fornecido na implantação não é encontrado na assinatura em que o script está sendo implantado.
DeploymentScriptStorageAccountInvalidKind A conta de armazenamento existente do tipo BlobBlobStorage ou BlobStorage não dá suporte a compartilhamentos de arquivos e não pode ser usada.
DeploymentScriptStorageAccountInvalidKindAndSku A conta de armazenamento existente não dá suporte a compartilhamentos de arquivos. Para obter uma lista de tipos de contas de armazenamento com suporte, consulte Usar uma conta de armazenamento existente.
DeploymentScriptStorageAccountNotFound A conta de armazenamento não existe ou um processo externo ou uma ferramenta a excluiu.
DeploymentScriptStorageAccountWithServiceEndpointEnabled A conta de armazenamento especificada tem um ponto de extremidade de serviço. Não há suporte para uma conta de armazenamento com um ponto de extremidade de serviço.
DeploymentScriptStorageAccountInvalidAccessKey Uma chave de acesso inválida foi especificada para a conta de armazenamento existente.
DeploymentScriptStorageAccountInvalidAccessKeyFormat A chave da conta de armazenamento tem um formato inválido. Veja Gerenciar chaves de acesso da conta de armazenamento.
DeploymentScriptExceededMaxAllowedTime O tempo de execução do script de implantação excedeu o valor de tempo limite especificado na definição de recurso do script de implantação.
DeploymentScriptInvalidOutputs A saída do script de implantação não é um objeto JSON válido.
DeploymentScriptContainerInstancesServiceLoginFailure A identidade gerenciada atribuída pelo usuário não pôde entrar após 10 tentativas com intervalos de um minuto.
DeploymentScriptContainerGroupNotFound Uma ferramenta ou processo externo excluiu um grupo de contêineres que o serviço de script de implantação criou.
DeploymentScriptDownloadFailure Falha no download de um script de suporte. Consulte Usar scripts de suporte.
DeploymentScriptError O script de usuário gerou um erro.
DeploymentScriptBootstrapScriptExecutionFailed O script de inicialização gerou um erro. O script de inicialização é o script do sistema que orquestra a execução do script de implantação.
DeploymentScriptExecutionFailed Erro desconhecido durante a execução do script de implantação.
DeploymentScriptContainerInstancesServiceUnavailable Durante a criação de uma instância de contêiner, o serviço Instâncias de Contêiner do Azure gerou um erro de "serviço indisponível".
DeploymentScriptContainerGroupInNonterminalState Durante a criação de uma instância de contêiner, outro script de implantação estava usando o mesmo nome de instância de contêiner no mesmo escopo (mesma assinatura, nome do grupo de recursos e nome do recurso).
DeploymentScriptContainerGroupNameInvalid O nome da instância de contêiner especificado não atende aos requisitos das Instâncias de Contêiner do Azure. Consulte Solucionar problemas comuns nas Instâncias de Contêiner do Azure.

Acessar uma rede virtual privada

Você pode executar scripts de implantação em redes privadas com algumas configurações adicionais. Para obter mais informações, consulte Acessar uma rede virtual privada.

Próximas etapas

Neste artigo, você aprendeu como usar os scripts de implantação. Para obter mais informações, consulte: