Partilhar via

Usar scripts de implantação no Bicep

  • Artigo

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

  • Adicione usuários a um diretório.
  • Realizar operações de plano de dados; Por exemplo, copie blobs ou semeie um banco de dados.
  • Procure e valide uma chave de licença.
  • Crie um certificado autoassinado.
  • Crie um objeto no Microsoft Entra ID.
  • Procure blocos de endereços IP a partir 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 favoritos. Os scripts podem ser incorporados 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 está disponível somente nas regiões onde as Instâncias de Contêiner do Azure estão disponíveis. Para obter mais informações, consulte Disponibilidade de recursos para instâncias de contêiner do Azure em 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. Geralmente, o serviço limpa esses recursos após a conclusão do script de implantação. Você incorre em cobranças por esses recursos até que eles sejam removidos.

Para obter informações sobre preços, consulte Preços de instâncias de contêiner e Preços do Armazenamento do Azure. Para saber mais, consulte Limpar recursos de script de implantação.

Recursos de formação

Se preferir saber mais sobre scripts de implantação por meio de orientação 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 do script de implantação ou posterior, duas entidades estão envolvidas na execução do script de implantação:

  • Entidade de implantação: essa entidade é usada para implantar o arquivo Bicep. Ele cria recursos subjacentes que são necessários para a execução do recurso de script de implantação — 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 Azure e das Instâncias de Contêiner do Azure não estiverem registrados, certifique-se de adicionar Microsoft.Storage/register/action e Microsoft.ContainerInstance/register/action.

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

    • Especifique uma identidade gerenciada atribuída pelo usuário na identity propriedade. (Consulte a sintaxe do recurso do 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, apenas uma identidade gerenciada atribuída pelo usuário é suportada para a identity propriedade. Para iniciar sessão com uma identidade diferente, utilize o segundo método nesta lista.
    • Passe as credenciais da entidade de serviço como variáveis de ambiente seguro 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 interna de Operador de Identidade Gerenciada atribuída ao recurso de identidade gerenciado.

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 string e cria outro string.

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, recomendamos 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 ..."

Utilizar a identidade gerida

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 de usuário, os resultados da execução e o stdout arquivo. Você pode especificar sua própria 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 como OnExpiration. Em seguida, você configura retentionInterval para 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 cleanupPreference propriedade ao arquivo Bicep anterior e defina o valor como OnExpiration. O valor predefinido é Always. Além disso, defina rentalInterval como PT1H (uma hora) ou menos.

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 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 tags.

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 de informações sobre um recurso de script de implantação.

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

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

Volte para o grupo de recursos, selecione a conta de armazenamento, selecione Compartilhamentos de arquivos e, em seguida, 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 de 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 list é semelhante a este exemplo:

{
  "arguments": "John Dole",
  "azCliVersion": "2.52.0",
  "cleanupPreference": "OnExpiration",
  "containerSettings": {
    "containerGroupName": null
  },
  "environmentVariables": null,
  "forceUpdateTag": null,
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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"
}

Azure PowerShell

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

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

Name                : inlinePS
Id                  : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlinePS
ResourceGroupName   : dsDemo
Location            : centralus
SubscriptionId      : aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/ee5o4rmoo6ilmazscripts
ContainerInstanceId : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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. ARMClient não é uma ferramenta da Microsoft suportada.

armclient login
armclient get /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Storage/storageAccounts/jgczqtxom5oreazscripts"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/dsDemo/providers/Microsoft.Resources/deploymentScripts/inlineCLI",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "inlineCLI",
}

A seguinte API REST 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 do 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 de erro Description
DeploymentScriptInvalidOperation A definição de recurso do script de implantação no arquivo Bicep contém nomes de propriedade inválidos.
DeploymentScriptResourceConflict Não é possível 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 de corpo de 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 criado pelo serviço de script de implantação 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 concluiu 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 BlobBlobStorage tipo ou BlobStorage não suporta compartilhamentos de arquivos e não pode ser usada.
DeploymentScriptStorageAccountInvalidKindAndSku A conta de armazenamento existente não suporta partilhas de ficheiros. Para obter uma lista dos tipos suportados de contas de armazenamento, consulte Usar uma conta de armazenamento existente.
DeploymentScriptStorageAccountNotFound A conta de armazenamento não existe ou um processo ou ferramenta externa 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. Consulte 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 criado pelo serviço de script de implantação.
DeploymentScriptDownloadFailure Falha no download de um script de suporte. Consulte Usar scripts de suporte.
DeploymentScriptError O script do usuário lançou um erro.
DeploymentScriptBootstrapScriptExecutionFailed O script de bootstrap lançou um erro. O script de bootstrap é o script do sistema que orquestra a execução do script de implantação.
DeploymentScriptExecutionFailed Ocorreu um erro desconhecido durante a execução do script de implementação.
DeploymentScriptContainerInstancesServiceUnavailable Durante a criação de uma instância de contêiner, o serviço de Instâncias de Contêiner do Azure lançou 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 de Instâncias de Contêiner do Azure. Consulte Solucionar problemas comuns em instâncias de contêiner do Azure.

Aceder a 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 usando o ponto de extremidade de serviço ou Executar script de implantação do Bicep de forma privada em um ponto de extremidade privado.

Próximos passos

Neste artigo, você aprendeu a usar scripts de implantação. Para saber mais, veja: