Usar scripts de implantação no Bicep

Você pode usar o recurso deploymentScripts para executar scripts em implantações do Bicep e revisar os resultados da execução. Esses scripts ajudam você a executar as seguintes etapas personalizadas:

• Adicione usuários a um diretório.
• Realizar operações no plano de dados; por exemplo, copiar blobs ou preencher 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. Os scripts de implantação do Azure PowerShell e da CLI do Azure no ambiente Linux são suportados no momento.
• 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 implementaçã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 & limites de cota para ACI e Produtos disponíveis por região.

O serviço de scripts de implementação cria dois recursos de suporte – uma conta de armazenamento e uma instância de contentor – para executar e resolver scripts. Os nomes destes recursos são gerados usando um hash determinístico do ID de recurso do script de implementação, com o sufixo azscripts adicionado (por exemplo, jgczqtxom5oreazscripts). Como resultado, execuções repetidas do mesmo script de implementação podem reutilizar a mesma conta de armazenamento.

Em casos raros, pode encontrar o erro "A conta de armazenamento nomeada-nome-conta-armazenamento <> já está ocupada." Isto ocorre normalmente quando uma conta de armazenamento criada por uma execução anterior do mesmo script de implementação não foi limpa com sucesso.

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 que o recurso de script de implantação execute uma conta de armazenamento e uma instância de contêiner do Azure. Para configurar os privilégios mínimos, atribua uma função personalizada com as seguintes propriedades ao principal de implementaçã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, adicione Microsoft.Storage/register/action e Microsoft.ContainerInstance/register/action.

• Principal do script de implantação: esta entidade é necessária somente se o script de implantação precisar autenticar-se no Azure e utilizar a CLI ou o PowerShell do Azure. Existem duas formas de especificar o principal do 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. Somente uma identidade gerenciada atribuída pelo usuário é suportada para a identity propriedade no momento. 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, em seguida, 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.

Uma função interna não é adaptada para configurar permissões de script de implantação no momento.

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

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '14.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      Write-Host 'The argument is {0}' -f $name
      $output = 'Hello {0}' -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    retentionInterval: 'PT1H'
  }
}

output result string = deploymentScript.properties.outputs.text

Para obter mais informações sobre como criar recursos de script de implantação, consulte Desenvolver um script de implantação no Bicep. Para criar scripts para o recurso de script de implantação, é recomendável estabelecer 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 o ambiente de desenvolvimento para scripts de implantação em arquivos Bicep.

Salve o script em um arquivo inlineScript.bicep e use os seguintes scripts para implantar o recurso:

$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@2025-06-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@2025-01-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 a sua própria conta de armazenamento envolve definir cleanupPreference para 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 do 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

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

resource deploymentScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'inlinePS'
  location: location
  kind: 'AzurePowerShell'
  properties: {
    azPowerShellVersion: '14.0'
    arguments: '-name ${name}'
    scriptContent: '''
      param([string] $name)
      Write-Output "The argument is {0}." -f $name
      $output = "Hello {0}." -f $name
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    '''
    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 é usar tags.

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, incluindo o estado de provisionamento e os dois recursos de suporte, conta de armazenamento e instância de contêiner. A área de Logs mostra o texto impresso do script.

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

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.

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:

• az deployment-scripts delete: eliminar um script de implementação.
• az deployment-scripts list: Liste todos os scripts de implantação.
• az deployment-scripts show: Obter um script de implantação.
• az deployment-scripts show-log: Mostrar registos do script de implementação.

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:

• Get-AzDeploymentScript: Obtenha ou liste scripts de implantação.
• Get-AzDeploymentScriptLog: Obtenha o log de uma execução de script de implantação.
• Remove-AzDeploymentScript: Remova um script de implantação e seus recursos associados.
• Save-AzDeploymentScriptLog: Salve o log de execução de um script de implantação no disco.

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 : 14.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:

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 a partir de um script de implantação do Bicep 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 explorar os tópicos deste artigo, consulte:

• Desenvolver um script de implantação em Bicep
• Acessar uma rede virtual privada a partir de um script de implantação do Bicep
• Executar o script de implantação do Bicep de forma privada em um ponto de extremidade privado
• Configurar o ambiente de desenvolvimento para scripts de implementação nos ficheiros Bicep