Partilhar via

Implantar arquivos Bicep com o Azure PowerShell

  • Artigo

Este artigo explica como usar o Azure PowerShell com arquivos Bicep para implantar seus recursos no Azure. Se você não estiver familiarizado com a implantação e o gerenciamento de suas soluções do Azure, consulte 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 estar conectado ao Azure:

Se você não tiver o PowerShell instalado, poderá usar o Azure Cloud Shell. Para obter mais informações, consulte Implantar arquivos Bicep com o 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, e o usuário que implanta o arquivo Bicep deve ter as permissões necessárias para criar recursos para cada escopo.

Implantar arquivo Bicep local

Esta seção descreve como implantar um arquivo Bicep local. Você pode implantar um arquivo Bicep a partir de sua máquina local ou externa.

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 e não pode terminar em um período.

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

Para implantar um arquivo Bicep local, use a -TemplateFile opção no comando deployment:

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 oferece suporte à implantação de arquivos Bicep remotos. Você pode usar a CLI do Bicep para criar 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â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 arquivo Bicep, use:

$arrayParam = "value1", "value2"
New-AzResourceGroupDeployment -ResourceGroupName testgroup `
  -TemplateFile <path-to-bicep> `
  -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-bicep> `
  -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 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 do bíceps

Em vez de passar parâmetros como valores embutidos em seu script, talvez seja mais fácil usar um arquivo de parâmetros Bicep ou um arquivo de parâmetros JSON que contenha os valores de parâmetro. O arquivo de parâmetros do 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 o Azure PowerShell versão 10.4.0 ou posterior e a CLI do Bicep versão 0.22.X ou posterior. Com a using instrução dentro do arquivo de parâmetros Bicep, não há necessidade de fornecer o -TemplateFile switch ao especificar um arquivo de parâmetros Bicep para o -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

Arquivos de parâmetros JSON

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

Para passar um arquivo de parâmetros locais, use o TemplateParameterFile switch 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 externos, use o TemplateParameterUri parâmetro:

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 TemplateParameterUri parâmetro suporta apenas arquivos de parâmetros JSON, ele não suporta .bicepparam arquivos.

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âmetros.

Pré-visualizar alterações

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

Implantar 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. O exemplo Criar especificação de modelo mostra como criar uma especificação de modelo em um arquivo Bicep. Você também pode criar seu arquivo Bicep para JSON usando a CLI do Bicep e, em seguida, um modelo JSON para criar uma especificação de modelo.

Nome da implementação

Ao implantar um arquivo Bicep, 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, 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 main.

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 nomeada storage1 e executar outra implantação nomeada newStorage que implanta uma conta de armazenamento nomeada storage2 ao mesmo tempo, 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 nomeada storage1 e executar imediatamente outra implantação nomeada newStorage que implanta uma conta de armazenamento nomeada storage2 após a conclusão da primeira implantação, 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 nomeada storage1 e executar outra implantação nomeada newStorage2 que implanta uma conta de armazenamento nomeada storage2 ao mesmo tempo, 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.

Próximos passos

Para saber como definir parâmetros em seu arquivo, consulte Compreender a estrutura e a sintaxe dos arquivos Bicep.