Como usar modelos de implantação do ARM (Azure Resource Manager) com a CLI do Azure

Este artigo explica como usar a CLI do Azure com modelos do ARM (Azure Resource Manager) para implantar recursos no Azure. Se você não estiver familiarizado com os conceitos de implantação e gerenciamento das soluções do Azure, confira Visão geral da implantação de modelos.

Os comandos de implantação foram alterados na CLI do Azure versão 2.2.0. Os exemplos neste artigo exigem a versão 2.20.0 ou posterior da CLI do Azure.

Para executar esta amostra, instale a última versão da CLI do Azure. Para iniciar, execute az login para criar uma conexão com o Azure.

As amostras da CLI do Azure são escritas para o shell bash. Para executar esta amostra no prompt de comando ou no Windows PowerShell, talvez você precise alterar os elementos do script.

Se você não tiver a CLI do Azure instalada, você pode usar o Azure Cloud Shell. Para obter mais informações, confira Implantar modelos ARM a partir do Azure Cloud Shell.

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 Como implantar recursos com o Bicep e a CLI do Azure.

Permissões necessárias

Para implantar um arquivo Bicep ou um modelo do ARM, você precisa de acesso de gravação nos recursos que está implantando e acesso a todas as operações no tipo de recurso Microsoft.Resources/implantações. Por exemplo, para implantar uma máquina virtual, você precisa Microsoft.Compute/virtualMachines/write e permissões Microsoft.Resources/deployments/*. A operação do teste de hipóteses tem os mesmos requisitos de permissão.

Para ver uma lista de funções e permissões, consulte Funções interna do Azure.

Escopo da implantação

É possível direcionar o modelo de implantação do Azure para um grupo de recursos, uma assinatura, um grupo de gerenciamento ou um locatário. Dependendo do escopo da implantação, você usará comandos diferentes.

• Para implantar em um grupo de recursos, use az deployment group create:

  az deployment group create --resource-group <resource-group-name> --template-file <path-to-template>
  

• Para implantar em uma assinatura, use az deployment sub create:

  az deployment sub create --location <location> --template-file <path-to-template>
  

  Para saber mais sobre as implantações de nível de assinatura, confira Criar grupos de recursos e recursos no nível da assinatura.

• Para implantar em um grupo de gerenciamento, use az deployment mg create:

  az deployment mg create --location <location> --template-file <path-to-template>
  

  Para saber mais sobre implantações de nível de grupo de gerenciamento, confira Criar recursos no nível de grupo de gerenciamento.

• Para implantar em um locatário, use az deployment tenant create:

  az deployment tenant create --location <location> --template-file <path-to-template>
  

  Para saber mais sobre implantações de nível de locatário, confira Criar recursos no nível de locatário.

Para cada escopo, o usuário que está implantando o modelo deve ter as permissões necessárias para criar recursos.

Implantar o modelo local

Você pode implantar um modelo do ARM por meio do computador local ou de um que esteja armazenado externamente. Esta seção descreve a implantação de um modelo local.

Se você estiver implantando em um grupo de recursos que ainda não existe, precisará criá-lo. O nome do grupo de recursos pode incluir somente caracteres alfanuméricos, pontos, sublinhados, hifens e parênteses. Pode ter até 90 caracteres. O nome não pode terminar em ponto.

az group create --name ExampleGroup --location "Central US"

Para implantar um modelo local, use o parâmetro --template-file no comando de implantação. O exemplo a seguir também mostra como definir um valor de parâmetro.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-template> \
  --parameters storageAccountType=Standard_GRS

O valor do parâmetro --template-file deve ser um arquivo Bicep ou um arquivo .json ou .jsonc. A extensão .jsonc de arquivo indica que o arquivo pode conter comentários de estilo //. O sistema ARM aceita comentários // em arquivos .json. Ele não se importa com a extensão de arquivo. Para mais detalhes sobre comentários e metadados, confira Entender a estrutura e a sintaxe de modelos do ARM.

O modelo de implantação do Azure pode levar alguns minutos para ser concluído. Quando ela for concluída, você verá uma mensagem que inclui o resultado:

"provisioningState": "Succeeded",

Implantar modelo remoto

Em vez de armazenar modelos ARM no computador local, talvez você prefira armazená-los em um local externo. É possível armazenar modelos em um repositório de controle de código-fonte (como o GitHub). Ou ainda armazená-los em uma conta de armazenamento do Azure para acesso compartilhado na sua organização.

Observação

Para implantar um modelo ou fazer referência a um modelo vinculado armazenado em um repositório do GitHub privado, consulte uma solução personalizada documentada em Criar uma oferta personalizada e segura portal do Azure. Você pode criar uma função do Azure que efetue pull do token do GitHub do Azure Key Vault.

Se você estiver implantando em um grupo de recursos que ainda não existe, precisará criá-lo. O nome do grupo de recursos pode incluir somente caracteres alfanuméricos, pontos, sublinhados, hifens e parênteses. Pode ter até 90 caracteres. O nome não pode terminar em ponto.

az group create --name ExampleGroup --location "Central US"

Para implantar um modelo externo, use o parâmetro template-uri.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-uri "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json" \
  --parameters storageAccountType=Standard_GRS

O exemplo anterior requer um URI acessível publicamente para o modelo, que funciona para a maioria dos cenários porque seu modelo não deve incluir dados confidenciais. Se você precisar especificar dados confidenciais (como uma senha de administrador), passe esse valor como um parâmetro seguro. No entanto, se você quiser gerenciar o acesso ao modelo, considere a possibilidade de usar especificações de modelo.

Para implantar modelos vinculados remotos com caminho relativo que são agrupados em uma conta de armazenamento, use query-string para especificar o token SAS:

az deployment group create \
  --name linkedTemplateWithRelativePath \
  --resource-group myResourceGroup \
  --template-uri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" \
  --query-string $sasToken

Para obter mais informações, confira Usar caminho relativo para modelos vinculados.

Nome do modelo de implantação do Azure

Ao implantar um modelo do ARM, você pode dar um nome ao modelo de implantação do Azure. Esse nome pode ajudar a recuperar a implantação do histórico de implantações. Caso você não forneça um nome à implantação, será usado o nome do arquivo de modelo por padrão. Por exemplo, se você implantar um modelo chamado azuredeploy.json e não especificar um nome de implantação, a implantação será nomeada como azuredeploy.

Sempre que você executa uma implantação, é adicionada uma entrada ao histórico de implantações do grupo de recursos com o nome da implantação. Se você executar outra implantação e atribuir o mesmo nome, a entrada anterior será substituída pela implantação atual. Caso você queira manter entradas exclusivas no histórico de implantações, dê a cada implantação um nome exclusivo.

Para criar um nome exclusivo, você pode designar um número aleatório.

deploymentName='ExampleDeployment'$RANDOM

Ou adicionar um valor de data.

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

Se você executar implantações simultâneas no mesmo grupo de recursos com o mesmo nome de implantação, somente a última implantação será concluída. Todas as implantações com nome idêntico que não tenham sido concluídas serão substituídas pela última implantação. Por exemplo, se você executar uma implantação chamada newStorage que implanta uma conta de armazenamento denominada storage1 e, ao mesmo tempo, executar outra implantação chamada newStorage que implanta uma conta de armazenamento denominada storage2, apenas uma conta de armazenamento será implantada. A conta de armazenamento resultante será denominada storage2.

No entanto, se você executar uma implantação chamada newStorage que implanta uma conta de armazenamento denominada storage1 e, logo após a conclusão, executar outra implantação chamada newStorage que implanta uma conta de armazenamento denominada storage2, serão geradas duas contas de armazenamento: uma chamada storage1 e outra denominada storage2. No entanto, apenas uma entrada será registrada no histórico de implantações.

Quando você especifica um nome exclusivo para cada implantação, pode executá-las simultaneamente sem conflitos. Se você executar uma implantação chamada newStorage1 que implanta uma conta de armazenamento denominada storage1 e, ao mesmo tempo, executar outra implantação chamada newStorage2 que implanta uma conta de armazenamento denominada storage2, serão geradas duas contas de armazenamento e serão registradas duas entradas no histórico de implantações.

Para evitar conflitos com implantações simultâneas e garantir entradas exclusivas no histórico de implantações, atribua a cada implantação um nome exclusivo.

Implantar especificação de modelo

Em vez de implantar um modelo local ou remoto, você pode criar uma especificação de modelo. Trata-se de um recurso na assinatura do Azure que contém um modelo ARM. Ela facilita o compartilhamento seguro do modelo com os usuários na organização. Use o Controle de Acesso Baseado em Função do Azure (Azure RBAC) para conceder acesso à especificação de modelo. Este recurso está atualmente em versão prévia.

Os exemplos a seguir mostram como criar e implantar uma especificação de modelo.

Primeiro, crie a especificação de modelo fornecendo o modelo ARM.

az ts create \
  --name storageSpec \
  --version "1.0" \
  --resource-group templateSpecRG \
  --location "westus2" \
  --template-file "./mainTemplate.json"

Em seguida, obtenha a ID da especificação de modelo e implante-a.

id = $(az ts show --name storageSpec --resource-group templateSpecRG --version "1.0" --query "id")

az deployment group create \
  --resource-group demoRG \
  --template-spec $id

Para obter mais informações, confira Especificações de modelo do Azure Resource Manager.

Visualizar alterações

Antes de implantar o modelo do ARM, você pode visualizar as alterações feitas pelo modelo no seu ambiente. Use o teste de hipóteses para conferir se o modelo faz as alterações que você espera. O teste de hipóteses também verifica se há erros no modelo.

Parâmetros

Para passar valores de parâmetros, você pode usar parâmetros embutidos ou um arquivo de parâmetros. O arquivo de parâmetro pode ser um arquivo de parâmetros Bicep ou um arquivo de parâmetros JSON.

Parâmetros embutidos

Para passar parâmetros embutidos, forneça os valores em parameters. Por exemplo, para passar uma cadeia de caracteres e a matriz a um modelo em um shell de Bash, use:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString='inline string' exampleArray='("value1", "value2")'

Se você estiver usando a CLI do Azure com Prompt de Comando do Windows (CMD) ou PowerShell, passe a matriz no formato: exampleArray="['value1','value2']".

Você também pode obter o conteúdo do arquivo e fornecer esse conteúdo como um parâmetro embutido.

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

Obtendo um valor de parâmetro de um arquivo é útil quando você precisa fornecer valores de configuração. Por exemplo, você pode fornecer valores de cloud-init para uma máquina virtual Linux.

O formato arrayContent.json é:

[
  "value1",
  "value2"
]

Para passar um objeto, por exemplo, para definir marcações, use JSON. Por exemplo, seu modelo pode incluir um parâmetro como este:

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

Nesse caso, você pode passar uma cadeia de caracteres JSON para definir o parâmetro, conforme mostrado no seguinte script Bash:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $templateFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

Use aspas duplas no JSON que você deseja passar para o objeto.

Você pode usar uma variável para conter os valores de parâmetro. No Bash, defina a variável como todos os valores de parâmetro e adicione ao comando de implantação.

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-template> \
  --parameters $params

No entanto, se você estiver usando a CLI do Azure com o CMD (Prompt de Comando) do Windows ou o PowerShell, defina a variável como uma cadeia de caracteres JSON. Escape as aspas duplas: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

Arquivos de parâmetro JSON

Em vez de passar parâmetros como valores embutidos no seu script, você pode achar mais fácil usar um arquivo de parâmetros, um arquivo .bicepparam ou um arquivo de parâmetros JSON, que contém os valores de parâmetro. O arquivo de parâmetros deve ser um arquivo local. Não há suporte para arquivos de parâmetros externos com a CLI do Azure.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters 'storage.parameters.json'

Para saber mais sobre o arquivo de parâmetro, confira Criar arquivo de parâmetro do Resource Manager.

Arquivos do parâmetro Bicep

Com a CLI do Azure versão 2.53.0 ou posterior e a CLI do Bicep versão 0.22.6 ou posterior, você pode implantar um arquivo Bicep utilizando um arquivo de parâmetro Bicep. Com a instrução using dentro do arquivo de parâmetros Bicep, não é necessário fornecer a opção --template-file ao especificar um arquivo de parâmetro Bicep para a opção --parameters. A inclusão da opção --template-file resulta em um erro "Somente um modelo .bicep é permitido com um arquivo .bicepparam".

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

O arquivo de parâmetros deve ser um arquivo local. Não há suporte para arquivos de parâmetros externos com a CLI do Azure. Para saber mais sobre o arquivo de parâmetros, confira Criar arquivo de parâmetros do Resource Manager.

Comentários e o formato JSON estendido

Você pode incluir comentários de estilo // em seu arquivo de parâmetro, mas deve nomear o arquivo com uma extensão .jsonc.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.json \
  --parameters '@storage.parameters.jsonc'

Para obter mais detalhes sobre comentários e metadados, consulte Noções básicas sobre a estrutura e a sintaxe dos modelos do ARM.

Se você está usando a CLI do Azure com a versão 2.3.0 ou anterior, pode implantar um modelo com comentários ou cadeias de caracteres multilinha usando a opção --handle-extended-json-format. Por exemplo:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2018-10-01",
  "name": "[variables('vmName')]", // to customize name, change it in variables
  "location": "[
    parameters('location')
    ]", //defaults to resource group location
  /*
    storage account and network interface
    must be deployed first
  */
  "dependsOn": [
    "[resourceId('Microsoft.Storage/storageAccounts/', variables('storageAccountName'))]",
    "[resourceId('Microsoft.Network/networkInterfaces/', variables('nicName'))]"
  ],

Próximas etapas

• Para reverter para uma implantação bem-sucedida quando você receber um erro, confira Reverter em caso de erro para uma implantação bem-sucedida.
• Para especificar como lidar com os recursos existentes no grupo de recursos, mas que não estão definidos no modelo, confira Modos de implantação do Azure Resource Manager.
• Para entender como definir parâmetros no modelo, confira Noções básicas sobre a estrutura e a sintaxe de modelos do ARM.
• Para dicas sobre como resolver erros de implantação, consulte Solução de erros comuns de implantação do Azure com o Azure Resource Manager.