Compartilhar via

Implantar recursos com modelos do ARM e Azure PowerShell

Este artigo explica como usar Azure PowerShell com modelos de Azure Resource Manager (modelos do ARM) para implantar seus recursos no Azure. Se você não estiver familiarizado com os conceitos de implantação e gerenciamento de soluções de Azure, consulte template deployment overview.

Dica

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

Pré-requisitos

Você precisa de um modelo para implantar. Se você ainda não tiver um, baixe e salve um modelo example no repositório de modelos de início rápido Azure. O nome de arquivo local usado neste artigo é C:\MyTemplates\azuredeploy.json.

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

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

Permissões necessárias

Para implantar um arquivo Bicep ou um modelo ARM (Azure Resource Manager), você precisa de permissão de escrita nos recursos a serem implantados 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 permissões Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/*. A operação do teste de hipóteses tem os mesmos requisitos de permissão.

CLI do Azure versão 2.76.0 ou posterior e Azure PowerShell versão 13.4.0 ou posterior introduziram a opção ValidationLevel para determinar o quão minuciosamente ARM valida o modelo de Bicep durante esse processo. Para obter mais informações, consulte comandos what-if

Para obter uma lista de funções e permissões, consulte funções internas do Azure.

Escopo da implantação

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

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

Nome da implantação

Você pode escolher um nome para o modelo ARM que será implantado. 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 a ela 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.

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

Ou adicionar 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 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 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 o modelo local

É possível implantar um modelo armazenado tanto no computador local como 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 com ponto.

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

Para implantar um modelo local, use o parâmetro -TemplateFile no comando de implantação. O exemplo a seguir também mostra como definir um valor de parâmetro proveniente 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 no computador local, talvez você prefira armazená-los em um local externo. Você pode armazenar modelos em um repositório de controle do código-fonte (como GitHub). Ou você pode armazená-los em uma conta de armazenamento Azure para acesso compartilhado em sua organização.

Observação

Para implantar um modelo ou fazer referência a um modelo vinculado armazenado em um repositório de GitHub privado, consulte uma solução personalizada documentada em Criando uma oferta de portal do Azure personalizada e segura. Você pode criar uma função Azure que extrai o token 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 com ponto.

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

Para implantar um modelo externo, use 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 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 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, confira 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 template. A especificação de modelo é um recurso em sua assinatura Azure que contém um modelo do ARM. Ela facilita o compartilhamento seguro do modelo com os usuários na organização. Você usa o controle de acesso baseado em função do Azure (Azure RBAC) para conceder acesso à especificação do modelo. Esse recurso 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 de modelo fornecendo o modelo ARM.

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

Em seguida, obtenha a ID da especificação de 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 modelos do Azure Resource Manager.

Visualizar alterações

Antes de implantar o modelo, você pode visualizar as alterações que ele fará no ambiente. Use a operação de teste de hipóteses para verificar se o modelo fez as alterações que você esperava. O teste de hipóteses também verifica se há erros no modelo.

Passar valores de parâmetro

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 inline, forneça os nomes do parâmetro com o comando New-AzResourceGroupDeployment. Por exemplo, para passar uma string e array para um template, use:

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

Você pode usar o parâmetro TemplateParameterObject para passar por uma hashtable que contém os parâmetros do modelo.

$params = @{
  exampleString = "inline string"
  exampleArray = "value1", "value2"
}

New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -TemplateParameterObject $params

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

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.

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âmetro JSON

Em vez de passar parâmetros como valores embutidos no script, talvez seja mais fácil usar um arquivo JSON que contenha os valores de parâmetro. 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 arquivo de parâmetro, consulte Criate Resource Manager arquivo de parâmetro.

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

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

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

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 Criate Resource Manager arquivo de parâmetros.

arquivos de parâmetro Bicep

Com Azure PowerShell versão 10.4.0 ou posterior e Bicep CLI versão 0.22.6 ou posterior, você pode implantar um arquivo de modelo arm utilizando um arquivo de parâmetro Bicep. Com a instrução using no arquivo de parâmetros Bicep, não é necessário fornecer a opção -TemplateFile ao especificar um arquivo de parâmetro Bicep para a opção -TemplateParameterFile.

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

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

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

Próximas etapas

  • Last updated on