Como implementar recursos com o Bicep e a CLI do Azure

  • Artigo

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

Pré-requisitos

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

Você precisa da CLI do Azure e estar conectado ao Azure:

  • Instale os comandos da CLI do Azure em seu computador local. Para implantar arquivos Bicep, você precisa da CLI do Azure versão 2.20.0 ou posterior.
  • Conecte-se ao Azure usando az login. Se você tiver várias assinaturas do Azure, talvez também precise executar o conjunto de contas az.

Exemplos para a CLI do Azure são escritos para o bash shell. Para executar este exemplo no Windows PowerShell ou no Prompt de Comando, talvez seja necessário alterar elementos do script.

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

  • Para implantar 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 implantar em uma assinatura, use az deployment sub create:

    az deployment sub create --location <location> --template-file <path-to-bicep>

    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 gerenciamento, use az deployment mg create:

    az deployment mg create --location <location> --template-file <path-to-bicep>

    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 az deployment tenant create:

    az deployment tenant create --location <location> --template-file <path-to-bicep>

    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 arquivo Bicep deve ter as permissões necessárias para criar recursos.

Implantar arquivo Bicep local

Você pode implantar um arquivo Bicep de sua máquina local ou um que é armazenado externamente. Esta seção descreve a implantação de um arquivo Bicep local.

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

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

Para implantar um arquivo Bicep local, use a --template-file opção no comando deployment. 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 implementação pode demorar alguns minutos a concluir. Quando terminar, você verá uma mensagem que inclui o resultado:

"provisioningState": "Succeeded",

Implantar arquivo Bicep remoto

Atualmente, a CLI do Azure 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 para o local remoto. Para obter mais informações, consulte Implantar modelos JSON ARM remotos.

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 valores em parameters. Por exemplo, para passar uma cadeia de caracteres e matriz para um arquivo Bicep em um shell 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 Prompt de Comando do Windows (CMD) ou o 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. Prefacie o nome do arquivo com @.

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

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.

O formato arrayContent.json é:

[
  "value1",
  "value2"
]

Para passar um objeto, por exemplo, para definir tags, use JSON. Por exemplo, seu 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 ao redor do JSON que você deseja passar para o objeto.

Se você estiver usando a CLI do Azure com o Prompt de Comando do Windows (CMD) ou o PowerShell, passe 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. Em Bash, defina a variável para todos os valores de parâmetro e adicione-a ao comando deployment.

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 Prompt de Comando do Windows (CMD) ou PowerShell, defina a variável como uma cadeia de caracteres JSON. Fuja das aspas: $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 várias vezes, apenas 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 bicepparam arquivo de parâmetros, poderá usar esse argumento apenas uma vez.

Arquivos de parâmetros do bíceps

Em vez de passar parâmetros como valores embutidos em 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. Os arquivos de parâmetros externos não são suportados com a CLI do Azure. Para obter mais informações sobre o arquivo de parâmetros, consulte Criar arquivo de parâmetros do Gerenciador de Recursos.

Com a CLI do Azure versão 2.53.0 ou posterior e a CLI do Bicep versão 0.22.X ou superior, você pode implantar um arquivo Bicep utilizando um arquivo de parâmetro Bicep. Com a using instrução dentro do arquivo de parâmetros Bicep, não há necessidade de fornecer o --template-file switch ao especificar um arquivo de parâmetro Bicep para o --parameters switch. Incluir a --template-file opção resultará em um 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 onde 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 onde o comando é executado.

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

Para obter mais informações sobre o arquivo de parâmetros, consulte Criar arquivo de parâmetros do Gerenciador de Recursos.

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, a CLI do Azure não oferece suporte à criação de especificações de modelo fornecendo 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 seu arquivo Bicep para JSON usando a CLI do Bicep e, em seguida, criar uma especificação de modelo com o modelo JSON.

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, o nome do arquivo Bicep será usado. Por exemplo, se você implantar um arquivo Bicep nomeado 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.

deploymentName='ExampleDeployment'$RANDOM

Ou adicione 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 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.

Próximos passos