Compartilhar via

Usar scripts de implantação em modelos do ARM

  • Artigo

Saiba como usar scripts de implantação em modelos do Azure Resource Manager (ARM). Com o recurso deploymentScripts, os usuários podem executar scripts em implantações do ARM e revisar resultados de execução.

Dica

Recomendamos o Bicep porque ele oferece as mesmas funcionalidades que os modelos do ARM e a sintaxe é mais fácil de usar. Para saber mais, confira os Scripts de implantação.

Esses scripts podem ser usados para executar etapas personalizadas, tais como:

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

Estes são os benefícios do script de implantação:

  • Fácil de codificar, usar e depurar. Você pode desenvolver scripts de implantação em seus ambientes de desenvolvimento preferidos. Os scripts podem ser inseridos em modelos ou 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 do CLI do Azure em ambiente Linux.
  • Permita a passagem de argumentos de linha de comando para o script.
  • É possível 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 a Instância de Contêiner do Azure está disponível. Consulte Disponibilidade de recursos para Instâncias de Contêiner do Azure nas regiões do Azure. Atualmente, o script de implantação usa somente redes públicas.

Importante

O serviço de script de implantação requer dois recursos de suporte para execução e solução de problemas de script: uma conta de armazenamento e uma instância de contêiner. Você pode especificar uma conta de armazenamento existente; caso contrário, o serviço de script criará uma para você. Os dois recursos de suporte criados automaticamente são geralmente excluídos pelo serviço de script quando a execução do script de implantação entra em um estado terminal. Você será cobrado pelos recursos de suporte até eles serem excluídos. Para obter as informações de preço, consulte os Preços de Instâncias de Contêiner e os Preços de Armazenamento do Azure. Para saber mais, consulte Limpar recursos do script de implantação.

Observação

A lógica de repetição para entrar no Azure agora está incorporada ao script de wrapper. Caso conceda permissões no mesmo modelo que seus scripts de implantação, o serviço de script de implantação tenta entrar por 10 minutos, com intervalo de 10 segundos, até que a atribuição de função de identidade gerenciada seja replicada.

Recursos de treinamento

Para saber mais sobre os scripts de implantação por meio de diretrizes passo a passo, consulte Estender modelos do ARM usando scripts de implantação.

Configurar as permissões mínimas

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

  • Entidade de implantação (a entidade usada para implantar o modelo): essa entidade de segurança é usada para criar 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 o Armazenamento do Azure e os provedores de recursos da instância de contêiner do Azure não tiverem sido registrados, você também precisará adicionar Microsoft.Storage/register/action e Microsoft.ContainerInstance/register/action.

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

    • Especificar uma identidade gerenciada atribuída pelo usuário na propriedade identity (consulte Modelos de exemplo). Quando especificado, 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. No momento, somente a identidade gerenciada atribuída pelo usuário tem suporte 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 seguro e, em seguida, poderá chamar Connect-AzAccount ou az login no script de implantação.

    Se for usada uma identidade gerenciada, a entidade de segurança da implantação precisará da função de Operador de identidade gerenciada (uma função interna) atribuída ao recurso de identidade gerenciada.

Modelos de exemplo

O JSON a seguir é um exemplo. Para obter mais informações, consulte o esquema de modelo mais recente.

{
  "type": "Microsoft.Resources/deploymentScripts",
  "apiVersion": "2020-10-01",
  "name": "runPowerShellInline",
  "location": "[resourceGroup().location]",
  "tags": {
    "tagName1": "tagValue1",
    "tagName2": "tagValue2"
  },
  "kind": "AzurePowerShell", // or "AzureCLI"
  "identity": {
    "type": "userAssigned",
    "userAssignedIdentities": {
      "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myResourceGroup/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myID": {}
    }
  },
  "properties": {
    "forceUpdateTag": "1",
    "containerSettings": {
      "containerGroupName": "mycustomaci"
    },
    "storageAccountSettings": {
      "storageAccountName": "myStorageAccount",
      "storageAccountKey": "myKey"
    },
    "azPowerShellVersion": "9.7",  // or "azCliVersion": "2.47.0",
    "arguments": "-name \\\"John Dole\\\"",
    "environmentVariables": [
      {
        "name": "UserName",
        "value": "jdole"
      },
      {
        "name": "Password",
        "secureValue": "jDolePassword"
      }
    ],
    "scriptContent": "
      param([string] $name)
      $output = 'Hello {0}. The username is {1}, the password is {2}.' -f $name,${Env:UserName},${Env:Password}
      Write-Output $output
      $DeploymentScriptOutputs = @{}
      $DeploymentScriptOutputs['text'] = $output
    ", // or "primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",
    "supportingScriptUris":[],
    "timeout": "PT30M",
    "cleanupPreference": "OnSuccess",
    "retentionInterval": "P1D"
  }
}

Observação

O exemplo é para fins de demonstração. As propriedades scriptContent e primaryScriptUri não podem coexistir em um modelo.

Observação

O scriptContent mostra um script com várias linhas. O portal do Azure e o pipeline do Azure DevOps não podem analisar um script de implantação com várias linhas. Você pode encadear os comandos do PowerShell (usando ponto e vírgula ou \r\n ou \n) em uma linha ou usar a propriedade primaryScriptUri com um arquivo de script externo. Há muitas ferramentas de escape/sem escape de cadeia de caracteres JSON gratuitas disponíveis. Por exemplo, https://www.freeformatter.com/json-escape.html.

Detalhes do valor da propriedade:

  • identity: Para a API de script de implantação versão 2020-10-01 ou posterior, uma identidade gerenciada atribuída pelo usuário é opcional, a menos que você precise executar ações específicas do Azure no script. Para a versão de API 2019-10-01 (prévia), uma identidade gerenciada é necessária, pois o serviço de script de implantação a utiliza para executar os scripts. Quando a propriedade de identidade é especificada, o serviço de script chama Connect-AzAccount -Identity antes de invocar o script de usuário. No momento, somente há suporte para a identidade gerenciada atribuída pelo usuário. Para fazer logon com uma identidade diferente, você pode chamar o Connect-AzAccount no script.

  • tags: Marcas do script de implantação. Se o serviço de script de implantação gerar uma conta de armazenamento e uma instância de contêiner, as marcas serão passadas para ambos os recursos, que podem ser utilizados para identificá-los. Outra maneira de identificar esses recursos é através de seus sufixos, que contêm "azscripts". Para obter mais informações, confira Monitorar e solucionar problemas de scripts de implantação.

  • kind: especifica o tipo de script. No momento, os scripts do Azure PowerShell e da CLI do Azure são suportados. Os valores são AzurePowerShell e AzureCLI.

  • forceUpdateTag: Alterar esse valor entre implantações de modelo força o script de implantação a ser executado novamente. Se você usar as funções newGuid() ou utcNow(), ambas as funções só poderão ser usadas no valor padrão para um parâmetro. Para saber mais, confira Executar script mais de uma vez.

  • containerSettings: Especifique as configurações para personalizar a Instância de Contêiner do Azure. O script de implantação requer uma nova instância de contêiner do Azure. Você não pode especificar uma instância de contêiner do Azure existente. No entanto, pode personalizar o nome do grupo de contêineres usando containerGroupName. Se não for especificado, o nome do grupo será gerado automaticamente.

  • storageAccountSettings: Especifique as configurações para usar uma conta de armazenamento existente. Se storageAccountName não for especificado, uma conta de armazenamento será criada automaticamente. Consulte Usar uma conta de armazenamento existente.

  • azPowerShellVersion/azCliVersion: Especifique a versão de módulo a ser usada. Consulte uma lista de versões do Azure PowerShell compatíveis. A versão determina qual imagem de contêiner deve ser usada:

    • As versões do Az iguais ou superiores a 9 usam o Ubuntu 22.04.
    • As versões do Az iguais ou superiores a 6 mas inferiores a 9 usam o Ubuntu 20.04.
    • As versões do Az inferiores a 6 usam o Ubuntu 18.04.

    Importante

    É aconselhável fazer o upgrade para a versão mais recente do Ubuntu, já que o Ubuntu 18.04 está se aproximando do fim de sua vida útil e não receberá mais atualizações de segurança após 31 de maio de 2023.

    Consulte uma lista de versões da CLI do Azure compatíveis.

    Importante

    O script de implantação usa as imagens da CLI disponíveis no Microsoft Container Registry (MCR). A certificação de uma imagem da CLI para o script de implantação costuma levar cerca de um mês. Não use as versões da CLI que foram lançadas dentro de 30 dias. Para localizar as datas de lançamento das imagens, consulte as notas de versão da CLI do Azure. Se for usada uma versão não compatível, a mensagem de erro listará as versões compatíveis.

  • arguments: Especifique os valores de parâmetro. os valores são separados por espaços.

    Os scripts de implantação dividem os argumentos em uma matriz de cadeias de caracteres invocando a chamada do sistema CommandLineToArgvW. Essa etapa é necessária porque os argumentos são passados como uma propriedade de comando para a instância de contêiner do Azure e a propriedade de comando é uma matriz de cadeia de caracteres.

    Se os argumentos contiverem caracteres de escape, use JsonEscaper para dobrar o escape dos caracteres. Cole a cadeia de caracteres de escape original na ferramenta e selecione Escape. A ferramenta gera uma cadeia de caracteres de escape duplo. Por exemplo, no modelo de amostra anterior, o argumento é -name \"John Dole\". A cadeia de caracteres de escape é -name \\\"John Dole\\\".

    Para passar um parâmetro de modelo ARM do tipo object como um argumento, converta o objeto em uma cadeia de caracteres usando a função string() e, em seguida, use a função replace() para substituir qualquer \" em \\\". Por exemplo:

    replace(string(parameters('tables')), '\"', '\\\"')

    Para obter mais informações, consulte o modelo de amostra.

  • environmentVariables: Especifique as variáveis de ambiente a serem passadas para o script. Para obter mais informações, consulte Desenvolver scripts de implantação.

  • scriptContent: especifique o conteúdo do script. Para executar um script externo, use primaryScriptUri. Para mais exemplos, consulte Usar script embutido e Usar script externo.

  • primaryScriptUri: Especifique uma URL acessível publicamente para o script de implantação primário com extensões de arquivo compatíveis. Para obter mais informações, consulte Usar scripts externos.

  • supportingScriptUris: Especifique uma matriz de URLs acessíveis publicamente para dar suporte a arquivos que são chamados em scriptContent ou primaryScriptUri. Para obter mais informações, consulte Usar scripts externos.

  • timeout: especifique o tempo de execução máximo permitido do script especificado no formato ISO 8601. O valor padrão é P1D.

  • cleanupPreference. Especifique a preferência de limpar os dois recursos de implantação de suporte, a conta de armazenamento e a instância de contêiner quando a execução do script estiver em estado terminal. A configuração padrão é Always, o que significa a exclusão dos recursos de suporte apesar do estado terminal (Êxito, Falha, Cancelado). Para saber mais, confira Limpar recursos do script de implantação.

  • retentionInterval: especifica o intervalo para o qual o serviço retém o recurso de script de implantação depois que a execução do script de implantação atingir um estado terminal. O recurso do script de implantação é excluído quando essa duração expira. A duração é baseada na norma ISO 8601. O intervalo de retenção está entre 1 e 26 horas (PT26H). Essa propriedade é usada quando cleanupPreference está configurado como OnExpiration. Para saber mais, confira Limpar recursos do script de implantação.

Mais exemplos

  • Amostra 1: crie um cofre de chaves e use o script de implantação para atribuir um certificado ao cofre de chaves.
  • Amostra 2: crie um grupo de recursos no nível da assinatura, crie um cofre de chaves no grupo de recursos e, em seguida, use o script de implantação para atribuir um certificado ao cofre de chaves.
  • Amostra 3: crie uma identidade gerenciada atribuída pelo usuário, atribua a função de colaborador à identidade no nível do grupo de recursos, crie um cofre de chaves e use o script de implantação para atribuir um certificado ao cofre de chaves.
  • Exemplo 4: é o mesmo cenário do Exemplo 1 nesta lista. Um novo grupo de recursos é criado para executar o script de implantação. Este modelo é um modelo de nível de assinatura.
  • Exemplo 5: é o mesmo cenário do Exemplo 4. Este é um modelo de nível de grupo de recursos.
  • Exemplo 6: crie manualmente uma identidade gerenciada atribuída pelo usuário e atribua-a permissão para usar a API do Microsoft Graph para criar aplicativos do Microsoft Entra. No arquivo Bicep, use um script de implantação para criar um aplicativo e uma entidade de serviço do Microsoft Entra e gere as IDs do objeto e a ID do cliente.

Usar scripts embutidos

O modelo a seguir tem um recurso definido com o tipo Microsoft.Resources/deploymentScripts. A parte realçada é o script embutido.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "\\\"John Dole\\\""
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runPowerShellInlineWithOutput",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "scriptContent": "
          param([string] $name)
          $output = \"Hello {0}\" -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "arguments": "[concat('-name', ' ', parameters('name'))]",
        "timeout": "PT1H",
        "cleanupPreference": "OnSuccess",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('runPowerShellInlineWithOutput').outputs.text]",
      "type": "string"
    }
  }
}

Observação

Como os scripts de implantação embutidos são colocados entre aspas duplas, as cadeias de caracteres dentro dos scripts de implantação precisam de escape usando uma barra invertida (\) ou ser colocadas entre aspas simples. Você também pode considerar usar a substituição de cadeia de caracteres, como mostrado no exemplo de JSON anterior.

O script usa um parâmetro e a saída do valor do parâmetro. DeploymentScriptOutputs é usado para armazenar saídas. Na seção de saídas, a linha de value mostra como acessar os valores armazenados. Write-Output é usado para fins de depuração. Para saber como acessar o arquivo de saída, consulte Monitorar e solucionar problemas em scripts de implantação. Para obter as descrições de propriedade, consulte Modelos de exemplo.

Para executar o script, selecione Experimentar para abrir o Cloud Shell, e cole o código a seguir no painel do Shell.

$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 -TemplateUri "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.json"

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

A saída se parece com isso:

Captura de tela da saída mundial do script de implantação do modelo do Resource Manager.

Usar scripts externos

Além dos scripts embutidos, você também pode usar arquivos de script externos. Há suporte somente para scripts primários do PowerShell com a extensão de arquivo ps1. Para os scripts da CLI, os scripts principais podem ter qualquer extensão (ou nenhuma extensão), desde que os scripts sejam scripts bash válidos. Para usar arquivos de script externos, substitua scriptContent por primaryScriptUri. Por exemplo:

"primaryScriptUri": "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/deploymentscript-helloworld.ps1",

Para obter mais informações, consulte o modelo de exemplo.

Os arquivos de scripts externos devem estar acessíveis. Para proteger os arquivos de script armazenados nas contas de armazenamento do Azure, gere um token SAS e inclua-o no URI para o modelo. Defina a hora de vencimento de forma a permitir que haja tempo suficiente para concluir a implantação. Para obter mais informações, consulte Implantar modelo do ARM particular com token SAS.

Você é responsável por garantir a integridade dos scripts referenciados pelo script de implantação, seja primaryScriptUri ou supportingScriptUris. Referencie somente scripts nos quais você confia.

Usar scripts de suporte

Você pode separar as lógicas complicadas em um ou mais arquivos de script de suporte. Se necessário, a propriedade supportingScriptUris permite que você forneça uma matriz de URIs para os arquivos de script de suporte:

"scriptContent": "
    ...
    ./Create-Cert.ps1
    ...
"

"supportingScriptUris": [
  "https://raw.githubusercontent.com/Azure/azure-docs-json-samples/master/deployment-script/create-cert.ps1"
],

Os arquivos de script de suporte podem ser chamados de scripts embutidos e arquivos de script primários. Os arquivos de script de suporte não têm restrições sobre a extensão do arquivo.

Os arquivos de suporte são copiados para azscripts/azscriptinput durante o tempo de execução. Use o caminho relativo para referenciar os arquivos de suporte de scripts embutidos e os arquivos de script primários.

Trabalhar com saídas de scripts do PowerShell

O modelo a seguir mostra como passar valores entre dois recursos do deploymentScripts:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "name": {
      "type": "string",
      "defaultValue": "John Dole"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate1",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-name', ' ', concat('\\\"', parameters('name'), '\\\"'))]",
        "scriptContent": "
          param([string] $name)
          $output = 'Hello {0}' -f $name
          Write-Output $output
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $output
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    },
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "scriptInTemplate2",
      "location": "[resourceGroup().location]",
      "kind": "AzurePowerShell",
      "dependsOn": [
        "scriptInTemplate1"
      ],
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azPowerShellVersion": "8.3",
        "timeout": "PT1H",
        "arguments": "[concat('-textToEcho', ' ', concat('\\\"', reference('scriptInTemplate1').outputs.text, '\\\"'))]",
        "scriptContent": "
          param([string] $textToEcho)
          Write-Output $textToEcho
          $DeploymentScriptOutputs = @{}
          $DeploymentScriptOutputs['text'] = $textToEcho
        ",
        "cleanupPreference": "Always",
        "retentionInterval": "P1D"
      }
    }
  ],
  "outputs": {
    "result": {
      "value": "[reference('scriptInTemplate2').outputs.text]",
      "type": "string"
    }
  }
}

No primeiro recurso, você define uma variável chamada $DeploymentScriptOutputs e a usa para armazenar os valores de saída. Para acessar o valor de saída de outro recurso dentro do modelo, use:

reference('<ResourceName>').outputs.text

Trabalhar com saídas de scripts da CLI

Ao contrário dos scripts de implantação do Azure PowerShell, a CLI/bash não expõe uma variável comum para armazenar saídas de script. Em vez disso, utiliza uma variável de ambiente nomeada AZ_SCRIPTS_OUTPUT_PATH para indicar o local do arquivo de saídas de script. Ao executar um script de implantação em um modelo do ARM, o shell do Bash configurará automaticamente essa variável de ambiente para você. Seu valor predefinido é estabelecido como /mnt/azscripts/azscriptoutput/scriptoutputs.json. As saídas são necessárias para estar em conformidade com uma estrutura de objeto de cadeia de caracteres JSON válida. O conteúdo do arquivo deve ser formatado como um par chave-valor. Por exemplo, uma matriz de cadeias de caracteres deve ser salva como { "MyResult": [ "foo", "bar"] }. Armazenar apenas os resultados da matriz, como [ "foo", "bar" ], é considerado inválido.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "identity": {
      "type": "string"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2020-10-01",
      "name": "runBashWithOutputs",
      "location": "[resourceGroup().location]",
      "kind": "AzureCLI",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "[parameters('identity')]": {
          }
        }
      },
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "AzCliVersion": "2.40.0",
        "timeout": "PT30M",
        "arguments": "'foo' 'bar'",
        "environmentVariables": [
          {
            "name": "UserName",
            "value": "jdole"
          },
          {
            "name": "Password",
            "secureValue": "jDolePassword"
          }
        ],
        "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo \"arg2 is: $2\"; echo \"Username is: $UserName\"; echo \"password is: $Password\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
        "cleanupPreference": "OnExpiration",
        "retentionInterval": "P1D"

jq foi usado no exemplo anterior. Ele vem com as imagens de contêiner. Consulte Configurar o ambiente de desenvolvimento.

Usar conta de armazenamento existente

Uma conta de armazenamento e uma instância de contêiner são necessárias para executar o script e solucionar problemas. Você tem as opções necessárias para especificar uma conta de armazenamento existente, caso contrário, o serviço de script criará automaticamente a conta de armazenamento junto com a instância de contêiner. Estes são os requisitos para usar uma conta de armazenamento existente:

  • Os tipos de conta de armazenamento compatíveis são:

    SKU Tipo compatível
    Premium_LRS FileStorage
    Premium_ZRS FileStorage
    Standard_GRS Storage, StorageV2
    Standard_GZRS StorageV2
    Standard_LRS Storage, StorageV2
    Standard_RAGRS Storage, StorageV2
    Standard_RAGZRS StorageV2
    Standard_ZRS StorageV2

    Essas combinações são compatíveis com compartilhamentos de arquivos. Para obter mais informações, consulte Criar um compartilhamento de arquivo do Azure e Tipos de contas de armazenamento.

  • As regras de firewall da conta de armazenamento ainda não são compatíveis. Para saber mais, consulte Configurar Redes Virtuais e Firewalls de Armazenamento do Azure.

  • A entidade de segurança de implantação deve ter permissões para gerenciar a conta de armazenamento, que inclui ler, criar e excluir compartilhamentos de arquivos.

  • A propriedade allowSharedKeyAccess da conta de armazenamento deve ser definida como true. A única maneira de montar uma conta de armazenamento na Instância de Contêiner do Azure (ACI) é por meio de uma chave de acesso.

Para especificar uma conta de armazenamento existente, adicione o seguinte JSON ao elemento de propriedade de Microsoft.Resources/deploymentScripts:

"storageAccountSettings": {
  "storageAccountName": "myStorageAccount",
  "storageAccountKey": "myKey"
},

  • storageAccountName: especifique o nome da conta de armazenamento.

  • storageAccountKey: especifique uma das chaves da conta de armazenamento. Você pode usar a função listKeys() para recuperar a chave. Por exemplo:

    "storageAccountSettings": {
    "storageAccountName": "[variables('storageAccountName')]",
    "storageAccountKey": "[listKeys(resourceId('Microsoft.Storage/storageAccounts', variables('storageAccountName')), '2019-06-01').keys[0].value]"
}

Consulte Modelos de exemplo para obter um exemplo de definição completo de Microsoft.Resources/deploymentScripts.

Quando uma conta de armazenamento existente é usada, o serviço de script cria um compartilhamento de arquivos com um nome exclusivo. Consulte Limpar recursos de script de implantação para saber como o serviço de script limpa o compartilhamento de arquivos.

Desenvolver scripts pós-implantação

Lidar com erros intermináveis

Você pode controlar como o PowerShell responde a erros que não terminam usando a variável $ErrorActionPreference no seu script de implantação. Se a variável não for definida no seu script de implantação, o serviço de script utilizará o valor padrão Continuar.

O serviço de script define o estado de provisionamento de recursos como Falhou quando o script encontra um erro, apesar da configuração de $ErrorActionPreference.

Usar variáveis de ambiente

O script de implantação usa estas variáveis de ambiente:

Variável de ambiente Valor padrão Sistema reservado
AZ_SCRIPTS_AZURE_ENVIRONMENT AzureCloud N
AZ_SCRIPTS_CLEANUP_PREFERENCE OnExpiration N
AZ_SCRIPTS_OUTPUT_PATH <AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY>/<AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME> S
AZ_SCRIPTS_PATH_INPUT_DIRECTORY /mnt/azscripts/azscriptinput S
AZ_SCRIPTS_PATH_OUTPUT_DIRECTORY /mnt/azscripts/azscriptoutput S
AZ_SCRIPTS_PATH_USER_SCRIPT_FILE_NAME Azure PowerShell: userscript.ps1; Azure CLI: userscript.sh S
AZ_SCRIPTS_PATH_PRIMARY_SCRIPT_URI_FILE_NAME primaryscripturi.config S
AZ_SCRIPTS_PATH_SUPPORTING_SCRIPT_URI_FILE_NAME supportingscripturi.config S
AZ_SCRIPTS_PATH_SCRIPT_OUTPUT_FILE_NAME scriptoutputs.json S
AZ_SCRIPTS_PATH_EXECUTION_RESULTS_FILE_NAME executionresult.json S
AZ_SCRIPTS_USER_ASSIGNED_IDENTITY /subscriptions/ N

Para obter mais informações sobre como usar o AZ_SCRIPTS_OUTPUT_PATH, confira Trabalhar com saídas do script da CLI.

Passar cadeias de caracteres seguras para o script de implantação

Definir variáveis de ambiente (EnvironmentVariable) em suas instâncias de contêiner permite que você forneça a configuração dinâmica do aplicativo ou do script executado pelo contêiner. O script de implantação lida com variáveis de ambiente não seguras e protegidas da mesma maneira que a Instância de Contêiner do Azure. Para saber mais, consulte Definir variáveis de ambiente em instâncias de contêiner. Para obter um exemplo, consulte Modelos de amostra.

O tamanho máximo permitido para variáveis de ambiente é 64 KB.

Monitorar e solucionar problemas de scripts de implantação

O serviço de script cria uma conta de armazenamento (a menos que você especifique uma conta de armazenamento existente) e uma instância de contêiner para execução de script. Se esses recursos forem criados automaticamente pelo serviço de script, ambos os recursos terão o sufixo azscripts nos nomes dos recursos.

Captura de tela dos nomes de recursos do script de implantação de modelo do Resource Manager.

O script do usuário, os resultados da execução e o arquivo stdout são armazenados nos compartilhamentos de arquivos da conta de armazenamento. Há uma pasta chamada azscripts. Na pasta, há mais duas pastas para os arquivos de entrada e de saída: azscriptinput e azscriptoutput.

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 de execução do script em executionresult.json. O arquivo de saída é criado somente quando o script é executado com êxito. A pasta de entrada contém um arquivo de script do PowerShell do sistema e os arquivos de script da 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.

Use o 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 captura de tela a seguir mostra a página Visão geral de um recurso de script de implantação:

Captura de tela da visão geral do portal do script de implantação de modelo do Resource Manager.

A página de visão geral exibe algumas informações importantes do recurso, como Estado de provisionamento, Conta de armazenamento, Instância de contêiner e Logs.

No menu à esquerda, você pode exibir o conteúdo do script de implantação, os argumentos passados para o script e a saída. Você também pode exportar um modelo para o script de implantação, incluindo o script de implantação.

Usar o PowerShell

Usando o Azure PowerShell, você pode gerenciar scripts de implantação na assinatura ou no escopo do grupo de recursos:

A saída Get-AzDeploymentScript é semelhante a:

Name                : runPowerShellInlineWithOutput
Id                  : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput
ResourceGroupName   : myds0618rg
Location            : centralus
SubscriptionId      : aaaabbbb-0000-cccc-1111-dddd2222eeee
ProvisioningState   : Succeeded
Identity            : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mydentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami
ScriptKind          : AzurePowerShell
AzPowerShellVersion : 9.7
StartTime           : 5/11/2023 7:46:45 PM
EndTime             : 5/11/2023 7:49:45 PM
ExpirationDate      : 5/12/2023 7:49:45 PM
CleanupPreference   : OnSuccess
StorageAccountId    : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.Storage/storageAccounts/ftnlvo6rlrvo2azscripts
ContainerInstanceId : /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0618rg/providers/Microsoft.ContainerInstance/containerGroups/ftnlvo6rlrvo2azscripts
Outputs             :
                      Key                 Value
                      ==================  ==================
                      text                Hello John Dole

RetentionInterval   : P1D
Timeout             : PT1H

Usar a CLI do Azure

Usando a CLI do Azure, você pode gerenciar scripts de implantação na assinatura ou no escopo do grupo de recursos:

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

[
  {
    "arguments": "'foo' 'bar'",
    "azCliVersion": "2.40.0",
    "cleanupPreference": "OnExpiration",
    "containerSettings": {
      "containerGroupName": null
    },
    "environmentVariables": null,
    "forceUpdateTag": "20231101T163748Z",
    "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runBashWithOutputs",
    "identity": {
      "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
      "type": "userAssigned",
      "userAssignedIdentities": {
        "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myidentity/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
          "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
          "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
        }
      }
    },
    "kind": "AzureCLI",
    "location": "centralus",
    "name": "runBashWithOutputs",
    "outputs": {
      "Result": [
        {
          "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mytest/providers/Microsoft.KeyVault/vaults/mykv1027",
          "resourceGroup": "mytest"
        }
      ]
    },
    "primaryScriptUri": null,
    "provisioningState": "Succeeded",
    "resourceGroup": "mytest",
    "retentionInterval": "1 day, 0:00:00",
    "scriptContent": "result=$(az keyvault list); echo \"arg1 is: $1\"; echo $result | jq -c '{Result: map({id: .id})}' > $AZ_SCRIPTS_OUTPUT_PATH",
    "status": {
      "containerInstanceId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/mytest/providers/Microsoft.ContainerInstance/containerGroups/eg6n7wvuyxn7iazscripts",
      "endTime": "2023-11-01T16:39:12.080950+00:00",
      "error": null,
      "expirationTime": "2023-11-02T16:39:12.080950+00:00",
      "startTime": "2023-11-01T16:37:53.139700+00:00",
      "storageAccountId": null
    },
    "storageAccountSettings": {
      "storageAccountKey": null,
      "storageAccountName": "dsfruro267qwb4i"
    },
    "supportingScriptUris": null,
    "systemData": {
      "createdAt": "2023-10-31T19:06:57.060909+00:00",
      "createdBy": "someone@contoso.com",
      "createdByType": "User",
      "lastModifiedAt": "2023-11-01T16:37:51.859570+00:00",
      "lastModifiedBy": "someone@contoso.com",
      "lastModifiedByType": "User"
    },
    "tags": null,
    "timeout": "0:30:00",
    "type": "Microsoft.Resources/deploymentScripts"
  }
]

Usar a API REST

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

/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 login
armclient get /subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourcegroups/myrg/providers/microsoft.resources/deploymentScripts/myDeployementScript?api-version=2020-10-01

A saída deverá ser semelhante a:

{
  "kind": "AzurePowerShell",
  "identity": {
    "type": "userAssigned",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "userAssignedIdentities": {
      "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myidentity1008rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myuami": {
        "principalId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444"
      }
    }
  },
  "location": "centralus",
  "systemData": {
    "createdBy": "someone@contoso.com",
    "createdByType": "User",
    "createdAt": "2023-05-11T02:59:04.7501955Z",
    "lastModifiedBy": "someone@contoso.com",
    "lastModifiedByType": "User",
    "lastModifiedAt": "2023-05-11T02:59:04.7501955Z"
  },
  "properties": {
    "provisioningState": "Succeeded",
    "forceUpdateTag": "20220625T025902Z",
    "azPowerShellVersion": "9.7",
    "scriptContent": "\r\n          param([string] $name)\r\n          $output = \"Hello {0}\" -f $name\r\n          Write-Output $output\r\n          $DeploymentScriptOutputs = @{}\r\n          $DeploymentScriptOutputs['text'] = $output\r\n        ",
    "arguments": "-name \\\"John Dole\\\"",
    "retentionInterval": "P1D",
    "timeout": "PT1H",
    "containerSettings": {},
    "status": {
      "containerInstanceId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.ContainerInstance/containerGroups/64lxews2qfa5uazscripts",
      "storageAccountId": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Storage/storageAccounts/64lxews2qfa5uazscripts",
      "startTime": "2023-05-11T02:59:07.5951401Z",
      "endTime": "2023-05-11T03:00:16.7969234Z",
      "expirationTime": "2023-05-12T03:00:16.7969234Z"
    },
    "outputs": {
      "text": "Hello John Dole"
    },
    "cleanupPreference": "OnSuccess"
  },
  "id": "/subscriptions/aaaabbbb-0000-cccc-1111-dddd2222eeee/resourceGroups/myds0624rg/providers/Microsoft.Resources/deploymentScripts/runPowerShellInlineWithOutput",
  "type": "Microsoft.Resources/deploymentScripts",
  "name": "runPowerShellInlineWithOutput"
}

A API REST a seguir retorna o log:

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

Ele só funciona antes de os recursos de script de implantação serem excluídos.

Para ver o recurso deploymentScripts no portal, selecione Mostrar tipos ocultos:

Captura de tela do script de implantação de modelo do Resource Manager com a opção mostrar tipos ocultos no portal.

Limpar recursos do script de implantação

Os dois recursos de suporte criados automaticamente nunca poderão sobreviver ao recurso deploymentScript, a menos que haja falhas ao excluí-los. O ciclo de vida dos recursos de suporte é controlado pela propriedade cleanupPreference, o ciclo de vida do recurso deploymentScript é controlado pela propriedade retentionInterval:

  • cleanupPreference: especifica a preferência de limpeza dos dois recursos de suporte quando a execução do script entrar em estado terminal. Os valores com suporte são:

    • Always: exclui os dois recursos de suporte quando a execução do script entra em estado terminal. Se uma conta de armazenamento existente for usada, o serviço de script excluirá o compartilhamento de arquivos criado pelo serviço. Como o recurso deploymentScripts ainda pode estar presente depois que os recursos de suporte forem limpos, o serviço de script persiste os resultados da execução do script, por exemplo, stdout, saídas e valor retornado antes que os recursos sejam excluídos.

    • OnSuccess: exclui os dois recursos de suporte somente quando a execução do script é bem-sucedida. Se uma conta de armazenamento existente for usada, o serviço de script removerá o compartilhamento de arquivos somente quando a execução do script for bem-sucedida.

      Se a execução do script não for bem-sucedida, o serviço de script aguarda até que o retentionInterval expire antes de limpar os recursos de suporte e, em seguida, o recurso do script de implantação.

    • OnExpiration: exclui os dois recursos de suporte somente quando a configuração retentionInterval tiver expirado. Se uma conta de armazenamento existente for usada, o serviço de script removerá o compartilhamento de arquivo, mas manterá a conta de armazenamento.

    A instância de contêiner e a conta de armazenamento são excluídas de acordo com cleanupPreference. No entanto, se o script falhar e cleanupPreference não estiver definido como Sempre, o processo de implantação manterá automaticamente o contêiner em execução por uma hora ou até que o contêiner tenha sido limpo. Você pode usar esse tempo para solucionar o problema do script. Se você quiser manter o contêiner em execução após implantações bem-sucedidas, adicione uma etapa de suspensão ao seu script. Por exemplo, adicione Start-Sleep ao final do seu script. Se você não adicionar a etapa de suspensão, o contêiner será definido como um estado de terminal e não poderá ser acessado mesmo que ainda não tenha sido excluído.

  • retentionInterval: especifica o intervalo de tempo durante o qual um recurso deploymentScript será mantido e após o qual será expirado e excluído.

Observação

Não é recomendável usar a conta de armazenamento e a instância do contêiner geradas pelo serviço de script para outros fins. Os dois recursos podem ser removidos, dependendo do ciclo de vida do script.

A conta de armazenamento e a instância de contêiner criadas automaticamente não podem ser excluídas se o script de implantação for implantado em um grupo de recursos com um bloqueio CanNotDelete. Para resolver esse problema, você pode implantar o script de implantação em outro grupo de recursos sem bloqueios. Consulte Exemplo 4 e Exemplo 5 em Modelos de exemplo.

Executar script mais de uma vez

A execução do script de implantação é uma operação idempotente. Se nenhuma das propriedades de recurso deploymentScripts (incluindo o script embutido) for alterada, o script não será executado quando você reimplantar o modelo. O serviço de script de implantação compara os nomes de recursos no modelo com os recursos existentes no mesmo grupo de recursos. Há duas opções se você quiser executar o mesmo script de implantação várias vezes:

  • Altere o nome do seu recurso deploymentScripts. Por exemplo, use a função de modelo utcNow como o nome do recurso ou como parte do nome do recurso. Alterar o nome do recurso cria um novo recurso deploymentScripts. É bom para manter um histórico da execução do script.

    Observação

    Só é possível usar a função utcNow no valor padrão de um parâmetro.

  • Especifique um valor diferente na propriedade do modelo forceUpdateTag. Por exemplo, use utcNow como o valor.

Observação

Grave os scripts de implantação idempotentes. Isso garante que, se eles forem executados novamente por acidente, não causarão alterações no sistema. Por exemplo, se o script de implantação for usado para criar um recurso do Azure, verifique se o recurso não existe antes de criá-lo, para que o script seja bem-sucedido e você não tenha que criar o recurso novamente.

Configurar o ambiente de desenvolvimento

Você pode usar uma imagem de contêiner pré-configurada como seu ambiente de desenvolvimento de scripts de implantação. Para obter mais informações, consulte Configurar o ambiente de desenvolvimento para scripts de implantação em modelos.

Depois que o script for testado com êxito, você poderá usá-lo como um script de implantação nos seus modelos.

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

Código do erro Descrição
DeploymentScriptInvalidOperation A definição de recurso de script de implantação no modelo contém nomes de propriedade inválidos.
DeploymentScriptResourceConflict Não é possível excluir um recurso do script de implantação que esteja em estado não terminal e a execução não tenha excedido 1 hora. Ou não é possível 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 terminou sua execução.
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 compatíveis, consulte Usar conta de armazenamento existente.
DeploymentScriptStorageAccountNotFound A conta de armazenamento não existe ou foi excluída por um processo ou ferramenta externa.
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 Chave de acesso inválida especificada para a conta de armazenamento existente.
DeploymentScriptStorageAccountInvalidAccessKeyFormat Formato de chave da conta de armazenamento 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 conseguiu entrar após 10 tentativas com um intervalo de 1 minuto.
DeploymentScriptContainerGroupNotFound Um grupo de contêineres criado pelo serviço de script de implantação foi excluído por uma ferramenta ou processo externo.
DeploymentScriptDownloadFailure Falha ao baixar um script de suporte. Consulte Usar script 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 Ao criar a instância de contêiner do Azure (ACI), o ACI gerou um erro de serviço indisponível.
DeploymentScriptContainerGroupInNonterminalState Ao criar a instância de contêiner do Azure (ACI), outro script de implantação está usando o mesmo nome da ACI no mesmo escopo (mesma assinatura, nome do grupo de recursos e nome do recurso).
DeploymentScriptContainerGroupNameInvalid O nome da instância de contêiner do Azure (ACI) especificado não atende aos requisitos da ACI. Consulte Solucionar problemas comuns nas Instâncias de Contêiner do Azure.

Usar o Microsoft Graph em um script de implantação

Um script de implantação pode usar o Microsoft Graph para criar e trabalhar com objetos no Microsoft Entra ID.

Comandos

Ao usar scripts de implantação da CLI do Azure, você pode usar comandos dentro do grupo de comandos az ad para trabalhar com aplicativos, entidades de serviço, grupos e usuários. Você também pode invocar diretamente as APIs do Microsoft Graph usando o comando az rest.

Ao usar scripts de implantação do Azure PowerShell, você pode usar o cmdlet Invoke-RestMethod para invocar diretamente as APIs do Microsoft Graph.

Permissões

A identidade usada pelo script de implantação precisa estar autorizada a trabalhar com a API do Microsoft Graph, com as permissões apropriadas para as operações que executa. Você deve autorizar a identidade fora da implantação do modelo, por exemplo, pré-criando uma identidade gerenciada atribuída pelo usuário e atribuindo-lhe uma função de aplicativo do Microsoft Graph. Para obter mais informações, confira este exemplo de início rápido.

Acessar rede virtual privada

Com o Microsoft.Resources/deploymentScripts versão 2023-08-01, você pode executar scripts de implantação em redes privadas com algumas configurações adicionais.

  • Crie uma identidade gerenciada atribuída pelo usuário e especifique-a na propriedade identity. Para atribuir a identidade, consulte Identidade.

  • Crie uma conta de armazenamento com allowSharedKeyAccessdefinida comotrue e especifique o script de implantação para usar a conta de armazenamento existente. Para especificar uma conta de armazenamento existente, consulte Usar uma conta de armazenamento existente. Algumas configurações adicionais são necessárias para a conta de armazenamento.

    1. Abra a conta de armazenamento no portal do Azure.

    2. No menu à esquerda, selecione Controle de Acesso (IAM) e, então, selecione a guia Atribuições de função.

    3. Adicione a função Storage File Data Privileged Contributor à identidade gerenciada atribuída pelo usuário.

    4. No menu à esquerda, em Segurança + rede, selecione Rede e, em seguida, selecione Firewalls e redes virtuais.

    5. Selecione Habilitado a partir das redes virtuais e endereços IP selecionados.

      Captura de tela da configuração da conta de armazenamento para acessar a rede privada.

    6. Em Redes virtuais, adicione uma sub-rede. Na captura de tela, a sub-rede é chamada dspvnVnet.

    7. Em Exceções, selecione Permitir que os serviços do Azure na lista de serviços confiáveis acessem esta conta de armazenamento.

O modelo do ARM a seguir mostra como configurar o ambiente para executar um script de implantação:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string",
      "maxLength": 10
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "userAssignedIdentityName": {
      "type": "string",
      "defaultValue": "[format('{0}Identity', parameters('prefix'))]"
    },
    "storageAccountName": {
      "type": "string",
      "defaultValue": "[format('{0}stg{1}', parameters('prefix'), uniqueString(resourceGroup().id))]"
    },
    "vnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Vnet', parameters('prefix'))]"
    },
    "subnetName": {
      "type": "string",
      "defaultValue": "[format('{0}Subnet', parameters('prefix'))]"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Network/virtualNetworks",
      "apiVersion": "2023-09-01",
      "name": "[parameters('vnetName')]",
      "location": "[parameters('location')]",
      "properties": {
        "addressSpace": {
          "addressPrefixes": [
            "10.0.0.0/16"
          ]
        },
        "enableDdosProtection": false,
        "subnets": [
          {
            "name": "[parameters('subnetName')]",
            "properties": {
              "addressPrefix": "10.0.0.0/24",
              "serviceEndpoints": [
                {
                  "service": "Microsoft.Storage"
                }
              ],
              "delegations": [
                {
                  "name": "Microsoft.ContainerInstance.containerGroups",
                  "properties": {
                    "serviceName": "Microsoft.ContainerInstance/containerGroups"
                  }
                }
              ]
            }
          }
        ]
      }
    },
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2023-01-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "properties": {
        "networkAcls": {
          "bypass": "AzureServices",
          "virtualNetworkRules": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]",
              "action": "Allow",
              "state": "Succeeded"
            }
          ],
          "defaultAction": "Deny"
        },
        "allowSharedKeyAccess": true
      },
      "dependsOn": [
        "[resourceId('Microsoft.Network/virtualNetworks', parameters('vnetName'))]"
      ]
    },
    {
      "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
      "apiVersion": "2023-07-31-preview",
      "name": "[parameters('userAssignedIdentityName')]",
      "location": "[parameters('location')]"
    },
    {
      "type": "Microsoft.Authorization/roleAssignments",
      "apiVersion": "2022-04-01",
      "scope": "[format('Microsoft.Storage/storageAccounts/{0}', parameters('storageAccountName'))]",
      "name": "[guid(tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd'), resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName')))]",
      "properties": {
        "principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), '2023-07-31-preview').principalId]",
        "roleDefinitionId": "[tenantResourceId('Microsoft.Authorization/roleDefinitions', '69566ab7-960f-475b-8e7c-b3118f30c6bd')]",
        "principalType": "ServicePrincipal"
      },
      "dependsOn": [
        "[resourceId('Microsoft.Storage/storageAccounts', parameters('storageAccountName'))]",
        "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
      ]
    }
  ]
}

Você pode usar o seguinte modelo do ARM para testar a implantação:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "prefix": {
      "type": "string"
    },
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]"
    },
    "utcValue": {
      "type": "string",
      "defaultValue": "[utcNow()]"
    },
    "storageAccountName": {
      "type": "string"
    },
    "vnetName": {
      "type": "string"
    },
    "subnetName": {
      "type": "string"
    },
    "userAssignedIdentityName": {
      "type": "string"
    }
  },
  "resources": [
    {
      "type": "Microsoft.Resources/deploymentScripts",
      "apiVersion": "2023-08-01",
      "name": "[format('{0}DS', parameters('prefix'))]",
      "location": "[parameters('location')]",
      "identity": {
        "type": "userAssigned",
        "userAssignedIdentities": {
          "[format('{0}', resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')))]": {}
        }
      },
      "kind": "AzureCLI",
      "properties": {
        "forceUpdateTag": "[parameters('utcValue')]",
        "azCliVersion": "2.47.0",
        "storageAccountSettings": {
          "storageAccountName": "[parameters('storageAccountName')]"
        },
        "containerSettings": {
          "subnetIds": [
            {
              "id": "[resourceId('Microsoft.Network/virtualNetworks/subnets', parameters('vnetName'), parameters('subnetName'))]"
            }
          ]
        },
        "scriptContent": "echo \"Hello world!\"",
        "retentionInterval": "P1D",
        "cleanupPreference": "OnExpiration"
      }
    }
  ]
}

Próximas etapas

Neste artigo, você aprendeu como usar os scripts de implantação. Para percorrer um tutorial de script de implantação:

Tutorial: Usar scripts de implantação em modelos do Azure Resource Manager

Módulo do Learn: Estenda os modelos do ARM usando scripts de implantação