Como implementar recursos com a Bicep e a Azure CLI

Este artigo explica como usar o Azure CLI com ficheiros Bicep para implantar os seus recursos no Azure. Se não está familiarizado com os conceitos de implantação e gestão das suas soluções Azure, consulte a visão geral da Bicep.

Pré-requisitos

Precisa de um ficheiro Bicep para ser implantado. O ficheiro deve ser local.

Precisa do Azure CLI e de estar ligado ao Azure:

  • Instale os comandos Azure CLI no seu computador local. Para implementar ficheiros Bicep, precisa da versão 2.20.0 ou posterior do Azure CLI.
  • Ligue-se ao Azure utilizando o login az. Se tiver várias subscrições do Azure, também poderá ter de executar a conta az.

As amostras para o Azure CLI são escritas para a bash concha. Para executar esta amostra em Windows PowerShell ou Solicitação de Comando, poderá ter de alterar elementos do script.

Se não tiver o Azure CLI instalado, pode utilizar o Azure Cloud Shell. Para obter mais informações, consulte ficheiros Bicep de 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, é necessário Microsoft.Compute/virtualMachines/write e Microsoft.Resources/deployments/* permissões. A operação "e se" tem os mesmos requisitos de permissão.

Para obter uma lista de funções e permissões, veja Funções incorporadas do Azure.

Âmbito de implantação

Pode direcionar a sua implementação para um grupo de recursos, subscrição, grupo de gestão ou inquilino. Dependendo do âmbito de implantação, utiliza-se diferentes comandos.

Para cada âmbito, o utilizador que implementa o ficheiro Bicep deve ter as permissões necessárias para criar recursos.

Implementar o arquivo Bicep local

Pode colocar um ficheiro Bicep na sua máquina local ou um que seja armazenado externamente. Esta secção descreve a implantação de um ficheiro Bicep local.

Se estiver a implantar para 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, períodos, sublinhados, hífens e parênteses. Pode ser até 90 caracteres. O nome não pode acabar num período.

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

Para implantar um ficheiro Bicep local, utilize o --template-file parâmetro 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 implementação pode demorar alguns minutos a concluir. Quando terminar, vê-se uma mensagem que inclui o resultado:

"provisioningState": "Succeeded",

Implementar ficheiro Bicep remoto

Atualmente, o Azure CLI não suporta a implementação de ficheiros Bicep remotos. Pode utilizar o CLI Bicep para construir o ficheiro Bicep num modelo JSON e, em seguida, carregar o ficheiro JSON para a localização remota.

Parâmetros

Para passar valores de parâmetros, pode utilizar parâmetros inline ou um ficheiro de parâmetros.

Parâmetros inline

Para passar parâmetros inline, forneça os valores em parameters. Por exemplo, para passar uma corda e matriz para um ficheiro Bicep numa concha bash, use:

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

Se estiver a utilizar o Azure CLI com o Windows Command Prompt (CMD) ou o PowerShell, passe a matriz no formato: exampleArray="['value1','value2']".

Também pode obter o conteúdo do ficheiro e fornecer esse conteúdo como um parâmetro inline. Prefacie o nome do ficheiro 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 ficheiro é útil quando é necessário fornecer valores de configuração. Por exemplo, pode fornecer valores de inição de nuvem para uma máquina virtual Linux.

O formato arrayContent.json é:

[
    "value1",
    "value2"
]

Para passar num objeto, por exemplo, para definir tags, use JSON. Por exemplo, o seu ficheiro Bicep pode incluir um parâmetro como este:

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

Neste caso, pode passar numa cadeia JSON para definir o parâmetro como 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 citações duplas em torno do JSON que pretende passar para o objeto.

Se estiver a utilizar o Azure CLI com o Windows Command Prompt (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

Pode utilizar uma variável para conter os valores dos parâmetros. Em Bash, desa um ponto de vista da variável para todos os valores dos parâmetros 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 estiver a utilizar o Azure CLI com o Windows Command Prompt (CMD) ou o PowerShell, desapedaça a variável para uma cadeia JSON. Escapar às aspas: $params = '{ \"prefix\": {\"value\":\"start\"}, \"suffix\": {\"value\":\"end\"} }'.

Ficheiros de parâmetros

Em vez de transmitir parâmetros como valores inline no seu script, poderá considerar mais fácil utilizar um ficheiro JSON que contenha os valores dos parâmetros. O ficheiro do parâmetro deve ser um ficheiro local. Os ficheiros de parâmetros externos não são suportados com o Azure CLI. O ficheiro Bicep utiliza ficheiros de parâmetros JSON.

Para obter mais informações sobre o ficheiro de parâmetros, veja Criar ficheiro de parâmetros do Resource Manager.

Para passar um ficheiro de parâmetro local, especifique o caminho e o nome do ficheiro. O exemplo a seguir mostra um ficheiro de parâmetro chamado storage.parameters.json. O ficheiro 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

Pré-visualizar alterações

Antes de implementar o seu ficheiro Bicep, pode visualizar as alterações que o ficheiro Bicep irá fazer para o seu ambiente. Utilize a operação "e se" para verificar se o ficheiro Bicep faz as alterações que espera. E se também valida o ficheiro Bicep por erros.

Implementar especificações de modelo

Atualmente, o Azure CLI não suporta a criação de especificações de modelos fornecendo ficheiros Bicep. No entanto, pode criar um ficheiro Bicep com o recurso Microsoft.Resources/templateSpecs para implementar uma especificação de modelo. A amostra de especificação do modelo Create mostra como criar uma especificação de modelo num ficheiro Bicep. Também pode construir o seu ficheiro Bicep para JSON usando o Bicep CLI e, em seguida, criar uma especificação de modelo com o modelo JSON.

Nome de implantação

Ao implementar um ficheiro Bicep, pode dar um nome à implantação. Este nome pode ajudá-lo a recuperar a implantação do histórico de implantação. Se não fornecer um nome para a implantação, o nome do ficheiro Bicep é usado. Por exemplo, se implementar um ficheiro Bicep nomeado main.bicep e não especificar um nome de implantação, a implementação é nomeada main.

Sempre que executar uma implantação, uma entrada é adicionada ao histórico de implantação do grupo de recursos com o nome de implantação. Se executar outra implantação e lhe der o mesmo nome, a entrada anterior é substituída pela implementação atual. Se pretender manter entradas únicas no histórico de implantação, dê a cada implementação um nome único.

Para criar um nome único, pode atribuir um número aleatório.

deploymentName='ExampleDeployment'$RANDOM

Ou adicionar um valor de data.

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

Se executar implementações simultâneas para o mesmo grupo de recursos com o mesmo nome de implantação, apenas a última implementação é concluída. Quaisquer implementações com o mesmo nome que não tenham terminado são substituídas pela última implementação. Por exemplo, se executar uma implantação com o nome newStorage de uma conta de armazenamento chamada storage1, e ao mesmo tempo executar outra implantação com o nome newStorage de uma conta de armazenamento chamada storage2, implementa apenas uma conta de armazenamento. A conta de armazenamento resultante é nomeada storage2.

No entanto, se executar uma implementação com o nome newStorage que implementa uma conta de armazenamento chamada storage1, e imediatamente após a sua conclusão, executar outra implantação com o nome newStorage de uma conta de armazenamento chamada storage2, então tem duas contas de armazenamento. Um tem o nome storage1, e o outro chama-se storage2. Mas só tens uma entrada na história da implantação.

Quando especificar um nome único para cada implantação, pode executá-los simultaneamente sem conflitos. Se executar uma implantação com o nome newStorage1 de uma conta de armazenamento chamada storage1, e ao mesmo tempo executar outra implantação com o nome newStorage2 de uma conta de armazenamento , storage2então tem duas contas de armazenamento e duas entradas no histórico de implantação.

Para evitar conflitos com implementações simultâneas e para garantir entradas únicas no histórico de implantação, dê a cada implementação um nome único.

Passos seguintes