Ficheiros de parâmetros extensíveis no Bicep

Ao usar ficheiros de parâmetros Bicep extensíveis, pode definir parâmetros uma vez num ficheiro de parâmetros base e reutilizá-los em múltiplos ficheiros de parâmetros derivados. Esta abordagem melhora significativamente a reutilização dos parâmetros e assegura consistência entre as suas implementações. A versão 0.44.1 da CLI do Bicep e versões posteriores suporta ficheiros de parâmetros extensíveis, juntamente com as palavras-chave extends e base.

Um ficheiro de parâmetros derivado pode estender apenas um ficheiro de parâmetros base. Só pode conter uma extends afirmação. No entanto, pode criar ficheiros de parâmetros aninhados encadeando extensões em vários ficheiros. Para mais informações, consulte Ficheiros de parâmetros aninhados.

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

  • Podes definir variáveis no ficheiro de parâmetros base para calcular os valores dos parâmetros, mas essas variáveis não estão expostas a ficheiros de parâmetros derivados.
  • Pode definir tipos definidos pelo utilizador em ficheiros de parâmetros. Também pode importar tipos definidos pelo utilizador num ficheiro Bicep. No entanto, estes tipos definidos pelo utilizador não estão expostos a ficheiros de parâmetros derivados.
  • Não podes declarar funções definidas pelo utilizador diretamente num ficheiro de parâmetros. No entanto, podes importá-los para um ficheiro de parâmetros. Estas funções não estão expostas a ficheiros de parâmetros derivados.

Expandir ficheiro de parâmetros

Por defeito, os parâmetros que defines num ficheiro de parâmetros derivados sobrescrevem completamente os do ficheiro de parâmetros base. Para intercalar em vez de sobrescrever, use a palavra-chave base com sintaxe de propagação de objetos ou de arrays. Para obter mais informações, consulte Aceder aos parâmetros principais.

Utilize a instrução using none nos ficheiros de parâmetros base para instruir o compilador a não os associar nem validar relativamente a qualquer ficheiro Bicep específico.

O exemplo seguinte demonstra como funcionam os ficheiros de parâmetros extensíveis no Bicep.

O seu modelo principal do Bicep, main.bicep, define os parâmetros que a sua implementação pode aceitar.

param namePrefix string
param location string
param tags object

Um ficheiro de parâmetros base, base.bicepparam, que podes reutilizar em múltiplas implementaçõ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 ficheiro de parâmetros estendido, derived.bicepparam, que se baseia no ficheiro de parâmetros base. Refere-se tanto ao ficheiro Bicep como ao ficheiro de parâmetros base. Os valores que defines aqui sobrepõem-se aos 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 dos parâmetros são aplicados em camadas com uma ordem clara de precedência. O main.bicep ficheiro declara parâmetros e pode fornecer valores por defeito. Um ficheiro derivado.bicepparam pode sobrepor valores definidos num ficheiro base.bicepparam , e os valores finais atribuídos dos parâmetros têm precedência sobre quaisquer valores definidos no modelo de destino. Os valores resolvidos são:

Parâmetro Valor
namePrefix 'Dev'
localização 'westus'
tags { environment: 'prod', owner: 'platform', region: 'westus2' }

Aceder aos parâmetros principais

Para usar a base palavra-chave, o seu ficheiro de parâmetros derivados deve incluir uma extends cláusula. Esta cláusula permite usar base como identificador, permitindo aceder a todos os parâmetros do elemento superior como propriedades. Se tentares usar base sem uma extends cláusula, recebes um erro.

Pode combinar o operador de dispersão (...) com base para estender ou fundir de forma limpa tipos de dados complexos. Esta abordagem permite copiar valores existentes de arrays ou objetos do ficheiro pai e modificá-los sem ter de reescrever toda a estrutura de dados. O operador de dispersão está estritamente limitado a objetos e arrays. Se tentares espalhar um valor primitivo, como uma cadeia, inteiro ou booleano, causas uma falha de compilação.

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

O ficheiro Bicep main.bicep:

param app object
param locations array
param fullName string

O ficheiro de parâmetros base base.bicepparam:

using none

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

O ficheiro 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:

Parâmetro Valor
aplicação {"name":"demo","tags":{"owner":"platform","environment":"prod","costCenter":"1234"}}
locations ["westus","eastus","centralus"]
Nome completo demo-api

Ficheiros de parâmetros aninhados

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

Esta estrutura é útil para organizar implementações empresariais. Podes definir os padrões globais na raiz, sobrepor definições ambientais no nível intermédio e especificar configurações localizadas e específicas de recurso ao nível da folha.

Quando cria uma cadeia, qualquer ficheiro de parâmetros intermédio ou de raiz da sequência tem de incluir a instrução using none. Esta instrução sinaliza ao compilador Bicep que o ficheiro atua estritamente como uma camada de configuração e não se liga diretamente a um template de implementação específico.bicep.

O exemplo seguinte mostra como pode configurar uma cadeia de três níveis para configurar um layout de recursos do Azure, passando das definições globais de organização para um ambiente de desenvolvimento localizado específico.

O ficheiro Bicep (compute.bicep)

param primaryLocation string

param globalTags object 
param environmentTags object
param resourceTags object

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

O nível raiz: padrões globais (global.bicepparam) estabelece as propriedades base usadas em toda a organização. 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'

O nível intermédio: definições de ambiente (dev-defaults.bicepparam) herda as propriedades globais, sobrepõe-se ao tipo de ambiente e acrescenta configurações específicas do ambiente. Como é uma camada intermédia, também utiliza 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 leaf: implementação direcionada (compute.dev.bicepparam) visa a implementação de uma carga de trabalho específica. Liga-se diretamente ao modelo real da infraestrutura Bicep através da instrução padrãousing, 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

  • Última atualização a