Criar arquivos de parâmetros para implantação do Bicep

  • Artigo

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

Observação

O arquivo de parâmetros Bicep só tem suporte na CLI do Bicep versão 0.18.4 ou mais recente, na CLI do Azure versão 2.47.0 ou mais recente e no Azure PowerShell versão 9.7.1 ou mais recente.

Um único arquivo Bicep pode ter vários arquivos de parâmetros Bicep associados a ele. No entanto, cada arquivo de parâmetros Bicep destina-se a um arquivo Bicep específico. Essa relação é estabelecida usando a instrução using dentro do arquivo de parâmetros Bicep.

Você pode compilar arquivos de parâmetros Bicep em arquivos de parâmetros JSON para implantar com um arquivo Bicep. Confira os build-params. Você também pode descompilar um arquivo de parâmetros JSON em um arquivo de parâmetros do Bicep. Confira decompile-params.

Arquivo de parâmetros

Um arquivo de parâmetros usa o seguinte formato:

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

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

Você pode usar a instrução using com o arquivo Bicep, os modelos JSON do ARM, os módulos do Bicep e as especificações de modelo. Por exemplo:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

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

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

Para obter mais informações, confira a Instrução using.

É possível usar as expressões com o valor padrão. 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. CLI do Bicep versão 0.21.X ou superior é necessária para usar variáveis no arquivo .bicepparam. Estes são alguns exemplos:

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
}

É importante observar que o arquivo de parâmetros salva valores de parâmetro como texto sem formatação. Por motivos de segurança, essa abordagem não é recomendada para 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 o valor confidencial ao arquivo de parâmetros, use a função getSecret para recuperá-lo. Para obter mais informações, confira Usar o Azure Key Vault para transmitir um valor de parâmetro seguro durante a implantação do Bicep.

Formatos do tipo de parâmetro

O exemplo a seguir mostra os formatos dos diferentes tipos de parâmetro: 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

O arquivo de parâmetros Bicep tem a extensão de arquivo de .bicepparam.

Para implantar em ambientes diferentes, crie mais de um arquivo de parâmetros. Ao nomear os arquivos de parâmetros, identifique o uso, como desenvolvimento e produção. Por exemplo, use main.dev.bicepparam e main.prod.bicepparampara implantar recursos.

Definir valores de parâmetro

Para determinar como definir os nomes e valores de parâmetro, abra o arquivo Bicep. Examine a seção de parâmetros do arquivo Bicep. Os exemplos a seguir mostram os parâmetros de um arquivo Bicep denominado 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, o primeiro detalhe a ser observado é 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 obter mais informações, confira Como usar a instrução.

Depois de digitar a palavra-chave param no Visual Studio Code, ele solicita 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 de parâmetro, 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.

Observe o tipo de parâmetro. Os tipos de parâmetro no arquivo de parâmetros devem ser iguais àqueles no seu arquivo Bicep. Neste exemplo, ambos os tipos de parâmetro são cadeias de caracteres.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Verifique o arquivo Bicep em busca de parâmetros com 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 é 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 will use default value if not provided.

Verifique os valores permitidos do Bicep e as restrições, como tamanho máximo. Esses valores 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

Para gerar um arquivo de parâmetros, você tem duas opções: por meio do Visual Studio Code ou usando a CLI do Bicep. Ambos os métodos permitem derivar o arquivo de parâmetros de um arquivo Bicep. No Visual Studio Code, confira Gerar arquivo de parâmetros. Na CLI do Bicep, confira Gerar arquivo de parâmetros.

Arquivo de parâmetros de build Bicep

Na CLI do Bicep, você pode criar um arquivo de parâmetros 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âmetro com sua implantação de arquivo Bicep.

Com a CLI do Azure versão 2.53.0 ou posterior e CLI do Bicep versão 0.22.X ou superior, você pode implantar um arquivo Bicep usando um arquivo de parâmetro Bicep. Com a instrução using no Arquivo de parâmetros Bicep, não é necessário fornecer a opção --template-file ao especificar um Arquivo de parâmetro 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, consulte Implantar recursos com o Bicep e a CLI do Azure.

PowerShell do Azure

No Azure PowerShell, transmita um arquivo de parâmetros local 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, consulte Implantar recursos com o Bicep e o Azure PowerShell. Para implantar arquivos .bicep, você precisa do Azure PowerShell versão 5.6.0 ou posterior.

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.

É possível usar um arquivo de parâmetros JSON externo, fornecendo o URI para o arquivo. No momento, não há suporte para o arquivo de parâmetros Bicep externo. Quando você usa um arquivo de parâmetros externo, não é possível transmitir outros valores embutidos ou de um arquivo local. Todos os parâmetros embutidos são ignorados. Forneça todos os valores de parâmetro no arquivo externo.

Conflitos de nome de parâmetro

Se o arquivo Bicep incluir um parâmetro com o mesmo nome de um dos parâmetros no comando do PowerShell, o PowerShell apresentará o parâmetro do arquivo Bicep com o sufixo FromTemplate. Por exemplo, um parâmetro chamado ResourceGroupName no arquivo Bicep entra em conflito com o parâmetro ResourceGroupName no cmdlet New-AzResourceGroupDeployment. Você é 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.

Próximas etapas