Partilhar via

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

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

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

Para executar este exemplo, instale a versão mais recente da CLI do Azure. Para começar, execute az login para criar uma ligação ao Azure.

Os exemplos da CLI do Azure são escritos para o shell bash. Para executar este exemplo no Windows PowerShell ou no Prompt de Comando, talvez seja necessário alterar elementos do script.

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

Gorjeta

Recomendamos o Bicep porque ele oferece os mesmos recursos que os modelos ARM e a sintaxe é mais fácil de usar. Para saber mais, consulte Como implantar recursos com o Bicep e a CLI do Azure.

Pré-requisitos

Permissões obrigatórias

Para implantar um arquivo Bicep ou um modelo ARM (Azure Resource Manager), você precisa de acesso de gravação nos recursos que está implantando e acesso a todas as operações no Microsoft.Resources/deployments tipo de recurso. Por exemplo, para implantares uma máquina virtual, precisas de Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/* permissões. A operação hipotética tem os mesmos requisitos de permissão.

A CLI do Azure versão 2.76.0 ou posterior e o Azure PowerShell versão 13.4.0 ou posterior introduzem a opção ValidationLevel para determinar quão completamente o ARM valida o modelo Bicep durante esse processo. Para obter mais informações, consulte Comandos hipotéticos

Para obter uma lista de funções e permissões, veja Funções incorporadas do Azure.

Âmbito da implementação

Você pode direcionar seu modelo de implantação do Azure para um grupo de recursos, assinatura, grupo de gerenciamento ou locatário. Dependendo do escopo da implantação, você usa 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 numa assinatura, use az deployment sub create:

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

    Para obter mais informações sobre implantações no nível de assinatura, consulte Criar grupos de recursos e recursos no nível de 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 obter mais informações sobre implantações no nível do grupo de gerenciamento, consulte Criar recursos no nível do 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 obter mais informações sobre implantações no nível do locatário, consulte Criar recursos no nível do locatário.

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

Implementar um modelo local

Você pode implantar um modelo ARM de sua máquina local ou um que é armazenado externamente. Esta seção descreve a implantação de um modelo local.

Caso estejas a implementar num grupo de recursos que ainda não existe, cria o grupo de recursos. O nome do grupo de recursos só pode incluir caracteres alfanuméricos, pontos, sublinhados, hífenes e parênteses. Pode ter até 90 caracteres. O nome não pode terminar em ponto final.

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

Para implantar um modelo local, use o --template-file parâmetro no comando deployment. 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 .jsonc extensão do arquivo indica que o arquivo pode conter // comentários de estilo. O sistema ARM aceita comentários // em ficheiros .json. Ele não se importa com a extensão do arquivo. Para obter mais detalhes sobre comentários e metadados, consulte Compreender a estrutura e a sintaxe dos modelos ARM.

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

"provisioningState": "Succeeded",

Implantar modelo remoto

Em vez de armazenar modelos ARM em sua máquina local, você pode preferir armazená-los em um local externo. Pode armazenar modelos num repositório de controlo de código fonte (como o GitHub). Em alternativa, pode armazená-los numa conta de armazenamento do Azure para acesso partilhado na sua organização.

Nota

Para implantar um modelo ou fazer referência a um modelo vinculado armazenado em um repositório privado do GitHub, consulte uma solução personalizada documentada em Criando uma oferta personalizada e segura do Portal do Azure. Você pode criar uma função do Azure que extrai o token do GitHub do Cofre da Chave do Azure.

Caso estejas a implementar num grupo de recursos que ainda não existe, cria o grupo de recursos. O nome do grupo de recursos só pode incluir caracteres alfanuméricos, pontos, sublinhados, hífenes e parênteses. Pode ter até 90 caracteres. O nome não pode terminar em ponto final.

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

Para implementar um modelo externo, utilize 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 usar as especificações do modelo.

Para implantar modelos vinculados remotos com caminho relativo armazenados 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, consulte Usar caminho relativo para modelos vinculados.

Nome do modelo de implantação do Azure

Ao implantar um modelo ARM, você pode dar um nome ao modelo de implantação do Azure. Esse nome pode ajudá-lo a recuperar a implantação a partir do histórico de implantação. Se você não fornecer um nome para a implantação, o nome do arquivo de modelo será usado. Por exemplo, se você implantar um modelo chamado azuredeploy.json e não especificar um nome de implantação, a implantação será nomeada azuredeploy.

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

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

deploymentName='ExampleDeployment'$RANDOM

Ou adicione 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 o mesmo nome que não foram concluídas são substituídas pela última implantação. Por exemplo, se você executar uma implantação nomeada newStorage que implanta uma conta de armazenamento chamada storage1, e ao mesmo tempo executar outra implantação nomeada newStorage que implanta uma conta de armazenamento chamada storage2, você implantará apenas uma conta de armazenamento. A conta de armazenamento resultante é denominada storage2.

No entanto, se você executar uma implantação nomeada newStorage que implanta uma conta de armazenamento chamada storage1, e imediatamente após sua conclusão executar outra implantação nomeada newStorage que implanta uma conta de armazenamento chamada storage2, então você terá duas contas de armazenamento. Um é chamado storage1, e o outro é chamado storage2. Mas só há uma entrada no histórico de implementação.

Ao especificar um nome exclusivo para cada implantação, você pode executá-los simultaneamente sem conflito. Se você executar uma implantação nomeada newStorage1 que implanta uma conta de armazenamento chamada storage1e, ao mesmo tempo, executar outra implantação nomeada newStorage2 que implanta uma conta de armazenamento chamada storage2, terá duas contas de armazenamento e duas entradas no histórico de implantação.

Para evitar conflitos com implantações simultâneas e garantir entradas exclusivas no histórico de implantação, dê 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. A especificação de modelo é um recurso em sua assinatura do Azure que contém um modelo ARM. Ele facilita o compartilhamento seguro do modelo com os usuários em sua organização. Você usa o controle de acesso baseado em função do Azure (Azure RBAC) para conceder acesso à especificação de template. A funcionalidade 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 do 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 identificação da especificação do modelo e implemente-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, consulte Especificações de modelo do Azure Resource Manager.

Pré-visualizar alterações

Antes de implantar seu modelo ARM, você pode visualizar as alterações que o modelo faz em seu ambiente. Use a operação what-if para verificar se o modelo faz as alterações que esperava. O What-if também valida o modelo em busca de erros.

Parâmetros

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

Parâmetros em linha

Para passar parâmetros em linha, forneça os valores em parameters. Por exemplo, para passar uma cadeia de caracteres e uma matriz para um modelo em um shell 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 o Prompt de Comando do Windows (CMD) ou o 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

Obter um valor de parâmetro de um arquivo é útil quando você precisa fornecer valores de configuração. Por exemplo, 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 tags, 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 ao redor do JSON que você deseja passar para o objeto.

Você pode usar uma variável para conter os valores de parâmetro. Em Bash, defina a variável para todos os valores de parâmetro e adicione-a ao comando deployment.

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 Prompt de Comando do Windows (CMD) ou PowerShell, defina a variável como uma cadeia de caracteres JSON. Fuja das aspas: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

Arquivos de parâmetros JSON

Em vez de passar parâmetros como valores embutidos em seu script, você pode achar mais fácil usar um arquivo de parâmetros, um .bicepparam arquivo 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. Os arquivos de parâmetros externos não são suportados com a CLI do Azure.

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

Para obter mais informações sobre o ficheiro de parâmetros, veja Criar ficheiro de parâmetros do Resource Manager.

Arquivos de parâmetros do bíceps

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 dos arquivos 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 --template-file opção resulta em um erro "Somente um arquivo .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. Os arquivos de parâmetros externos não são suportados com a CLI do Azure. Para obter mais informações sobre o arquivo de parâmetros, consulte Criar arquivo de parâmetros do Gerenciador de Recursos.

Comentários e o formato JSON estendido

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

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 Compreender a estrutura e a sintaxe dos modelos ARM.

Se você estiver usando a CLI do Azure com a versão 2.3.0 ou anterior, poderá implantar um modelo com cadeias de caracteres de várias linhas ou comentários usando o --handle-extended-json-format switch. Por exemplo:

{
  "type": "Microsoft.Compute/virtualMachines",
  "apiVersion": "2025-04-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óximos passos

  • Last updated on