Compartilhar via

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

Os arquivos de parâmetro Bicep permitem definir valores em um arquivo individual que, em seguida, são passados para o arquivo main.bicep. O arquivo de parâmetro expõe valores que podem mudar de uma determinada assinatura, ambiente e/ou região. Aproveitar um arquivo de parâmetro gerará consistência em suas implantações de IaC, ao mesmo tempo em que fornecerá flexibilidade. Parte dessa flexibilidade pode permitir que uma organização aproveite os benefícios de custo dimensionando corretamente seus ambientes de não produção, mantendo a mesma infraestrutura principal.

Esses arquivos de parâmetro também ajudam a habilitar uma abordagem simplificada de implantação de CI/CD. Cada arquivo de parâmetro está sob controle do código-fonte e passado para as etapas de implantação automatizadas apropriadas. Esses arquivos de parâmetro garantem uma experiência de implantação consistente.

Esse artigo mostra como criar um arquivo de parâmetros, que você pode usar em vez de passar parâmetros como valores embutidos no seu script. Você pode usar um arquivo de parâmetros Bicep com a extensão .bicepparam ou um arquivo de parâmetros JSON que contém o valor do parâmetro.

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. O using none recurso é compatível com a CLI do Bicep versão 0.31.0 ou posterior.

Um único arquivo Bicep pode ser associado a vários arquivos de parâmetro. No entanto, cada arquivo de parâmetro normalmente está vinculado a um arquivo Bicep específico, a menos que using none seja especificado. Essa associação é estabelecida usando a using instrução dentro do arquivo de parâmetro.

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

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>

Você pode aplicar a instrução using usando um arquivo Bicep, modelos JSON do Azure Resource Manager, módulos Bicep e especificações de modelo. Por exemplo:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:avm/res/storage/storage-account:0.9.0' 
...

using 'br:myacr.azurecr.io/bicep/modules/storage:v1'
...

using 'ts:00000000-0000-0000-0000-000000000000/myResourceGroup/storageSpec:1.0'
...

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

Você pode aplicar a using none instrução para indicar que o arquivo de parâmetros não está vinculado a um modelo Bicep específico durante a criação ou compilação. Isso desassocia o arquivo de parâmetro de um modelo específico, permitindo maior flexibilidade em como os parâmetros são definidos e usados entre implantações. Para obter mais informações, consulte Usando nenhuma instrução.

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

Observação

Um arquivo de parâmetros salva valores de parâmetros como texto simples. Por motivos de segurança, não recomendamos usar essa abordagem com valores confidenciais, como senhas.

Se você precisar passar um parâmetro com um valor confidencial, deverá manter 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.

Formatos de tipos de parâmetros

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.

Nome do arquivo

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.

Definir valores de parâmetro

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, procure 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 Bicep a um arquivo Bicep. 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 no 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 isso não é obrigató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'

Gerar 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.

Arquivo de parâmetros de build Bicep

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

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. Com a instrução using no arquivo de parâmetros do Bicep, não é necessário fornecer a opção --template-file ao especificar um arquivo de parâmetros do 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.

Precedência de parâmetro

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.

Conflitos de nome de parâmetro

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