Como utilizar modelos de implantação Azure Resource Manager (ARM) com Azure CLI

Este artigo explica como usar o Azure CLI com modelos de Resource Manager Azure (modelos ARM) para implantar os seus recursos em Azure. Se não está familiarizado com os conceitos de implantação e gestão das suas soluções Azure, consulte a visão geral da implementação do modelo.

Os comandos de implantação mudaram na versão 2.2.0 do Azure CLI. Os exemplos deste artigo requerem a versão 2.20.0 ou posterior do Azure CLI.

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

As amostras para o Azure CLI são escritas para a bash concha. Para executar esta amostra em Windows PowerShell ou Solicitação de Comando, poderá ter de alterar elementos do script.

Se não tiver o Azure CLI instalado, pode utilizar o Azure Cloud Shell. Para obter mais informações, consulte os modelos ARM da Azure Cloud Shell.

Dica

Recomendamos a Bicep porque oferece as mesmas capacidades que os modelos ARM e a sintaxe é mais fácil de usar. Para saber mais, consulte Como implementar recursos com Bicep e Azure CLI.

Permissões obrigatórias

Para implementar um ficheiro Bicep ou modelo do ARM, precisa de acesso de escrita nos recursos que está a implementar e acesso a todas as operações no tipo de recurso Microsoft.Resources/deployments. Por exemplo, para implantar uma máquina virtual, é necessário Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/* permissões. A operação "e se" tem os mesmos requisitos de permissão.

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

Âmbito de implantação

Pode direcionar o seu modelo de implantação Azure para um grupo de recursos, subscrição, grupo de gestão ou inquilino. Dependendo do âmbito de implantação, utiliza-se diferentes comandos.

Para cada âmbito, o utilizador que implementa o modelo deve ter as permissões necessárias para criar recursos.

Implementar um modelo local

Pode colocar um modelo ARM a partir da sua máquina local ou um que seja armazenado externamente. Esta secção descreve a implementação de um modelo local.

Se estiver a implantar para um grupo de recursos que não existe, crie o grupo de recursos. O nome do grupo de recursos só pode incluir caracteres alfanuméricos, períodos, sublinhados, hífens e parênteses. Pode ser até 90 caracteres. O nome não pode acabar num período.

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

Para implementar um modelo local, utilize o --template-file parâmetro 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 --template-file parâmetro deve ser um ficheiro Bicep ou um .json ou .jsonc ficheiro. A .jsonc extensão do ficheiro indica que o ficheiro pode conter // comentários de estilo. O sistema ARM aceita // comentários em .json ficheiros. Não se importa com a extensão do ficheiro. Para mais detalhes sobre comentários e metadados consulte Consulte a estrutura e sintaxe dos modelos ARM.

O modelo de implantação Azure pode demorar alguns minutos a ser concluído. Quando terminar, vê-se uma mensagem que inclui o resultado:

"provisioningState": "Succeeded",

Implementar o modelo remoto

Em vez de armazenar modelos ARM na sua máquina local, pode preferir guardá-los num 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 implementar um modelo ou referência de um modelo ligado que é armazenado num repo GitHub privado, consulte uma solução personalizada documentada na Criação de uma Oferta personalizada e Segura do Portal Azure. Pode criar uma função Azure que retira o token GitHub do Azure Key Vault.

Se estiver a implantar para um grupo de recursos que não existe, crie o grupo de recursos. O nome do grupo de recursos só pode incluir caracteres alfanuméricos, períodos, sublinhados, hífens e parênteses. Pode ser até 90 caracteres. O nome não pode acabar num período.

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 ao público para o modelo, que funciona para a maioria dos cenários porque o seu modelo não deve incluir dados sensíveis. Se precisar de especificar dados sensíveis (como uma palavra-passe de administração), passe esse valor como parâmetro seguro. No entanto, se quiser gerir o acesso ao modelo, considere usar as especificações do modelo.

Para implementar modelos de ligação remota com caminho relativo que são armazenados numa conta de armazenamento, utilize 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 Utilizar o caminho relativo para modelos ligados.

Nome do modelo de implantação azul

Ao implementar um modelo ARM, pode dar um nome ao modelo de implantação Azure. Este nome pode ajudá-lo a recuperar a implantação do histórico de implantação. Se não fornecer um nome para a implementação, o nome do ficheiro de modelo é usado. Por exemplo, se implementar um modelo chamado azuredeploy.json e não especificar um nome de implantação, a implementação é nomeada azuredeploy.

Sempre que executar uma implantação, uma entrada é adicionada ao histórico de implantação do grupo de recursos com o nome de implantação. Se executar outra implantação e lhe der o mesmo nome, a entrada anterior é substituída pela implementação atual. Se pretender manter entradas únicas no histórico de implantação, dê a cada implementação um nome único.

Para criar um nome único, pode atribuir um número aleatório.

deploymentName='ExampleDeployment'$RANDOM

Ou adicionar um valor de data.

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

Se executar implementações simultâneas para o mesmo grupo de recursos com o mesmo nome de implantação, apenas a última implementação é concluída. Quaisquer implementações com o mesmo nome que não tenham terminado são substituídas pela última implementação. Por exemplo, se executar uma implantação com o nome newStorage de uma conta de armazenamento chamada storage1, e ao mesmo tempo executar outra implantação com o nome newStorage de uma conta de armazenamento chamada storage2, implementa apenas uma conta de armazenamento. A conta de armazenamento resultante é nomeada storage2.

No entanto, se executar uma implementação com o nome newStorage que implementa uma conta de armazenamento chamada storage1, e imediatamente após a sua conclusão, executar outra implantação com o nome newStorage de uma conta de armazenamento chamada storage2, então tem duas contas de armazenamento. Um tem o nome storage1, e o outro chama-se storage2. Mas só tens uma entrada na história da implantação.

Quando especificar um nome único para cada implantação, pode executá-los simultaneamente sem conflitos. Se executar uma implantação com o nome newStorage1 de uma conta de armazenamento chamada storage1, e ao mesmo tempo executar outra implantação com o nome newStorage2 de uma conta de armazenamento , storage2então tem duas contas de armazenamento e duas entradas no histórico de implantação.

Para evitar conflitos com implementações simultâneas e para garantir entradas únicas no histórico de implantação, dê a cada implementação um nome único.

Implementar especificação de modelo

Em vez de implementar um modelo local ou remoto, pode criar uma especificação de modelo. A especificação do modelo é um recurso na sua subscrição Azure que contém um modelo ARM. Torna fácil partilhar o modelo de forma segura com os utilizadores da sua organização. Você usa o controlo de acesso baseado em funções Azure (Azure RBAC) para conceder acesso à especificação do modelo. Esta funcionalidade encontra-se atualmente em pré-visualização.

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

Em primeiro lugar, 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 o ID para especificação de modelo e implemente-o.

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 as especificações do modelo Azure Resource Manager.

Pré-visualizar alterações

Antes de implementar o modelo ARM, pode visualizar as alterações que o modelo irá fazer para o seu ambiente. Utilize a operação "e se" para verificar se o modelo faz as alterações que espera. E se também valida o modelo para erros.

Parâmetros

Para passar valores de parâmetros, pode utilizar parâmetros inline ou um ficheiro de parâmetros.

Parâmetros inline

Para passar parâmetros inline, forneça os valores em parameters. Por exemplo, para passar uma corda e matriz para um modelo numa concha bash, use:

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

Se estiver a utilizar o Azure CLI com o Windows Command Prompt (CMD) ou o PowerShell, passe a matriz no formato: exampleArray="['value1','value2']".

Também pode obter o conteúdo do ficheiro e fornecer esse conteúdo como um parâmetro inline.

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 ficheiro é útil quando é necessário fornecer valores de configuração. Por exemplo, pode fornecer valores de inição de nuvem para uma máquina virtual Linux.

O formato arrayContent.json é:

[
    "value1",
    "value2"
]

Para passar num objeto, por exemplo, para definir tags, use JSON. Por exemplo, o seu modelo pode incluir um parâmetro como este:

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

Neste caso, pode passar numa cadeia JSON para definir o parâmetro como 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 citações duplas em torno do JSON que pretende passar para o objeto.

Pode utilizar uma variável para conter os valores dos parâmetros. Em Bash, desa um ponto de vista da variável para todos os valores dos parâmetros e adicione-a 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 estiver a utilizar o Azure CLI com o Windows Command Prompt (CMD) ou o PowerShell, desapedaça a variável para uma cadeia JSON. Escapar às aspas: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

Ficheiros de parâmetros

Em vez de transmitir parâmetros como valores inline no seu script, poderá considerar mais fácil utilizar um ficheiro JSON que contenha os valores dos parâmetros. O ficheiro do parâmetro deve ser um ficheiro local. Os ficheiros de parâmetros externos não são suportados com o Azure CLI.

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

Para passar um ficheiro de parâmetro local, use @ para especificar um ficheiro local chamado storage.parameters.json.

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

Comentários e o formato JSON alargado

Pode incluir // comentários de estilo no seu ficheiro de parâmetros, mas tem de 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 mais detalhes sobre comentários e metadados consulte Consulte a estrutura e sintaxe dos modelos ARM.

Se estiver a utilizar o Azure CLI com a versão 2.3.0 ou mais antiga, pode implementar um modelo com cordas ou comentários multi-line utilizando o --handle-extended-json-format interruptor. 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'))]"
  ],

Passos seguintes