Compartir a través de

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

Los archivos de parámetros de Bicep permiten definir valores en un archivo individual que luego se pasan al archivo main.bicep. El archivo de parámetros expone valores que pueden cambiar de una suscripción, un entorno o una región determinados. El aprovechamiento de un archivo de parámetros impulsará la coherencia en las implementaciones de IaC, a la vez que proporciona flexibilidad. Algunas de estas flexibilidades podrían permitir que una organización aproveche las ventajas de los costos mediante el ajuste correcto del tamaño de sus entornos que no son de producción, a la vez que se mantiene la misma infraestructura básica.

Estos archivos de parámetros también ayudan a habilitar un enfoque optimizado de implementación de CI/CD. Cada archivo de parámetros está bajo control de código fuente y se pasa a los pasos de implementación automatizados adecuados. Estos archivos de parámetros garantizan una experiencia de implementación coherente.

En este artículo se muestra cómo crear un archivo de parámetros, que puede usar en lugar de pasar parámetros como valores insertados en el script. Puede usar un archivo de parámetros de Bicep con la extensión de archivo .bicepparam o un archivo de parámetros JSON que contenga el valor del parámetro.

Nota:

El archivo de parámetros de Bicep solo se admite en la CLI de Bicep versión 0.18.4 o posterior, la CLI de Azure versión 2.47.0 o posterior y Azure PowerShell versión 9.7.1 o posterior.

Un único archivo de Bicep puede tener varios archivos de parámetros de Bicep asociados. Sin embargo, cada archivo de parámetros de Bicep está diseñado para un archivo de Bicep determinado. Puede establecer esta relación aplicando la instrucción using dentro del archivo de parámetros de Bicep.

Puede compilar archivos de parámetros de Bicep en archivos de parámetros JSON que se pueden implementar usando 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 de Bicep. Para obtener más información, vea decompile-params.

Archivo de parámetros

Un archivo de parámetros usa el siguiente formato:

using '<path>/<file-name>.bicep'

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

Puede aplicar la instrucción using mediante un archivo de Bicep, plantillas JSON de Azure Resource Manager, módulos de Bicep y especificaciones de plantilla. Por ejemplo:

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 obtener más información, consulte Instrucción using.

Puede usar expresiones con el valor predeterminado. 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
}

Nota:

Un archivo de parámetros guarda los valores de parámetro como texto sin formato. Por motivos de seguridad, no se recomienda usar este enfoque con valores confidenciales, como contraseñas.

Si necesita pasar un parámetro con un valor confidencial, debe mantener 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.

Formatos de tipo de parámetro

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.

Nombre del archivo

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

Para realizar la implementación 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.

Definición de los valores de parámetro

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, busque 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 de Bicep a un archivo de Bicep. Para obtener más información, consulte Instrucción using.

Al escribir la palabra clave param en Visual Studio Code, se le mostrarán los parámetros disponibles y sus descripciones del archivo de 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'

Generación del 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.

Compilar un archivo de parámetros 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

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. Con la declaración using del archivo de parámetros de Bicep, no es necesario proporcionar el conmutador --template-file al especificar un archivo de parámetros de Bicep para el conmutador --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.

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

Conflictos de nombres de parámetro

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