Archivos de parámetros extensibles en Bicep

Mediante el uso de archivos de parámetros de Bicep extensibles, puede definir parámetros una vez en un archivo de parámetros base y reutilizarlos en varios archivos de parámetros derivados. Este enfoque mejora significativamente la reutilización de parámetros y garantiza la coherencia en las implementaciones. Bicep CLI versión 0.44.1 y versiones posteriores admiten archivos de parámetros extensibles, junto con las extends palabras clave y base .

Un archivo de parámetros derivado solo puede extender un archivo de parámetros base. Puede contener solo una sentencia extends. Sin embargo, puede crear archivos de parámetros anidados encadenando extensiones entre varios archivos. Para obtener más información, consulte Archivos de parámetros anidados.

La extends instrucción hereda solo las asignaciones de parámetros.

• Puede definir variables en el archivo de parámetros base para calcular sus valores de parámetro, pero esas variables no se exponen a los archivos de parámetros derivados.
• Puede definir tipos definidos por el usuario en archivos de parámetros. También puede importar tipos definidos por el usuario de un archivo Bicep. Sin embargo, estos tipos definidos por el usuario no se exponen a los archivos de parámetros derivados.
• No se pueden declarar funciones definidas por el usuario directamente en un archivo de parámetros. Sin embargo, puede importarlos en un archivo de parámetros. Estas funciones no se exponen a archivos de parámetros derivados.

Extensión del archivo de parámetros

De forma predeterminada, los parámetros definidos en un archivo de parámetros derivados sobrescriben completamente los del archivo de parámetros base. Para combinar en lugar de sobrescribir, use la palabra clave base con sintaxis de propagación de objeto o matriz. Para más información, consulte Acceso a parámetros primarios.

Utilice la instrucción using none en los archivos de parámetros base para indicar al compilador que no los vincule ni los valide con ningún archivo Bicep específico.

En el ejemplo siguiente se muestra cómo funcionan los archivos de parámetros extensibles en Bicep.

La plantilla principal de Bicep, main.bicep, define los parámetros que acepta la implementación.

param namePrefix string
param location string
param tags object

Un archivo de parámetros base, base.bicepparam, que puede reutilizar en varias implementaciones y entornos.

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

Un archivo de parámetros extendido, derived.bicepparam, que se basa en el archivo de parámetros base. Hace referencia al archivo Bicep y al archivo de parámetros base. Los valores que defina aquí invalidan los 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
}

En este ejemplo, los valores de parámetro se aplican en capas con un orden claro de prioridad. El main.bicep archivo declara parámetros y puede proporcionar valores predeterminados. Un archivo derivado.bicepparam puede invalidar los valores definidos en un archivo base.bicepparam y los valores de parámetro asignados finales tienen prioridad sobre los valores predeterminados definidos en la plantilla de destino. Los valores resueltos son:

Acceso a parámetros primarios

Para usar la palabra clave base, el archivo de parámetros derivados debe incluir una cláusula extends. Esta cláusula habilita base como identificador, por lo que puede acceder a todos los parámetros padre como propiedades. Si intenta usar base sin una extends cláusula , obtendrá un error.

Puede combinar el operador de propagación (...) con base para ampliar o combinar tipos de datos complejos limpiamente. Este enfoque le permite copiar los valores de matriz o objeto existentes del archivo primario y modificarlos sin volver a ajustar toda la estructura de datos. El operador de propagación se limita estrictamente a objetos y matrices. Si intenta distribuir un valor primitivo, como una cadena, un entero o un valor booleano, se produce un error de compilación.

Todos los valores invalidados deben coincidir con el tipo de datos exacto esperado por el parámetro de destino. Si se proporciona un tipo incompatible, se produce un error de tipo durante la compilación.

El archivo Bicep main.bicep:

param app object
param locations array
param fullName string

El archivo de parámetros base base.bicepparam:

using none

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

El archivo 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}'

Los valores resueltos son:

Archivos de parámetros anidados

Aunque un archivo de parámetros derivado solo puede contener una única instrucción extends, Bicep permite crear jerarquías multinivel encadenando archivos de parámetros de forma secuencial (Archivo de parámetros A $\rightarrow$ Archivo de parámetros B $\rightarrow$ Archivo de parámetros C).

Esta estructura es útil para organizar implementaciones empresariales. Puede definir valores predeterminados globales en la raíz, invalidar la configuración de todo el entorno en el nivel intermedio y especificar configuraciones localizadas específicas de recursos en el nivel hoja.

Al compilar una cadena, cualquier archivo de parámetros intermedio o raíz de la secuencia debe incluir la using none instrucción . Esta instrucción indica al compilador de Bicep que el archivo actúa estrictamente como una capa de configuración y no enlaza directamente a una plantilla de implementación específica.bicep.

En el ejemplo siguiente se muestra cómo puede configurar una cadena de tres niveles para configurar un diseño de recursos de Azure, pasando de la configuración de la organización global a un entorno de desarrollo localizado específico.

El archivo Bicep (compute.bicep)

param primaryLocation string

param globalTags object 
param environmentTags object
param resourceTags object

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

El nivel raíz: los valores predeterminados globales (global.bicepparam) establecen las propiedades de línea base usadas en toda la organización. Usa using none porque es solo una base de configuración.

using none

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

// Default regional pair
param primaryLocation = 'eastus'

El nivel intermedio: la configuración del entorno (dev-defaults.bicepparam) hereda las propiedades globales, invalida el tipo de entorno y anexa configuraciones específicas del entorno. Dado que es una capa intermedia, también 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'

El nivel de hoja: implementación de destino (compute.dev.bicepparam) tiene como destino una implementación de carga de trabajo específica. Se conecta directamente a la plantilla de infraestructura real de Bicep a través de la instrucción estándar using, heredando todo el estado combinado de la cadena.

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'

Contenido relacionado

• Para obtener información sobre los archivos de parámetros de Bicep, consulte archivo de parámetros de Bicep.
• Para obtener información sobre using y using none, consulte Uso de instrucciones none.
• Para obtener información sobre el operador de propagación, consulte Operador de propagación.