Compartilhar via

Implantar arquivos Bicep com o Azure PowerShell

  • Artigo

Este artigo explica como usar o Azure PowerShell com os arquivos Bicep para implantar seus recursos no Azure. Se você não estiver familiarizado com a implantação e o gerenciamento de soluções do Azure, confira O que é o Bicep?.

Pré-requisitos

Você precisa de um arquivo Bicep para implantar e o arquivo deve ser local. Você também precisa do Azure PowerShell e se conectar ao Azure:

Se você não tiver o PowerShell instalado, use o Azure Cloud Shell. Para obter mais informações, consulte Implantar arquivos Bicep com o Azure Cloud Shell.

Permissões necessárias

Para implantar um arquivo Bicep ou um modelo do ARM, você precisa de acesso de gravação nos recursos que está implantando e acesso a todas as operações no tipo de recurso Microsoft.Resources/implantações. Por exemplo, para implantar uma máquina virtual, você precisa Microsoft.Compute/virtualMachines/write e permissões Microsoft.Resources/deployments/*. A operação do teste de hipóteses tem os mesmos requisitos de permissão.

Para ver uma lista de funções e permissões, consulte Funções interna 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ê usa comandos diferentes e o usuário que está implantando o arquivo Bicep deve ter as permissões necessárias para criar recursos para cada escopo.

Implantar um arquivo Bicep local

Esta seção descreve como implantar um arquivo Bicep local. Você pode implantar um arquivo Bicep do computador local ou de um externo.

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 e não pode terminar em um ponto final.

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

Para implantar um arquivo Bicep local, use o comutador -TemplateFile no comando de implantação:

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

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

Implantar arquivo Bicep remoto

Atualmente, o Azure PowerShell não dá suporte à implantação de arquivos Bicep remotos. Você pode usar a CLI do Bicep para compilar o arquivo Bicep em um modelo JSON e, em seguida, carregar o arquivo JSON em um local remoto. Para obter mais informações, consulte Implantar modelo remoto.

Parâmetros

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 arquivo Bicep, use:

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

Você pode usar o parâmetro TemplateParameterObject para passar por uma tabela hash 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-bicep> `
  -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 hash no Azure 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-bicep> `
  -exampleArray $subnetArray

Arquivos de parâmetros Bicep

Em vez de passar parâmetros como valores embutidos em seu script, pode ser mais fácil usar um arquivo de parâmetros Bicep ou um arquivo de parâmetros JSON que contém os valores de parâmetro. O arquivo de parâmetros Bicep deve ser um arquivo local, enquanto o arquivo de modelo JSON pode estar localizado em algum lugar online. Para obter mais informações sobre arquivos de parâmetros, consulte Criar arquivos de parâmetros para implantação do Bicep.

Você pode usar um arquivo de parâmetros Bicep para implantar um arquivo Bicep com a versão 10.4.0 do Azure PowerShell e a versão 0.22.X ou posterior da CLI do Bicep. Com a instrução using no arquivo de parâmetros do Bicep, não é necessário fornecer a opção -TemplateFile ao especificar um arquivo de parâmetros do 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

Arquivos de parâmetros JSON

O arquivo de parâmetros JSON pode ser um arquivo local ou um arquivo externo com um URI acessível.

Para passar um arquivo de parâmetros local, use a opção TemplateParameterFile com um arquivo de parâmetros JSON:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile c:\BicepFiles\storage.bicep `
  -TemplateParameterFile c:\BicepFiles\storage.parameters.json

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

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

Como o parâmetro TemplateParameterUri só dá suporte a arquivos de parâmetros JSON, ele não dá suporte a arquivos .bicepparam.

Você pode usar parâmetros embutidos e um arquivo de parâmetros de localização na mesma operação de implantação. Para obter mais informações, consulte Precedência de parâmetro.

Visualizar alterações

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

Implantar as especificações de modelo

Atualmente, o Azure PowerShell não fornece arquivos Bicep para ajudar a criar especificações de modelo. No entanto, você pode criar um arquivo Bicep com o recurso Microsoft.Resources/templateSpecs para implantar uma especificação de modelo. A opção Criar exemplo de especificação de modelo mostra como criar uma especificação de modelo em um arquivo Bicep. Você também pode criar o arquivo Bicep em JSON usando a CLI do Bicep e um modelo JSON para criar uma especificação de modelo.

Nome da implantação

Ao implantar um arquivo Bicep, você pode escolher um nome para a implantação. 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, seu nome se tornará o nome do arquivo Bicep. Por exemplo, se você implantar um arquivo Bicep chamado main.bicep e não especificar um nome de implantação, a implantação será nomeada como main.

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 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 atribuir 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 executar imediatamente outra implantação chamada newStorage que implanta uma conta de armazenamento denominada storage2 após a conclusão da primeira implantação, você terá 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, terá 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.

Próximas etapas

Para saber como definir parâmetros no arquivo, consulte Entender a estrutura e a sintaxe dos arquivos Bicep.