Implementar recursos com templates ARM e Azure PowerShell

Este artigo explica como usar o Azure PowerShell com templates do Azure Resource Manager (templates ARM) para implementar os seus recursos no Azure. Se não estiver familiarizado com os conceitos de implementação e gestão das suas soluções Azure, consulte visão geral da implementação de modelos.

Pré-requisitos

Você precisa de um modelo para implantar. Se ainda não tiveres um, descarrega e guarda um modelo exemplo do repositório de templates Azure Quickstart. O nome de ficheiro local usado neste artigo é C:\MyTemplates\azuredeploy.json.

Precisa de instalar o Azure PowerShell e ligar-se ao Azure:

• Instale os cmdlets do Azure PowerShell no seu computador local. Para mais informações, consulte Comece com Azure PowerShell.
• Liga-te a Azure usando Connect-AZAccount. Se tiver várias subscrições de Azure, poderá também precisar de executar Set-AzContext. Para mais informações, consulte Use as múltiplas assinaturas do Azure.

Se não tiver o PowerShell instalado, pode usar o Azure Cloud Shell. Para mais informações, consulte Implementar templates ARM a partir do Azure Cloud Shell.

Permissões obrigatórias

Para implementar um ficheiro Bicep ou um modelo Azure Resource Manager (ARM), precisa de permissões 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 implementar uma máquina virtual, precisa de permissões Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/*. A operação 'what-if' 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 introduzem o interruptor ValidationLevel para determinar quão completamente o ARM valida o modelo de Bicep durante este processo. Para obter mais informações, consulte Comandos hipotéticos

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

Âmbito da implementação

Pode direcionar a sua implementação para um grupo de recursos, uma subscrição, um grupo de gestão ou um 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 numa assinatura, use New-AzSubscriptionDeployment, que é um aliais 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 gestão, 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 através 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 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, 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 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.

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 estiver a fazer a implementação num 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 num 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. Podes armazenar modelos num repositório de controlo de versões (como o GitHub). Ou pode armazená-las numa conta de armazenamento Azure para acesso partilhado na sua organização.

Se estiveres a implementar num grupo de recursos que 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.

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 implementar um modelo local ou remoto, pode criar uma especificação template. A especificação do template é um recurso na tua subscrição do Azure que contém um template ARM. Ele facilita o compartilhamento seguro do modelo com os usuários em sua organização. Utilizas o controlo de acesso baseado em papéis do Azure (Azure RBAC) para conceder acesso à especificação do template. 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 o identificador da 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 mais informações, consulte as especificações do 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.

Passar valores de parâmetros

Para passar valores de parâmetro, você pode usar parâmetros embutidos ou um arquivo de parâmetros. O ficheiro de parâmetros pode ser um ficheiro de parâmetros Bicep ou um ficheiro 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ê pode usar o TemplateParameterObject parâmetro para passar por uma hashtable que contém os parâmetros para o 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

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 mais informações sobre o ficheiro de parâmetros, veja Create Resource Manager ficheiro de parâmetros.

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 mais informações sobre o ficheiro de parâmetros, veja Create Resource Manager parameters file.

Os ficheiros de parâmetros do Bicep

Com Azure PowerShell versão 10.4.0 ou posterior, e Bicep CLI versão 0.22.6 ou posterior, pode implementar um ficheiro modelo ARM utilizando um ficheiro de parâmetros Bicep. Com a instrução using dentro do ficheiro de parâmetros Bicep, não é necessário fornecer o interruptor -TemplateFile ao especificar um ficheiro de parâmetros Bicep para o interruptor -TemplateParameterFile.

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 mais informações sobre o ficheiro de parâmetros do Bicep, consulte ficheiro de parâmetros do Bicep.

Próximos passos

• Para reverter para uma implantação bem-sucedida ao obteres um erro, consulta Reversão em erro para implantação bem-sucedida.
• Para especificar como gerir recursos que existem no grupo de recursos mas não estão definidos no modelo, veja Azure Resource Manager modos de implementação.
• Para entender como definir parâmetros em seu modelo, consulte Compreender a estrutura e a sintaxe dos modelos ARM.
• Para obter informações sobre como implantar um modelo que requer um token SAS, consulte Implantar modelo ARM privado com token SAS.