Creación de archivos de parámetros para la implementación de Bicep

  • Artículo

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 los valores de parámetro. En este artículo, se muestra cómo crear archivos de parámetros.

Nota:

El archivo de parámetros de Bicep solo se admite en la versión 0.18.4 o posterior de la CLI de Bicep, 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. Esta relación se establece mediante la instrucción using en el archivo de parámetros de Bicep.

Puede compilar archivos de parámetros de Bicep en archivos de parámetros JSON para implementarlos con un archivo de Bicep. Consulte build-params. También puede descompilar un archivo de parámetros JSON en un archivo de parámetros de Bicep. Consulte 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 usar la instrucción using con el archivo Bicep, las plantillas JSON de ARM, los módulos de Bicep y las especificaciones de plantilla. Por ejemplo:

using './main.bicep'
...

using './azuredeploy.json'
...

using 'br/public:storage/storage-account:3.0.1'
...

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, vea 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. Para usar variables en el archivo .bicepparam, se necesita la versión 0.21X o posterior de la CLI de Bicep. Estos son algunos 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
}

Vale la pena tener en cuenta que el archivo de parámetros guarda los valores del parámetro como texto sin formato. Por motivos de seguridad, este enfoque no se recomienda para valores confidenciales, como contraseñas. Si necesita pasar un parámetro con un valor confidencial, conserve el valor en un almacén de claves. En lugar de agregar el valor confidencial en el archivo de parámetros, use la función getSecret para recuperarlo. Para obtener más información, vea Uso de Azure Key Vault para pasar valores de parámetro seguros 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 de archivo

El archivo de parámetros de Bicep tiene la extensión de archivo de .bicepparam.

Para realizar la implementación en entornos diferentes, cree más de un archivo de parámetros. Cuando asigne un nombre a los archivos de parámetros, identifique su uso, desarrollo y producción. Por ejemplo, use main.dev.bicepparam y main.prod.bicepparam para implementar recursos.

Definición de los valores de parámetro

Para determinar cómo definir los nombres y valores de los parámetros, abra el archivo Bicep. Examine la sección de parámetros del archivo Bicep. En los ejemplos siguientes, se muestran los parámetros del archivo Bicep denominado 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, el primer detalle que se debe tener en cuenta es 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.

Después de escribir la palabra clave param en Visual Studio Code, se le pedirá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 de parámetro, 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.

Tenga en cuenta el tipo del parámetro. Los tipos de parámetros del archivo de parámetros deben usar los mismos tipos que el archivo Bicep. En este ejemplo, ambos tipos de parámetros son cadenas.

using 'main.bicep'

param storagePrefix = ''
param storageAccountType = ''

Compruebe en el archivo Bicep los parámetros con 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 will use default value if not provided.

Compruebe los valores permitidos de Bicep y las restricciones, como la longitud máxima. Esos valores 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

Para generar un archivo de parámetros, tiene dos opciones: a través de Visual Studio Code o mediante la CLI de Bicep. Ambos métodos permiten derivar el archivo de parámetros desde un archivo de Bicep. Desde Visual Studio Code, consulte Generar archivo de parámetros. Desde la CLI de Bicep, consulte Generar archivo de parámetros.

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.

Implementación de un archivo Bicep con un archivo de parámetros

CLI de Azure

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

Con la versión 2.53.0 o posterior de la CLI de Azure y la versión 0.22.X o posterior de la CLI de Bicep, puede implementar un archivo de Bicep mediante un archivo de parámetros de Bicep. Con la instrucción using dentro del archivo de parámetros de Bicep, no es necesario proporcionar el modificador --template-file al especificar un archivo de parámetros de Bicep para el modificador de --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 más información, consulte Implementación de recursos con Bicep y 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 recursos con Bicep y Azure PowerShell. Para implementar archivos .bicep, necesita la versión 5.6.0 o posterior de Azure PowerShell.

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.

Es posible usar un archivo de parámetros JSON externo, proporcionando el URI al archivo. El archivo de parámetros de Bicep externo no se admite actualmente. Cuando se utiliza un archivo de parámetros externo, no se pueden pasar otros valores, tanto si se hace en línea como desde un archivo local. Se omiten todos los parámetros insertados. Proporcione todos los valores de parámetro en el archivo externo.

Conflictos de nombres de parámetro

Si el archivo Bicep incluye un parámetro con el mismo nombre que uno de los parámetros del comando de PowerShell, PowerShell presenta el parámetro del archivo Bicep con el postfijo FromTemplate. Por ejemplo, un parámetro denominado ResourceGroupName en el archivo 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.

Pasos siguientes