Implantar recursos com modelos ARM e Azure PowerShell

  • Artigo

Este artigo explica como usar o Azure PowerShell 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.

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 Implantar recursos com Bicep e Azure PowerShell.

Pré-requisitos

Você precisa de um modelo para implantar. Se ainda não tiver um, transfira e guarde um modelo de exemplo a partir do repositório de modelos de início rápido do Azure. O nome do arquivo local usado neste artigo é C:\MyTemplates\azuredeploy.json.

Você precisa instalar o Azure PowerShell e conectar-se ao Azure:

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

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, você precisa de Microsoft.Compute/virtualMachines/write permissões Microsoft.Resources/deployments/* . A operação hipotética tem os mesmos requisitos de permissão.

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

Âmbito da implementação

Você pode direcionar sua implantação 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 New-AzResourceGroupDeployment:

    New-AzResourceGroupDeployment -ResourceGroupName <resource-group-name> -TemplateFile <path-to-template>

  • Para implantar em uma assinatura, use New-AzSubscriptionDeployment, que é um alias do New-AzDeployment cmdlet:

    New-AzSubscriptionDeployment -Location <location> -TemplateFile <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 New-AzManagementGroupDeployment.

    New-AzManagementGroupDeployment -Location <location> -TemplateFile <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 New-AzTenantDeployment.

    New-AzTenantDeployment -Location <location> -TemplateFile <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.

Nome da implementação

Ao implantar um modelo ARM, você pode dar um nome à implantação. Esse nome pode ajudá-lo a recuperar a implantação 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.

$suffix = Get-Random -Maximum 1000
$deploymentName = "ExampleDeployment" + $suffix

Ou adicione um valor de data.

$today=Get-Date -Format "MM-dd-yyyy"
$deploymentName="ExampleDeployment"+"$today"

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 que implanta uma conta de armazenamento chamada , e ao mesmo tempo executar outra implantação nomeada newStoragenewStorage que implanta uma conta de armazenamento chamada storage1storage2, você implantará apenas uma conta de armazenamento. A conta de armazenamento resultante é denominada storage2.

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

Ao especificar um nome exclusivo para cada implantação, você pode executá-los simultaneamente sem conflito. Se você executar uma implantação nomeada que implanta uma conta de armazenamento chamada e, ao mesmo tempo, executar outra implantação nomeada newStorage1newStorage2 que implanta uma conta de armazenamento chamada storage1storage2, 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.

Implementar um modelo local

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

Se você estiver implantando em 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, pontos, sublinhados, hífenes e parênteses. Pode ter até 90 caracteres. O nome não pode terminar em um ponto.

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

Para implantar um modelo local, use o -TemplateFile parâmetro no comando deployment. O exemplo a seguir também mostra como definir um valor de parâmetro que vem do modelo.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateFile <path-to-template>

A implantação pode levar vários minutos para ser concluída.

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.

Se você estiver implantando em 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, pontos, sublinhados, hífenes e parênteses. Pode ter até 90 caracteres. O nome não pode terminar em um ponto.

New-AzResourceGroup -Name ExampleGroup -Location "Central US"

Para implementar um modelo externo, utilize o parâmetro -TemplateUri.

New-AzResourceGroupDeployment `
  -Name remoteTemplateDeployment `
  -ResourceGroupName ExampleGroup `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json

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 QueryString para especificar o token SAS:

New-AzResourceGroupDeployment `
  -Name linkedTemplateWithRelativePath `
  -ResourceGroupName "myResourceGroup" `
  -TemplateUri "https://stage20210126.blob.core.windows.net/template-staging/mainTemplate.json" `
  -QueryString "$sasToken"

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

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 do modelo. Esta funcionalidade está atualmente em pré-visualização.

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.

New-AzTemplateSpec `
  -Name storageSpec `
  -Version 1.0 `
  -ResourceGroupName templateSpecsRg `
  -Location westus2 `
  -TemplateJsonFile ./mainTemplate.json

Em seguida, obtenha a ID para a especificação do modelo e implante-a.

$id = (Get-AzTemplateSpec -Name storageSpec -ResourceGroupName templateSpecsRg -Version 1.0).Versions.Id

New-AzResourceGroupDeployment `
  -ResourceGroupName demoRG `
  -TemplateSpecId $id

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

Pré-visualizar alterações

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

Valores dos parâmetros de passagem

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 embutidos, forneça os nomes do parâmetro com o New-AzResourceGroupDeployment comando. Por exemplo, para passar uma cadeia de caracteres e uma matriz para um modelo, use:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleString "inline string" `
  -exampleArray $arrayParam

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

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleString $(Get-Content -Path c:\MyTemplates\stringcontent.txt -Raw) `
  -exampleArray $arrayParam

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

Se você precisar passar uma matriz de objetos, crie tabelas de hash no PowerShell e adicione-as a uma matriz. Passe essa matriz como um parâmetro durante a implantação.

$hash1 = @{ Name = "firstSubnet"; AddressPrefix = "10.0.0.0/24"}
$hash2 = @{ Name = "secondSubnet"; AddressPrefix = "10.0.1.0/24"}
$subnetArray = $hash1, $hash2
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-template> `
  -exampleArray $subnetArray

Arquivos de parâmetros JSON

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 arquivo de parâmetro pode ser um arquivo local ou um arquivo externo com um URI acessível.

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

Para passar um arquivo de parâmetro local, use o TemplateParameterFile parâmetro:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile <path-to-template> `
  -TemplateParameterFile c:\MyTemplates\storage.parameters.json

Para passar um arquivo de parâmetro externo, use o TemplateParameterUri parâmetro:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.json `
  -TemplateParameterUri https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/quickstarts/microsoft.storage/storage-account-create/azuredeploy.parameters.json

Para obter mais informações sobre o arquivo de parâmetros, consulte Criar arquivo de parâmetros do Gerenciador de Recursos.

Arquivos de parâmetros do bíceps

Com o Azure PowerShell versão 10.4.0 ou posterior e a CLI do Bicep versão 0.22.6 ou posterior, você pode implantar um arquivo de modelo ARM utilizando um arquivo de parâmetro Bicep. Com a using instrução dentro do arquivo de parâmetros Bicep, não há necessidade de fornecer o switch ao especificar um arquivo de parâmetro Bicep para o -TemplateFile-TemplateParameterFile switch.

O exemplo a seguir mostra um arquivo de parâmetros chamado storage.bicepparam. O arquivo está no mesmo diretório onde o comando é executado.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateParameterFile storage.bicepparam

Para obter mais informações sobre o arquivo de parâmetros do Bicep, consulte Arquivo de parâmetros do Bicep.

Próximos passos