Partilhar via

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

Os arquivos de parâmetros Bicep permitem que você defina valores em um arquivo individual que são passados para o seu main.bicep arquivo. O arquivo de parâmetros expõe valores que podem variar de acordo com uma determinada assinatura, ambiente e/ou região. Aproveitar um arquivo de parâmetros aumentará a consistência em suas implantações de IaC e, ao mesmo tempo, proporcionará flexibilidade. Parte dessa flexibilidade pode permitir que uma organização aproveite os benefícios de custo, dimensionando corretamente seus ambientes não produtivos enquanto mantém a mesma infraestrutura principal.

Esses arquivos de parâmetros 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âmetros garantem uma experiência de implantação consistente.

Este artigo mostra como criar um arquivo de parâmetros, que você pode usar 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 contenha os valores dos parâmetros.

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. O using none recurso é suportado na versão 0.31.0 ou posterior da CLI do Bicep .

Um único arquivo Bicep pode ser associado a vários arquivos de parâmetro. No entanto, cada arquivo de parâmetro normalmente é 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âmetros.

Você pode compilar arquivos de parâmetros do Bicep em arquivos de parâmetros JSON que você pode implantar usando um arquivo Bicep. Para obter mais informações, veja build-params. Você também pode descompilar um arquivo de parâmetros JSON em um arquivo de parâmetros Bicep. Para obter mais informações, veja 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 using instrução usando um ficheiro 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 obter mais informações, consulte Usando 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 separa o arquivo de parâmetros de um modelo específico, permitindo maior flexibilidade na forma como os parâmetros são definidos e usados em todas as implantações. Para obter mais informações, consulte Utilizando uma instrução 'none'.

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

Nota

Um arquivo de parâmetros salva valores de parâmetros como texto sem formatação. Por motivos de segurança, não recomendamos o uso dessa abordagem com valores confidenciais, como senhas.

Se precisar passar um parâmetro com um valor sensível, você deve 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 mais informações, consulte Use o Azure Key Vault para passar um segredo como parâmetro durante a implantação do Bicep.

Formatos de tipo de parâmetro

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.

Nome de ficheiro

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

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

Definir valores de parâmetros

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 arquivo de parâmetros, procure 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 using instrução vincula o arquivo de parâmetros Bicep a um arquivo Bicep. Para obter mais informações, consulte Usando instrução.

Quando você digita 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 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 padrão, você poderá fornecer um valor no arquivo de parâmetros, mas ele não será 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'

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

Construir ficheiro de parâmetros do Bicep

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

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 Azure CLI versão 2.53.0 ou posterior e a Bicep CLI versão 0.22.X ou posterior. Com a declaração using dentro do arquivo de parâmetros Bicep, não há necessidade de fornecer o switch --template-file ao especificar um arquivo de parâmetros Bicep para o switch --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.

Precedência dos 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.

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