Criar um arquivo de parâmetros para a implantação do Bicep

Os ficheiros de parâmetros Bicep permitem definir valores de parâmetros num ficheiro separado e passá-los ao ficheiro main.bicep. São perfeitos para valores que variam consoante a subscrição, ambiente ou região.

Os principais benefícios incluem:

  • Manter a consistência entre as implementações de Infraestrutura como Código (IaC), permitindo ao mesmo tempo a flexibilidade.
  • Suporta a otimização de custos, como ajustar o tamanho de ambientes não produtivos sem alterar a infraestrutura central.
  • Permitir pipelines CI/CD simplificados mantendo ficheiros de parâmetros no controlo de versões e passando o ficheiro apropriado para cada etapa de implementação.

Nota

Os arquivos de parâmetros do Bicep são suportados somente na CLI do Bicep versão 0.18.4 ou posterior, na CLI do Azure versão 2.47.0 ou posterior e no Azure PowerShell versão 9.7.1 ou posterior.

Pode utilizar qualquer uma das duas opções:

  • Um ficheiro nativo de parâmetros Bicep (extensão .bicepparam), ou
  • Um ficheiro padrão de parâmetros JSON.

A extensão de arquivo para um arquivo de parâmetros Bicep é .bicepparam.

Para implementar em múltiplos ambientes, crie mais do que um ficheiro de parâmetros. Quando você usa vários arquivos de parâmetros, rotule-os de acordo com seu uso. Por exemplo, para implantar recursos, use o rótulo main.dev.bicepparam para desenvolvimento e o rótulo main.prod.bicepparam para produção.

Podes compilar ficheiros de parâmetros Bicep em ficheiros de parâmetros JSON que podes implementar usando um ficheiro Bicep. Para obter mais informações, veja build-params. Também pode descompilar um ficheiro de parâmetros JSON num ficheiro de parâmetros Bicep. Para obter mais informações, veja decompile-params.

Warning

Um arquivo de parâmetros salva valores de parâmetros como texto sem formatação. Por razões de segurança, não use esta abordagem com valores sensíveis como palavras-passe. Se precisares de passar um parâmetro com um valor sensível, mantém esse valor num cofre de chaves. Em vez de adicionar um valor sensível ao seu arquivo de parâmetros, use a getSecret função para recuperá-lo. Para mais informações, consulte Use o Azure Key Vault para passar um segredo como parâmetro durante a implantação do Bicep.

Ficheiro de definição de parâmetros

Um arquivo de parâmetros usa o seguinte formato:

using '<path>/<file-name>.bicep' | using none
extends '<path>/<file-name>.bicepparam' 

type <user-defined-data-type-name> = <type-expression>

var <variable-name> <data-type> = <variable-value>

import {<symbol_name> [as <alias_name>], ...} from '<bicep_file_name>'

param <first-parameter-name> = <first-value>
param <second-parameter-name> = <second-value>
param <third-parameter-name> = <variable-name>

Para determinar como definir nomes e valores de parâmetros, abra o arquivo Bicep. Veja a secção de parâmetros do arquivo Bicep. Os exemplos a seguir mostram os parâmetros de um arquivo Bicep chamado main.bicep:

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

No ficheiro de parâmetros, use o nome de cada parâmetro. Os nomes dos parâmetros no arquivo de parâmetros devem corresponder aos nomes dos parâmetros no arquivo Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

A instrução using associa o ficheiro de parâmetros Bicep a um ficheiro Bicep. Pode associar vários ficheiros de parâmetros a um único ficheiro Bicep. Cada ficheiro de parâmetros normalmente liga a um ficheiro Bicep específico usando a instrução using.

Usa using none se não quiseres ligar o ficheiro de parâmetros a um ficheiro Bicep específico. Bicep CLI versão 0.31.0 ou posterior suporta a funcionalidade using none.

Para obter mais informações, consulte Usando instrução.

A instrução extends herda parâmetros de um ficheiro .bicepparam base, permitindo que os valores dos parâmetros sejam reutilizados e substituídos seletivamente no ficheiro de parâmetros atual. Para mais informações, consulte Ficheiros de parâmetros extensíveis.

Quando escreve a palavra-chave param no Visual Studio Code, são-lhe apresentados os parâmetros disponíveis e as respetivas descrições do ficheiro Bicep associado.

Captura de tela do prompt dos parâmetros disponíveis.

Ao passar o mouse sobre um param nome, você pode ver o tipo de dados e a descrição do parâmetro.

Captura de tela do tipo de dados e descrição do parâmetro.

Revise o tipo de parâmetro, porque os tipos de parâmetro no arquivo de parâmetros devem usar os mesmos tipos que o arquivo Bicep. Neste exemplo, ambos os tipos de parâmetros são cadeias de caracteres:

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Verifique o arquivo Bicep para parâmetros que incluem um valor padrão. Se um parâmetro tiver um valor predefinido, podes fornecer um valor no ficheiro de parâmetros, mas não é necessário. O valor do arquivo de parâmetros substitui o valor padrão do arquivo Bicep.

using 'main.bicep'

param storagePrefix = '' // This value must be provided.
param storageAccountType = '' // This value is optional. Bicep uses default value if not provided.

Para ver se há alguma restrição como comprimento máximo, verifique os valores permitidos do arquivo Bicep. Os valores permitidos especificam o intervalo de valores que você pode fornecer para um parâmetro. Neste exemplo, storagePrefix pode ter no máximo 11 caracteres e storageAccountType deve especificar um valor permitido.

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

O exemplo a seguir mostra os formatos de vários tipos de parâmetro: string, integer, Boolean, array e object.

using './main.bicep'

param exampleString = 'test string'
param exampleInt = 2 + 2
param exampleBool = true
param exampleArray = [
  'value 1'
  'value 2'
]
param exampleObject = {
  property1: 'value 1'
  property2: 'value 2'
}

Use a sintaxe Bicep para declarar objetos e matrizes.

Você pode usar expressões como valores de parâmetro. Por exemplo:

using './main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

Você pode fazer referência a variáveis de ambiente como valores de parâmetro. Por exemplo:

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

Você pode definir e usar variáveis. Você deve usar a Bicep CLI versão 0.21.X ou uma versão posterior para usar variáveis nos .bicepparam arquivos. Veja os exemplos seguintes:

using './main.bicep'

var storagePrefix = 'myStorage'
param primaryStorageName = '${storagePrefix}Primary'
param secondaryStorageName = '${storagePrefix}Secondary'

using './main.bicep'

var testSettings = {
  instanceSize: 'Small'
  instanceCount: 1
}

var prodSettings = {
  instanceSize: 'Large'
  instanceCount: 4
}

param environmentSettings = {
  test: testSettings
  prod: prodSettings
}

Pode definir tipos de dados definidos pelo utilizador. Por exemplo:

using './main.bicep'

// Define a reusable type for tags with optional properties
type TagValues = {
  environment: 'dev' | 'test' | 'production'
  project: string
}

var tagsExample TagValues = {
  environment: 'dev'
  project: 'bicep-sample'
}

param tags = tagsExample

Também pode importar variáveis, tipos de dados definidos pelo utilizador e funções definidas pelo utilizador a partir de um ficheiro Bicep. Para mais informações, consulte Importar.

Ficheiro de parâmetros extensíveis

Para mais detalhes, consulte o ficheiro Estender parámetros.

Gerar e compilar ficheiro de parâmetros

Você pode criar um arquivo de parâmetros usando o Visual Studio Code ou a CLI do Bicep. Ambas as ferramentas permitem que você use um arquivo Bicep para gerar um arquivo de parâmetros. Consulte Gerar arquivo de parâmetros para o método Visual Studio Code e Gerar arquivo de parâmetros para o método Bicep CLI.

A partir da CLI do Bicep, você pode criar um arquivo de parâmetros do Bicep em um arquivo de parâmetros JSON. Para obter mais informações, consulte Arquivo de parâmetros de compilação.

Implantar arquivo Bicep com arquivo de parâmetros

Você pode usar parâmetros embutidos e um arquivo de parâmetros locais na mesma operação de implantação. Por exemplo, você pode especificar alguns valores no arquivo de parâmetros locais e adicionar outros valores embutidos durante a implantação. Se fornecer valores para um parâmetro tanto no ficheiro de parâmetros local como em linha, o valor em linha terá precedência.

Embora os ficheiros de parâmetros externos do Bicep não sejam suportados no momento, pode usar um ficheiro de parâmetros JSON externo fornecendo o URI para o ficheiro. Quando você usa um arquivo de parâmetros externos, forneça todos os valores de parâmetro no arquivo externo. Quando tu usas um arquivo externo, não podes passar outros valores em linha ou de um arquivo local e todos os parâmetros em linha são ignorados.

O exemplo seguinte mostra um exemplo de CLI do Azure para usar um ficheiro externo de parâmetros JSON:

az deployment group create \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters https://storageaccount.blob.core.windows.net/templates/main.parameters.json

CLI do Azure

Na CLI do Azure, você pode passar um arquivo de parâmetros com sua implantação de arquivo Bicep.

Você pode implantar um arquivo Bicep usando um arquivo de parâmetros Bicep com a CLI do Azure versão 2.53.0 ou posterior e a Bicep CLI versão 0.22.X ou posterior. Ao usar a instrução using dentro do ficheiro de parâmetros Bicep, não precisa de fornecer o interruptor --template-file ao especificar um ficheiro de parâmetros Bicep para o interruptor --parameters.

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

Você pode usar parâmetros embutidos e um arquivo de parâmetros de localização na mesma operação de implantação. Por exemplo:

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

Para obter mais informações, consulte Implantar arquivos Bicep usando a CLI do Azure.

Azure PowerShell

No Azure PowerShell, passe um arquivo de parâmetros locais usando o TemplateParameterFile parâmetro.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

Você pode usar parâmetros embutidos e um arquivo de parâmetros de localização na mesma operação de implantação. Por exemplo:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

Para obter mais informações, consulte Implantar arquivos Bicep com o Azure PowerShell. Para implantar .bicep arquivos, você precisa do Azure PowerShell versão 5.6.0 ou posterior.

Se o arquivo Bicep incluir um parâmetro com o mesmo nome de um dos parâmetros no comando do Azure PowerShell, o Azure PowerShell apresentará o parâmetro do arquivo Bicep com o FromTemplate postfix. Por exemplo, se um parâmetro nomeado ResourceGroupName no arquivo Bicep entrar em conflito com o ResourceGroupName parâmetro no New-AzResourceGroupDeployment cmdlet, você será solicitado a fornecer um valor para ResourceGroupNameFromTemplate. Para evitar essa confusão, use nomes de parâmetros que não são usados para comandos de implantação.

Conteúdos relacionados

  • Last updated on