Como implantar recursos com o Bicep e a CLI do Azure

  • Artigo

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

Pré-requisitos

Você precisa de um arquivo Bicep para implantar. O arquivo precisa ser local.

Você precisa ter a CLI do Azure e se conectar ao 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.
  • Conexão para o Azure usando az login . Se você tiver várias assinaturas do Azure, talvez precise executar também az account set.

As amostras da CLI do Azure são escritas para o shell bash. Para executar esta amostra no prompt de comando ou no Windows PowerShell, talvez você precise alterar os elementos do script.

Se você não tiver a CLI do Azure instalada, você pode usar o Azure Cloud Shell. Para obter mais informações, confira Implantar arquivos Bicep do 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.

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

Implantar um arquivo Bicep local

É possível implantar um arquivo Bicep armazenado tanto no computador local como externamente. Esta seção descreve a implantação de 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. Pode ter até 90 caracteres. O nome não pode terminar em ponto.

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

Para implantar um arquivo Bicep local, use o comutador --template-file no comando de implantação. O exemplo a seguir 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. Quando ela for concluída, você verá uma mensagem que inclui o resultado:

"provisioningState": "Succeeded",

Implantar arquivo Bicep remoto

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

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 Prompt de Comando do Windows (CMD) ou PowerShell, passe a matriz no formato: exampleArray="['value1','value2']".

Você também pode obter o conteúdo do arquivo e fornecer esse conteúdo 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 passar um objeto, por exemplo, para definir marcações, use JSON. Por exemplo, o arquivo Bicep pode incluir um parâmetro como este:

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

Nesse caso, você pode passar uma cadeia de caracteres JSON para definir o parâmetro, conforme mostrado no seguinte script Bash:

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

Use aspas duplas no JSON que você deseja passar para o objeto.

Se você estiver usando a CLI do Azure com o CMD (Prompt de Comando do Windows) 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. No Bash, defina a variável como todos os valores de parâmetro e adicione 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 (Prompt de Comando) do Windows 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 de parâmetros segue uma ordem sequencial, o que significa que, se um valor for atribuído várias vezes, somente o último valor atribuído será usado. Para garantir a atribuição adequada de parâmetros, é aconselhável fornecer seu arquivo de parâmetros inicialmente e substituir seletivamente parâmetros específicos usando a sintaxe KEY=VALUE. É importante mencionar que, se você estiver fornecendo um arquivo de parâmetros bicepparam, poderá usar esse argumento apenas uma vez.

Arquivos do parâmetro Bicep

Em vez de passar parâmetros como valores embutidos no seu script, você pode achar mais fácil usar um arquivo de parâmetros, 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 deve ser um arquivo local. Não há suporte para arquivos de parâmetros externos com a CLI do Azure. Para saber mais sobre o arquivo de parâmetros, confira Criar arquivo de parâmetros do Resource Manager.

Com a CLI do Azure versão 2.53.0 ou posterior e CLI do Bicep versão 0.22.X ou superior, você pode implantar um arquivo Bicep usando 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 --template-file ao especificar um Arquivo de parâmetro Bicep para a opção --parameters. A inclusão da opção --template-file resultará no 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âmetro 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'

Para saber mais sobre o arquivo de parâmetros, confira Criar arquivo de parâmetros do Resource Manager.

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, a CLI do Azure não dá suporte à criação de especificações de modelo ao fornecer arquivos Bicep. 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 o arquivo Bicep em JSON usando a CLI do Bicep e criar uma especificação de modelo com o modelo JSON.

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, será usado o nome do arquivo Bicep por padrão. 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 designar um número aleatório.

deploymentName='ExampleDeployment'$RANDOM

Ou 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 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 serão registradas 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