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

Os arquivos de parâmetros do Bicep permitem definir valores de parâmetros em um arquivo separado e passá-los para o main.bicep. Eles são perfeitos para valores que variam de acordo com a assinatura, o ambiente ou a região.

Os principais benefícios incluem:

  • Mantenha a consistência entre implantações de IaC (Infraestrutura como Código) e, ao mesmo tempo, habilite a flexibilidade.
  • Permite a otimização de custos, como o dimensionamento adequado de ambientes não produtivos sem alterar a infraestrutura central.
  • Habilite fluxos de CI/CD simplificados mantendo os arquivos de parâmetros no controle de versão e passando o arquivo apropriado para cada etapa de implantação.

Observação

Os arquivos de parâmetros Bicep têm suporte apenas 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.

Você pode utilizar qualquer uma delas:

  • Um arquivo de parâmetros nativo do Bicep (com a extensão .bicepparam) ou
  • Um arquivo de parâmetros JSON padrão.

A extensão do arquivo para um arquivo de parâmetros do bíceps é .bicepparam.

Para implantar em vários ambientes, crie mais de um arquivo de parâmetros. Ao usar 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.

Você pode compilar arquivos de parâmetro Bicep em arquivos de parâmetro JSON que podem ser implantados usando um arquivo Bicep. Para obter mais informações, consulte build-params. Você também pode descompilar um arquivo de parâmetro JSON em um arquivo de parâmetro Bicep. Para obter mais informações, consulte decompile-params.

Warning

Um arquivo de parâmetros salva valores de parâmetros como texto simples. Por motivos de segurança, não use essa abordagem com valores confidenciais, como senhas. Se você precisar passar um parâmetro com um valor confidencial, mantenha o valor em um 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 obter mais informações, veja Usar o Azure Key Vault para passar um segredo como parâmetro durante a implantação do Bicep.

Definir arquivo de parâmetros

Um arquivo de parâmetros usa o seguinte formato:

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

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

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

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. Consulte a seção 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 arquivo de parâmetros, use o nome de cada parâmetro. Os nomes de parâmetro no arquivo de parâmetros devem corresponder àqueles no seu arquivo Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

A instrução using vincula o arquivo de parâmetros do Bicep a um arquivo Bicep. Você pode associar vários arquivos de parâmetro a um único arquivo Bicep. Cada arquivo de parâmetros normalmente se vincula a um arquivo Bicep específico por meio da using instrução.

Use using none se você não quiser vincular o arquivo de parâmetros a um arquivo Bicep específico. Bicep CLI versão 0.31.0 ou posterior dá suporte ao recurso using none.

Para mais informações, veja Usando a instrução.

Quando você digita a palavra-chave param no Visual Studio Code, ele exibe os parâmetros disponíveis e suas descrições do arquivo Bicep vinculado.

Captura de tela da solicitação dos parâmetros disponíveis.

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

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 seu arquivo de parâmetros devem usar os mesmos tipos do seu arquivo Bicep. Nesse exemplo, ambos os tipos de parâmetros são strings:

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Verifique no arquivo Bicep os parâmetros que incluem um valor padrão. Se um parâmetro tiver um valor padrão, você poderá fornecer um valor no arquivo de parâmetros, mas não precisará. 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âmetros: cadeia de caracteres, inteiro, booleano, matriz e objeto.

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 referenciar 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 o Bicep CLI versão 0.21.X ou posterior para usar variáveis ​​em .bicepparam arquivos. Veja os exemplos a seguir:

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
}

Você pode definir tipos de dados definidos pelo usuário. 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

Gerar e criar arquivo de parâmetros

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

A partir do Bicep CLI, você pode criar um arquivo de parâmetros do Bicep em um arquivo de parâmetros JSON. Para obter mais informações, confira Arquivo de parâmetros de build.

Implantar o arquivo Bicep com o arquivo de parâmetros

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

Embora arquivos de parâmetros externos do Bicep não sejam suportados atualmente, você pode usar um arquivo de parâmetros JSON externo fornecendo o URI para o arquivo. Ao usar um arquivo de parâmetros externos, forneça todos os valores de parâmetros no arquivo externo. Ao usar um arquivo externo, você não pode passar outros valores inline ou de um arquivo local, e todos os parâmetros inline são ignorados.

O exemplo a seguir mostra um exemplo de CLI do Azure para usar um arquivo de parâmetros JSON externo:

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 versão 2.53.0 ou posterior da CLI do Azure e a versão 0.22.X ou posterior da CLI do Bicep. Usando a instrução using no arquivo de parâmetros Bicep, você não precisa fornecer a opção --template-file ao especificar um arquivo de parâmetros Bicep para a opção --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, veja Implantar arquivos Bicep usando a CLI do Azure.

Azure PowerShell

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

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, confira Implantar arquivos Bicep com o Azure PowerShell. Para implantar arquivos .bicep, você precisará da versão 5.6.0 ou posterior do Azure PowerShell.

Se o seu 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 seu arquivo Bicep com o sufixo FromTemplate. Por exemplo, se um parâmetro chamado ResourceGroupName no seu arquivo Bicep entrar em conflito com o ResourceGroupName parâmetro no New-AzResourceGroupDeployment cmdlet, você será solicitado a fornecer um valor paraResourceGroupNameFromTemplate. Para evitar essa confusão, use nomes de parâmetros que não são usados para comandos de implantação.

Conteúdo relacionado

  • Last updated on