Creación de un archivo de parámetros para la implementación de Bicep

Los archivos de parámetros de Bicep permiten definir valores para los parámetros en un archivo independiente y pasarlos a main.bicep. Son perfectos para los valores que varían según la suscripción, el entorno o la región.

Entre las ventajas clave se incluyen las siguientes:

  • Mantenga la coherencia en las implementaciones de infraestructura como código (IaC) al tiempo que permite la flexibilidad.
  • Permite la optimización de costes, como el dimensionamiento adecuado de entornos no productivos sin cambiar la infraestructura principal.
  • Habilite canalizaciones de CI/CD simplificadas manteniendo los archivos de parámetros en el control de código fuente y pasando el archivo adecuado a cada fase de implementación.

Nota:

Los archivos de parámetros de Bicep solo se admiten en la versión 0.18.4 o posterior de la CLI de Bicep, en la versión 2.47.0 o posterior de la CLI de Azure, y en la versión 9.7.1 o posterior de Azure PowerShell.

Puede usar cualquiera de las siguientes opciones:

  • Un archivo de parámetros nativo de Bicep (con la extensión .bicepparam) o
  • Un archivo de parámetros JSON estándar.

La extensión de archivo para un archivo de parámetros de Bicep es .bicepparam.

Para implementar en varios entornos, cree más de un archivo de parámetros. Al usar varios archivos de parámetros, etiquételos según su uso. Por ejemplo, para implementar recursos, use la etiqueta main.dev.bicepparam para el desarrollo y la etiqueta main.prod.bicepparam para producción.

Puede compilar archivos de parámetros Bicep en archivos de parámetros JSON que puede implementar mediante un archivo Bicep. Para obtener más información, vea build-params. También puede descompilar un archivo de parámetros JSON en un archivo de parámetros Bicep. Para obtener más información, vea decompile-params.

Warning

Un archivo de parámetros guarda los valores de parámetro como texto sin formato. Por motivos de seguridad, no use este enfoque con valores confidenciales, como contraseñas. Si debe pasar un parámetro con un valor confidencial, conserve el valor en un almacén de claves. En lugar de agregar un valor confidencial en el archivo de parámetros, use la función getSecret para recuperarlo. Para obtener más información, consulte Uso de Azure Key Vault para pasar un secreto como un parámetro durante la implementación de Bicep.

Definición del archivo de parámetros

Un archivo de parámetros usa el siguiente formato:

using '<path>/<file-name>.bicep' | using none
extends '<path>/<file-name>.bicepparam' 

type <user-defined-data-type-name> = <type-expression>

var <variable-name> <data-type> = <variable-value>

import {<symbol_name> [as <alias_name>], ...} from '<bicep_file_name>'

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

Para determinar cómo definir los nombres y valores de los parámetros, abra el archivo de Bicep. Examine la sección parameters del archivo de Bicep. En los ejemplos siguientes, se muestran los parámetros del archivo de Bicep llamado main.bicep:

@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_ZRS'
  'Premium_LRS'
])
param storageAccountType string = 'Standard_LRS'

En el archivo de parámetros, use el nombre de cada parámetro. Los nombres de los parámetros del archivo de parámetros deben coincidir con los nombres de los parámetros del archivo Bicep.

using 'main.bicep'

param storagePrefix
param storageAccountType

La instrucción using vincula el archivo de parámetros Bicep a un archivo Bicep. Puede asociar varios archivos de parámetros a un único archivo Bicep. Cada archivo de parámetros normalmente se vincula a un archivo Bicep específico mediante la using instrucción .

Use using none si no desea vincular el archivo de parámetros a un archivo de Bicep determinado. La CLI de Bicep versión 0.31.0 o posterior admite la característica using none.

Para obtener más información, consulte Instrucción using.

La extends instrucción hereda los parámetros de un archivo base .bicepparam , lo que permite reutilizar y reemplazar de forma selectiva los valores de parámetro en el archivo de parámetros actual. Para obtener más información, vea Archivos de parámetros extensibles.

Al escribir la palabra clave param en Visual Studio Code, te muestra los parámetros disponibles y sus descripciones del archivo Bicep vinculado.

Captura de pantalla de la consulta de parámetros disponibles.

Al mantener el puntero sobre un nombre param, puede ver el tipo de datos y la descripción del parámetro.

Captura de pantalla del tipo de datos y la descripción del parámetro.

Revise el tipo de parámetro, ya que los tipos de parámetro del archivo de parámetros deben usar los mismos tipos que el archivo de Bicep. En este ejemplo, ambos tipos de parámetros son cadenas:

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Compruebe el archivo de Bicep para ver los parámetros que incluyen un valor predeterminado. Si un parámetro tiene un valor predeterminado, puede proporcionar un valor en el archivo de parámetros, pero no es necesario. El valor del archivo de parámetros reemplaza al valor predeterminado del archivo 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 si hay restricciones, como una longitud máxima, compruebe los valores permitidos del archivo de Bicep. Los valores permitidos especifican el intervalo de valores que puede proporcionar para un parámetro. En este ejemplo, storagePrefix puede tener un máximo de 11 caracteres y storageAccountType debe especificar un valor permitido.

using 'main.bicep'

param storagePrefix = 'storage'
param storageAccountType = 'Standard_ZRS'

En el ejemplo siguiente se muestran los formatos de distintos tipos de parámetros: cadena, entero, booleano, matriz y 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 la sintaxis de Bicep para declarar objetos y matrices.

Puede usar expresiones como valores de parámetro. Por ejemplo:

using './main.bicep'

param storageName = toLower('MyStorageAccount')
param intValue = 2 + 2

Puede hacer referencia a variables de entorno como valores de parámetro. Por ejemplo:

using './main.bicep'

param intFromEnvironmentVariables = int(readEnvironmentVariable('intEnvVariableName'))

Puede definir y usar variables. Debe usar la versión 0.21.X o posterior de la CLI de Bicep para usar variables en archivos .bicepparam. Consulte los siguientes ejemplos:

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
}

Puede definir tipos de datos definidos por el usuario. Por ejemplo:

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

También puede importar variables, tipos de datos definidos por el usuario y funciones definidas por el usuario desde un archivo de Bicep. Para obtener más información, vea Importar.

Archivo de parámetros extensibles

Para obtener más información, consulte Extensión del archivo de parámetros.

Generar y compilar el archivo de parámetros

Puede crear un archivo de parámetros mediante Visual Studio Code o la CLI de Bicep. Ambas herramientas permiten usar un archivo de Bicep para generar un archivo de parámetros. Consulte el archivo de parámetros de generación para el método de Visual Studio Code y el archivo de parámetros de generación para el método de la CLI de Bicep.

Desde la CLI de Bicep, puede compilar un archivo de parámetros de Bicep en un archivo de parámetros JSON. Para más información, consulte Compilación de archivos de parámetros.

Desplegar archivo Bicep con archivo de parámetros

Puede usar parámetros en línea y un archivo de parámetros local en la misma operación de implementación. Por ejemplo, puede especificar algunos valores en el archivo de parámetros local y agregar otros valores en línea durante la implementación. Si proporciona valores para un parámetro en el archivo de parámetros local y en línea, el valor en línea tiene prioridad.

Aunque actualmente no se admiten archivos de parámetros de Bicep externos, puede usar un archivo de parámetros JSON externo proporcionando el identificador URI del archivo. Cuando se usa un archivo de parámetros externos, proporcione todos los valores de parámetro en el archivo externo. Cuando utilizas un archivo externo, no puedes pasar otros valores en línea ni desde un archivo local, y se ignoran todos los parámetros en línea.

En el ejemplo siguiente se muestra un ejemplo de CLI de Azure para usar un archivo de parámetros JSON externo:

az deployment group create \
  --resource-group my-rg \
  --template-file main.bicep \
  --parameters https://storageaccount.blob.core.windows.net/templates/main.parameters.json

CLI de Azure

Desde la CLI de Azure, puede pasar un archivo de parámetros con la implementación del archivo de Bicep.

Puede implementar un archivo de Bicep mediante un archivo de parámetros de Bicep con CLI de Azure versión 2.53.0 o posterior y CLI de Bicep versión 0.22.X o posterior. El uso de la instrucción using dentro del archivo de parámetros de Bicep evita la necesidad de usar el modificador --template-file cuando se especifica un archivo de parámetros de Bicep para el modificador --parameters.

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam

Puede usar parámetros en línea y un archivo de parámetros de ubicación en la misma operación de implementación. Por ejemplo:

az deployment group create \
  --name ExampleDeployment \
  --resource-group ExampleGroup \
  --parameters storage.bicepparam \
  --parameters storageAccountType=Standard_LRS

Para obtener más información, consulte Implementación de archivos de Bicep mediante la CLI de Azure.

Azure PowerShell

Desde Azure PowerShell, pase un archivo de parámetros local mediante el parámetro TemplateParameterFile.

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam

Puede usar parámetros en línea y un archivo de parámetros de ubicación en la misma operación de implementación. Por ejemplo:

New-AzResourceGroupDeployment `
  -Name ExampleDeployment `
  -ResourceGroupName ExampleResourceGroup `
  -TemplateFile C:\MyTemplates\storage.bicep `
  -TemplateParameterFile C:\MyTemplates\storage.bicepparam `
  -storageAccountType Standard_LRS

Para más información, consulte Implementación de archivos de Bicep con Azure PowerShell. Para implementar archivos .bicep, necesita Azure PowerShell versión 5.6.0 o posterior.

Si el archivo de Bicep incluye un parámetro con el mismo nombre que uno de los parámetros del comando de Azure PowerShell, Azure PowerShell presenta el parámetro del archivo de Bicep con el postfijo FromTemplate. Por ejemplo, si un parámetro denominado ResourceGroupName en el archivo de Bicep entra en conflicto con el parámetro ResourceGroupName del cmdlet New-AzResourceGroupDeployment, se le pedirá que proporcione un valor para ResourceGroupNameFromTemplate. Para evitar esta confusión, use nombres de parámetros que no se usan para los comandos de implementación.

Contenido relacionado

  • Last updated on