Implantar arquivos Bicep com a CLI do Azure

Artigo
01/17/2025

Este artigo explica como usar a CLI do Azure com arquivos Bicep para implantar seus recursos no Azure. Se você não tiver familiaridade com a implantação e o gerenciamento das soluções do Azure, confira O que é um Bicep?.

Pré-requisitos

Você precisa implantar um arquivo Bicep e ele deve ser local. Você também precisa da CLI do Azure e de conexão com o Azure:

Instale os comandos da CLI do Azure em seu computador local. Para implantar os arquivos Bicep, você precisa da CLI do Azure versão 2.20.0 ou posterior.
Use az login para se conectar ao Azure. Se você tiver muitas assinaturas do Azure, talvez também precise executar az account set.

As amostras da CLI do Azure são escritas para o shell bash. Para executar esse exemplo no Windows PowerShell ou no prompt de comando (cmd), pode ser necessário alterar elementos do script.

Se você não tiver a CLI do Azure instalada, use o Azure Cloud Shell. Para saber mais, confira 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ê usará comandos diferentes, e o usuário que implanta o arquivo Bicep precisará das permissões necessárias a fim de criar recursos para cada escopo.

Para fazer a implantação em um grupo de recursos, use az deployment group create:

az deployment group create --resource-group <resource-group-name> --template-file <path-to-bicep>

Para fazer a implantação em uma assinatura, use az deployment sub create:
```
az deployment sub create --location <location> --template-file <path-to-bicep>
```
Para saber mais sobre implantações no nível da assinatura, confira Usar o Bicep para implantar recursos em uma assinatura.
Para fazer a implantação em um grupo de gerenciamento, use az deployment mg create:
```
az deployment mg create --location <location> --template-file <path-to-bicep>
```
Para saber mais sobre implantações no nível do grupo de gerenciamento, confira Usar o Bicep para implantar recursos em um grupo de gerenciamento.
Para fazer a implantação em um locatário, use az deployment tenant create:
```
az deployment tenant create --location <location> --template-file <path-to-bicep>
```
Para saber mais sobre implantações no nível do locatário, confira Usar o Bicep para implantar recursos em um locatário.

Implantar um arquivo Bicep local

É possível implantar um arquivo Bicep do computador local ou um que seja externo. Esta seção descreve como implantar um arquivo Bicep 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. Ele pode ter até 90 caracteres e não pode terminar com ponto final.

az group create --name ExampleGroup --location "Central US"

Para implantar um arquivo Bicep local, use o comutador --template-file no comando de implantação. Este exemplo também mostra como definir um valor de parâmetro:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file <path-to-bicep> \
  --parameters storageAccountType=Standard_GRS

A implantação pode levar alguns minutos para ser concluída. Ao final, será exibida uma mensagem que inclui o seguinte resultado:

"provisioningState": "Succeeded",

Implantar arquivo Bicep remoto

No momento, a CLI do Azure não é compatível com a implantação de arquivos Bicep remotos. Você pode usar a CLI do Bicep para compilar o arquivo Bicep em um modelo JSON e carregar esse JSON em um local remoto. Para saber mais, confira Implantar um 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 embutidos, forneça os valores em parameters. Por exemplo, para passar uma cadeia de caracteres e a matriz a um arquivo Bicep em um shell de Bash, use:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters exampleString='inline string' exampleArray='["value1", "value2"]'

Se você estiver usando a CLI do Azure com o cmd ou o PowerShell, transmita a matriz no formato exampleArray="['value1','value2']".

Também é possível obter o conteúdo do arquivo para fornecê-lo como um parâmetro embutido. Coloque @ no início do nome do arquivo:

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters exampleString=@stringContent.txt exampleArray=@arrayContent.json

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.

O formato arrayContent.json é:

[
  "value1",
  "value2"
]

Para transmitir um objeto, use JSON (ao definir tags, por exemplo). O arquivo Bicep pode incluir um parâmetro como este:

"resourceTags": {
  "type": "object",
  "defaultValue": {
    "Cost Center": "IT Department"
  }
}

Conforme mostrado no script Bash a seguir, também é possível transmitir uma cadeia de caracteres JSON para definir o parâmetro. Use aspas duplas ao redor do JSON que você deseja transmitir ao objeto:

tags='{"Owner":"Contoso","Cost Center":"2345-324"}'
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags="$tags"

Se você estiver usando a CLI do Azure com o cmd ou o PowerShell, transmita o objeto no seguinte formato:

$tags="{'Owner':'Contoso','Cost Center':'2345-324'}"
az deployment group create --name addstorage  --resource-group myResourceGroup \
--template-file $bicepFile \
--parameters resourceName=abcdef4556 resourceTags=$tags

Você pode usar uma variável para conter os valores de parâmetro. Defina a variável para todos os valores de parâmetro no script Bash e adicione-a ao comando de implantação:

params="prefix=start suffix=end"

az deployment group create \
  --resource-group testgroup \
  --template-file <path-to-bicep> \
  --parameters $params

No entanto, se você estiver usando a CLI do Azure com o cmd ou o PowerShell, defina a variável como uma cadeia de caracteres JSON. Escape as aspas duplas: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

A avaliação dos parâmetros segue uma ordem sequencial, o que significa que se um valor for atribuído diversas vezes, somente o último valor atribuído será usado. Para atribuir parâmetros corretamente, é recomendado fornecer o arquivo de parâmetros inicialmente e, em seguida, usar a sintaxe KEY=VALUE para substituir seletivamente parâmetros específicos. Ao fornecer um arquivo de parâmetros .bicepparam, só é possível usar esse argumento uma vez.

Arquivos de parâmetros Bicep

Em vez de transmitir parâmetros como valores embutidos no script, pode ser mais fácil usar um arquivo de parâmetros Bicep ou um arquivo de parâmetros JSON com os valores dos parâmetros. O arquivo de parâmetros precisa ser local porque a CLI do Azure não aceita arquivos de parâmetros externos. Para saber mais sobre arquivos de parâmetros, confira Criar arquivos de parâmetros para a implantação do Bicep.

É possível usar um arquivo de parâmetros do Bicep para implantar um arquivo Bicep com a CLI do Azure 2.53.0 ou mais recente e a CLI do Bicep 0.22.X ou mais recente. Com a instrução using no arquivo de parâmetros do Bicep, não é necessário fornecer a opção --template-file ao especificar um arquivo de parâmetros do Bicep para a opção --parameters. Incluir a opção --template-file exibirá o erro "Somente um modelo .bicep é permitido com um arquivo .bicepparam".

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:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

Arquivos de parâmetros JSON

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

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --template-file storage.bicep \
  --parameters '@storage.parameters.json'

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

No momento, a CLI do Azure não fornece arquivos Bicep para ajudar na criação de especificações de modelo. No entanto, é possível criar um arquivo Bicep com o recurso Microsoft.Resources/templateSpecs para implantar uma especificação de modelo. O exemplo Criar uma especificação de modelo mostra como criar uma especificação de modelo em um arquivo Bicep. Também é possível criar o arquivo Bicep em JSON usando a CLI do Bicep e, em seguida, 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. Se você não fornecer um nome para a implantação, o nome dela será 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á chamada 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, é possível atribuir um número aleatório:

deploymentName='ExampleDeployment'$RANDOM

Também é possível adicionar um valor de data:

deploymentName='ExampleDeployment'$(date +"%d-%b-%Y")

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 a implantação newStorage para implantar a conta de armazenamento storage1 e executar outra implantação newStorage para implantar a conta de armazenamento storage2 ao mesmo tempo, somente uma das contas de armazenamento será implantada. A conta de armazenamento resultante será denominada storage2.

No entanto, se você executar a implantação newStorage para implantar a conta de armazenamento storage1 e executar imediatamente outra implantação newStorage para implantar a conta de armazenamento storage2 após a conclusão da primeira, 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 a implantação newStorage1 para implantar a conta de armazenamento storage1 e, ao mesmo tempo, executar outra implantação newStorage2 para implantar a conta de armazenamentostorage2, 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 entender como definir parâmetros no arquivo, confira Entender a estrutura e a sintaxe dos arquivos Bicep.

Compartilhar via