Arquivos de parâmetro extensíveis no Bicep

Usando arquivos de parâmetro de Bicep extensíveis, você pode definir parâmetros uma vez em um arquivo de parâmetro base e reutilizá-los em vários arquivos de parâmetro derivados. Essa abordagem melhora significativamente a reutilização de parâmetros e garante a consistência em suas implantações. Bicep CLI versão 0.44.1 e posteriores oferece suporte a arquivos de parâmetros extensíveis, juntamente com as palavras-chave extends e base.

Um arquivo de parâmetro derivado pode estender apenas um arquivo de parâmetro base. Ele pode conter apenas uma extends instrução. No entanto, você pode criar arquivos de parâmetro aninhados encadeando extensões em vários arquivos. Para obter mais informações, consulte arquivos de parâmetro aninhados.

A extends instrução herda apenas atribuições de parâmetro.

• Você pode definir variáveis no arquivo de parâmetro base para calcular seus valores de parâmetro, mas essas variáveis não são expostas a arquivos de parâmetro derivados.
• Você pode definir tipos definidos pelo usuário em arquivos de parâmetro. Você também pode importar tipos definidos pelo usuário presentes em um arquivo Bicep. No entanto, esses tipos definidos pelo usuário não são expostos a arquivos de parâmetro derivados.
• Você não pode declarar funções definidas pelo usuário diretamente em um arquivo de parâmetro. No entanto, você pode importá-los em um arquivo de parâmetros. Essas funções não são expostas a arquivos de parâmetro derivados.

Estender o arquivo de parâmetro

Por padrão, os parâmetros que você define em um arquivo de parâmetro derivado substituem completamente aqueles no arquivo de parâmetro base. Para mesclar em vez de substituir, use a palavra-chave base com sintaxe de espalhamento de objeto ou matriz. Para obter mais informações, consulte os parâmetros pai do Access.

Use a instrução using none em arquivos de parâmetros base para instruir o compilador a não vinculá-los nem validá-los em relação a nenhum arquivo Bicep específico.

O exemplo a seguir demonstra como os arquivos de parâmetro extensíveis funcionam em Bicep.

Seu modelo principal do Bicep, main.bicep, define os parâmetros que sua implantação aceita.

param namePrefix string
param location string
param tags object

Um arquivo de parâmetro base, base.bicepparamque você pode reutilizar em várias implantações e ambientes.

using none
// Notice that the first line of this .bicepparam file declares `using none` which tells the compiler not to validate this against any particular .bicep file.

param namePrefix = 'Prod'
param location = 'westus'
param tags = {
  environment: 'dev'
  owner: 'platform'
}

Um arquivo de parâmetro estendido, derived.bicepparamque se baseia no arquivo de parâmetro base. Ele faz referência ao arquivo Bicep e ao arquivo de parâmetro base. Os valores definidos aqui substituem os anteriores.

using 'main.bicep'

extends 'base.bicepparam'

param namePrefix = 'Dev'
param tags = {
  ...base.tags        // inherit the object from the base file
  environment: 'prod' // override a single property
  region: 'westus2'   // add new data
}

Neste exemplo, os valores de parâmetro são aplicados em camadas com uma ordem clara de precedência. O main.bicep arquivo declara parâmetros e pode fornecer valores padrão. Um arquivo derivado.bicepparam pode substituir valores definidos em um arquivo base.bicepparam e os valores de parâmetro atribuídos finais têm precedência sobre todos os padrões definidos no modelo de destino. Os valores resolvidos são:

Acessar parâmetros pai

Para usar a base palavra-chave, o arquivo de parâmetro derivado deve incluir uma extends cláusula. Esta cláusula permite usar base como identificador, para que você possa acessar todos os parâmetros superiores como propriedades. Se você tentar usar base sem uma extends cláusula, receberá um erro.

Você pode combinar o operador spread (...) com base para estender ou mesclar tipos de dados complexos de maneira simples. Essa abordagem permite copiar valores de matriz ou objeto existentes do arquivo pai e modificá-los sem redigir toda a estrutura de dados. O operador de spread é estritamente limitado a objetos e matrizes. Se você tentar espalhar um valor primitivo, como uma cadeia de caracteres, um inteiro ou um booliano, causará uma falha na compilação.

Todos os valores substituídos devem corresponder ao tipo de dados exato esperado pelo parâmetro de destino. Fornecer um tipo incompatível resulta em um erro de tipo durante a compilação.

O arquivo Bicep main.bicep:

param app object
param locations array
param fullName string

O arquivo de parâmetro base base.bicepparam:

using none

param app = {
  name: 'demo'
  tags: {
    owner: 'platform'
    environment: 'dev'
  }
}
param locations = ['westus', 'eastus']

O arquivo de parâmetros derivado derived.bicepparam:

using './main.bicep'
extends './base.bicepparam'

// Merge objects
param app = {
  ...base.app
  tags: {
    ...base.app.tags
    environment: 'prod'
    costCenter: '1234'
  }
}

// Merge arrays
param locations = [...base.locations, 'centralus']

// Use base in expressions or variables
var suffix = '-api'
param fullName = '${base.app.name}${suffix}'

Os valores resolvidos são:

Arquivos de parâmetro aninhados

Embora um arquivo de parâmetros derivados só possa apresentar uma única extends instrução, Bicep permite criar hierarquias multinível encadeando arquivos de parâmetro sequencialmente (Arquivo de parâmetro A $\rightarrow$ Arquivo de Parâmetro B $\rightarrow$ Arquivo de Parâmetro C).

Essa estrutura é útil para organizar implantações empresariais. Você pode definir padrões globais na raiz, substituir configurações de todo o ambiente na camada intermediária e especificar configurações localizadas e específicas de recursos no nível folha.

Quando você constrói uma cadeia, qualquer arquivo de parâmetros intermediário ou de raiz na sequência deve incluir a instrução using none. Essa instrução sinaliza ao compilador Bicep que o arquivo age estritamente como uma camada de configuração e não se associa diretamente a um modelo de implantação específico.bicep.

O exemplo a seguir mostra como você pode configurar uma cadeia de três camadas para configurar um layout de recurso Azure, passando das configurações da organização global para um ambiente de desenvolvimento localizado específico.

O arquivo Bicep (compute.bicep)

param primaryLocation string

param globalTags object 
param environmentTags object
param resourceTags object

param skuName string
param vmSku string
param vmName string
...

A camada raiz: padrões globais (global.bicepparam) estabelece as propriedades de linha de base usadas em toda a organização. Ele usa using none porque é puramente uma base de configuração.

using none

// Global baseline tags applied to every single resource
param globalTags = {
  BillingUnit: 'Enterprise-IT'
  DataClassification: 'Confidential'
}

// Default regional pair
param primaryLocation = 'eastus'

A camada intermediária: configurações de ambiente (dev-defaults.bicepparam) herda as propriedades globais, substitui o tipo de ambiente e acrescenta configurações específicas do ambiente. Como é uma camada intermediária, ela também usa using none.

using none
extends './global.bicepparam'

// Inherit global tags and inject the environment designation
param environmentTags = {
  ...base.globalTags
  Environment: 'Development'
}

// Override region for low-cost development testing
param primaryLocation = 'westus'

// Tier-specific infrastructure sizes
param skuName = 'Standard_D2s_v5'

A camada folha: a implantação direcionada (compute.dev.bicepparam) tem como destino uma implantação de carga de trabalho específica. Ela se conecta diretamente ao modelo de infraestrutura real do Bicep por meio da instrução using padrão, herdando todo o estado combinado da cadeia.

extends './dev-defaults.bicepparam'
using './compute.bicep' // Binds the final resolved values to the template

// Combine all inherited layers into the final parameters expected by compute.bicep
param resourceTags = {
  ...base.environmentTags
  Workload: 'Web-FrontEnd'
}

// Use inherited environment SKU directly, or override it if needed
param vmSku = base.skuName

// Explicit deployment property
param vmName = 'vm-web-dev-01'

Conteúdo relacionado

• Para saber mais sobre os arquivos de parâmetro do Bicep, consulte arquivo de parâmetro do Bicep.
• Para saber mais sobre using e using none, veja Como usar instruções none.
• Para saber mais sobre o operador de spread, consulte o operador Spread.