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
eMicrosoft.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 chamaConnect-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 propriedadeidentity
. 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.
- Especifique uma identidade gerenciada atribuída pelo usuário na propriedade
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.
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.
Selecione Saídas para exibir saídas do script.
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.
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: Excluir um script de implantação.
- az deployment-scripts list: Listar todos os scripts de implantação.
- az deployment-scripts show: Recuperar um script de implantação.
- az deployment-scripts show-log: Mostrar os logs de script de implantação.
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:
- Get-AzDeploymentScript: obtém ou lista scripts de implantação.
- Get-AzDeploymentScriptLog: obtém o log de uma execução de script de implantação.
- Remove-AzDeploymentScript: remove um script de implantação e seus recursos associados.
- Save-AzDeploymentScriptLog: salve o log de uma execução de script de implantação em disco.
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 suportada pela 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 onde 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 usando um ponto de extremidade de serviço ou Executar o script de implantação do Bicep de forma privada em um ponto de extremidade privado.
Próximas etapas
Neste artigo, você aprendeu como usar os scripts de implantação. Para obter mais informações, consulte:
- Módulo de treinamento: estender modelos do ARM usando scripts de implantação
- Desenvolver recursos de script de implantação
- Acesse uma rede virtual privada usando o ponto de extremidade de serviço
- Executar o script de implantação do Bicep de forma privada em um ponto de extremidade privado
- Criar ambientes de desenvolvimento de script