Módulos de Bicep

Con Bicep, puede organizar las implementaciones en módulos. Un módulo es un archivo de Bicep que implementa otro archivo de Bicep. Un módulo también puede ser una plantilla de Azure Resource Manager (plantilla de ARM) para JSON. Con los módulos, mejorará la legibilidad de los archivos de Bicep mediante la encapsulación de detalles complejos de la implementación. También puede reutilizar fácilmente módulos para diferentes implementaciones.

Para compartir módulos con otras personas de la organización, cree una especificación de plantilla o registro privado. Las especificaciones de plantilla y los módulos del Registro solo están disponibles para los usuarios con los permisos correctos.

Los módulos de Bicep se convierten en una sola plantilla de ARM con plantillas anidadas. Para obtener más información sobre cómo Bicep resuelve los archivos de configuración y cómo Bicep combina un archivo de configuración definido por el usuario con el archivo de configuración predeterminado, consulte Proceso de resolución de archivos de configuración y Proceso de combinación de archivos de configuración.

Recursos de entrenamiento

Si desea obtener información sobre los módulos a través de instrucciones paso a paso, consulte Creación de archivos Bicep que se pueden componer mediante módulos.

Definición de módulos

La sintaxis básica para definir un módulo es:

@<decorator>(<argument>)
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Un ejemplo sencillo y real tiene el siguiente aspecto:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

También puede usar una plantilla de ARM para JSON como módulo:

module stgModule '../storageAccount.json' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Use el nombre simbólico para hacer referencia al módulo en otra parte del archivo de Bicep. Por ejemplo, puede usar el nombre simbólico para obtener la salida de un módulo. El nombre simbólico puede contener a-z, A-Z, 0-9 y subrayado (_). El nombre no puede empezar con un número. Un módulo no puede tener el mismo nombre que un parámetro, una variable o un recurso.

La ruta de acceso puede ser un archivo local o un archivo en un registro. El archivo local puede ser un archivo de Bicep o una plantilla de ARM para JSON. Para obtener más información, consulte Ruta de acceso a un módulo.

La propiedad name es opcional. Se convierte en el nombre del recurso de implementación anidado en la plantilla generada. Si no se proporciona ningún nombre, se generará un GUID como nombre para el recurso de implementación anidado.

Si un módulo con un nombre estático se implementa simultáneamente en el mismo ámbito, existe la posibilidad de que una implementación interfiera con la salida de la otra implementación. Por ejemplo, si dos archivos de Bicep usan el mismo módulo con el mismo nombre estático (examplemodule) y están destinados al mismo grupo de recursos, una implementación podría mostrar la salida incorrecta. Si le preocupa la implementación simultánea en el mismo ámbito, asigne al módulo un nombre único. Otra manera de asegurarse de que los nombres de módulo únicos es dejar fuera de la propiedad name, se generará automáticamente un nombre de módulo único.

En el ejemplo siguiente se concatena el nombre de la implementación en el nombre del módulo. Si proporciona un nombre único para la implementación, el nombre del módulo también es único.

module stgModule 'storageAccount.bicep' = {
  name: '${deployment().name}-storageDeploy'
  scope: resourceGroup('demoRG')
}

No proporcionar ningún nombre de módulo también es válido. Se generará un GUID como nombre del módulo.

module stgModule 'storageAccount.bicep' = {
  scope: resourceGroup('demoRG')
}

Si necesita especificar un ámbito distinto del ámbito del archivo principal, agregue la propiedad del ámbito. Para obtener más información, consulte Establecimiento del ámbito del módulo.

// deploy to different scope
module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  scope: <scope-object>
  params: {
    <parameter-names-and-values>
  }
}

Para implementar condicionalmente un módulo, agregue una expresión if. Esto es similar a implementar condicionalmente un recurso.

// conditional deployment
module <symbolic-name> '<path-to-file>' = if (<condition-to-deploy>) {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}

Para implementar más de una instancia de un módulo, agregue la expresión for. Use el batchSize decorador para especificar si las instancias se implementan en serie o en paralelo. Para obtener más información, consulte bucles iterativos en Bicep.

// iterative deployment
@batchSize(int) // optional decorator for serial deployment
module <symbolic-name> '<path-to-file>' = [for <item> in <collection>: {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
}]

Al igual que los recursos, los módulos se implementan en paralelo a menos que dependan de otros módulos o recursos. Normalmente, no es necesario establecer dependencias porque se determinan implícitamente. Si necesita establecer una dependencia explícita, agregue dependsOn a la definición del módulo. Para más información sobre las dependencias, consulte Dependencias de recursos en Bicep.

module <symbolic-name> '<path-to-file>' = {
  name: '<linked-deployment-name>'
  params: {
    <parameter-names-and-values>
  }
  dependsOn: [
    <symbolic-names-to-deploy-before-this-item>
  ]
}

Ruta de acceso a un módulo

El archivo del módulo puede ser un archivo local o un archivo externo. El archivo externo puede estar en una especificación de plantilla o en un registro de módulos de Bicep.

Archivo local

Si el módulo es un archivo local, proporcione una ruta de acceso relativa a ese archivo. Todas las rutas de acceso de Bicep deben especificarse mediante el separador de directorios de barra diagonal (/) para garantizar una compilación coherente entre plataformas. No se admite el carácter de barra diagonal inversa de Windows (\). Las rutas de acceso pueden contener espacios.

Por ejemplo, para implementar un archivo que esté en un nivel superior en el directorio desde el archivo principal, use:

module stgModule '../storageAccount.bicep' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Archivo en el registro

Hay registros de módulos públicos y privados.

Registro de módulos públicos

Los módulos comprobados de Azure son módulos precompilados, probados y verificados que puede usar para implementar recursos en Azure. Los empleados de Microsoft crearon y poseen estos módulos. Se diseñaron para simplificar y acelerar el proceso de implementación para configuraciones y recursos comunes de Azure. Los módulos también se alinean con los procedimientos recomendados, como Azure Well-Architected Framework.

Examine Módulos de Bicep para ver la lista de módulos disponibles. Seleccione los números resaltados en la captura de pantalla siguiente para ir directamente a esa vista filtrada:

La lista de módulos muestra la versión más reciente. Seleccione el número de versión para ver una lista de versiones disponibles.

Para vincular a un módulo público, especifique la ruta de acceso del módulo con la sintaxis siguiente:

module <symbolic-name> 'br/public:<file-path>:<tag>' = {}

• br/public: Este es el alias de los módulos públicos. Puede personalizar este alias en el Archivo de configuración de Bicep.
• ruta de acceso del archivo: Puede contener segmentos que se pueden separar con el / carácter.
• etiqueta: Se usa para especificar una versión para el módulo.

Por ejemplo:

module storage 'br/public:avm/res/storage/storage-account:0.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

module <symbolic-name> 'br:mcr.microsoft.com/bicep/<file-path>:<tag>' = {}

Registro de módulo privado

Si ha publicado un módulo en un registro, puede vincularlo a ese módulo. Proporcione el nombre del registro de contenedor de Azure y una ruta de acceso al módulo. Especifique la ruta de acceso del módulo con la sintaxis siguiente:

module <symbolic-name> 'br:<registry-name>.azurecr.io/<file-path>:<tag>' = {

• br: Se trata de un nombre de esquema para un registro de Bicep.
• ruta de acceso del archivo: Se llama repository en Azure Container Registry. La ruta de acceso del archivo puede contener segmentos separados por el carácter /.
• etiqueta: Se usa para especificar una versión para el módulo.

Por ejemplo:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Al hacer referencia a un módulo de un registro, la extensión de Bicep en Visual Studio Code llama bicep restore automáticamente para copiar el módulo externo en la memoria caché local. Se tardan unos minutos en restaurar el módulo externo. Si IntelliSense para el módulo no funciona inmediatamente, espere a que se complete la restauración.

La ruta de acceso completa de un módulo de un registro puede ser larga. En lugar de proporcionar la ruta de acceso completa cada vez que quiera usar el módulo, configure alias en el archivo bicepconfig.json. Los alias facilitan la referencia al módulo. Por ejemplo, con un alias, puede acortar la ruta de acceso a:

module stgModule 'br/ContosoModules:storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

El registro de módulo público tiene un alias predefinido:

module storage 'br/public:avm/res/storage/storage-account:0.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Puede invalidar el alias público en el archivo bicepconfig.json.

Archivo en la especificación de plantilla

Después de crear una especificación de plantilla, vincule a esa especificación de plantilla en un módulo. Especifique la especificación de plantilla en el formato siguiente:

module <symbolic-name> 'ts:<sub-id>/<rg-name>/<template-spec-name>:<version>' = {

Para simplificar el archivo de Bicep, crear un alias para el grupo de recursos que contiene las especificaciones de plantilla. Cuando se usa un alias, la sintaxis se convierte en:

module <symbolic-name> 'ts/<alias>:<template-spec-name>:<version>' = {

En el módulo siguiente se implementa una especificación de plantilla para crear una cuenta de almacenamiento. La suscripción y el grupo de recursos de la especificación de plantilla se definen en el alias denominado ContosoSpecs.

module stgModule 'ts/ContosoSpecs:storageSpec:2.0' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

Usar decoradores

Los decoradores se escriben en el formato @expression y se colocan encima de las declaraciones de módulo. En la tabla siguiente se muestran los decoradores disponibles para los módulos:

Los decoradores están en el espacio de nombres sys. Si necesita diferenciar un decorador de otro elemento con el mismo nombre, antepone el decorador con sys. Por ejemplo, si el archivo de Bicep incluye un parámetro denominado description, debe agregar el sys espacio de nombres al usar el description decorador.

Tamaño de lote

Solo se puede aplicar @batchSize() a un recurso o definición de módulo que use una for expresión.

De forma predeterminada, los módulos se implementan en paralelo. Cuando agrega el decorador @batchSize(int), implementa las instancias en serie.

@batchSize(3)
module storage 'br/public:avm/res/storage/storage-account:0.11.1' = [for storageName in storageAccounts: {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}]

Para obtener más información, consulte Implementación en lotes.

Descripción

Para agregar una explicación, agregue una descripción a las declaraciones del módulo. Por ejemplo:

@description('Create storage accounts referencing an AVM.')
module storage 'br/public:avm/res/storage/storage-account:0.18.0' = {
  name: 'myStorage'
  params: {
    name: 'store${resourceGroup().name}'
  }
}

Puede usar texto con formato Markdown para el texto de descripción.

Parámetros

Los parámetros que proporcione en la definición del módulo coinciden con los parámetros del archivo de Bicep.

El ejemplo de Bicep siguiente tiene tres parámetros: storagePrefix, storageSKU, y ___location. El storageSKU parámetro tiene un valor predeterminado, por lo que no es necesario proporcionar un valor para ese parámetro durante la implementación.

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param ___location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  ___location: ___location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Para usar el ejemplo anterior como módulo, proporcione valores para esos parámetros.

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    ___location: demoRG.___location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Establecimiento del ámbito del módulo

Al declarar un módulo, establezca un ámbito para el módulo que sea diferente del ámbito del archivo de Bicep que lo contiene. Use la propiedad scope para establecer el ámbito del módulo. Cuando no se proporciona la scope propiedad, el módulo se implementa en el ámbito de destino del elemento primario.

El siguiente archivo de Bicep crea un grupo de recursos y una cuenta de almacenamiento en ese grupo de recursos. El archivo se implementa en una suscripción, pero el ámbito del módulo es el grupo de recursos nuevo.

// set the target scope for this file
targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

param ___location string = deployment().___location

var resourceGroupName = '${namePrefix}rg'

resource newRG 'Microsoft.Resources/resourceGroups@2024-03-01' = {
  name: resourceGroupName
  ___location: ___location
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: newRG
  params: {
    storagePrefix: namePrefix
    ___location: ___location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

En el ejemplo siguiente se implementan cuentas de almacenamiento en dos grupos de recursos diferentes. Ambos grupos de recursos ya deben existir.

targetScope = 'subscription'

resource firstRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

resource secondRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup2'
}

module storage1 '../create-storage-account/main.bicep' = {
  name: 'westusdeploy'
  scope: firstRG
  params: {
    storagePrefix: 'stg1'
    ___location: 'westus'
  }
}

module storage2 '../create-storage-account/main.bicep' = {
  name: 'eastusdeploy'
  scope: secondRG
  params: {
    storagePrefix: 'stg2'
    ___location: 'eastus'
  }
}

Establezca la scope propiedad en un objeto de ámbito válido. Si el archivo de Bicep implementa un grupo de recursos, una suscripción o un grupo de administración, puede establecer el ámbito de un módulo en el nombre simbólico de ese recurso. O bien, puede usar las funciones de ámbito para obtener un ámbito válido.

Estas funciones son:

• resourceGroup
• suscripción
• managementGroup
• inquilino

En el ejemplo siguiente se usa la función managementGroup para establecer el ámbito.

param managementGroupName string

module mgDeploy 'main.bicep' = {
  name: 'deployToMG'
  scope: managementGroup(managementGroupName)
}

Salida

Puede obtener valores de un módulo y usarlos en el archivo de Bicep principal. Para obtener un valor de salida de un módulo, use la propiedad outputs en el objeto module.

En el primer ejemplo se crea una cuenta de almacenamiento y se devuelven los puntos de conexión principales:

@minLength(3)
@maxLength(11)
param storagePrefix string

@allowed([
  'Standard_LRS'
  'Standard_GRS'
  'Standard_RAGRS'
  'Standard_ZRS'
  'Premium_LRS'
  'Premium_ZRS'
  'Standard_GZRS'
  'Standard_RAGZRS'
])
param storageSKU string = 'Standard_LRS'

param ___location string

var uniqueStorageName = '${storagePrefix}${uniqueString(resourceGroup().id)}'

resource stg 'Microsoft.Storage/storageAccounts@2023-04-01' = {
  name: uniqueStorageName
  ___location: ___location
  sku: {
    name: storageSKU
  }
  kind: 'StorageV2'
  properties: {
    supportsHttpsTrafficOnly: true
  }
}

output storageEndpoint object = stg.properties.primaryEndpoints

Cuando la propiedad se usa como módulo, puede obtener ese valor de salida:

targetScope = 'subscription'

@minLength(3)
@maxLength(11)
param namePrefix string

resource demoRG 'Microsoft.Resources/resourceGroups@2024-03-01' existing = {
  name: 'demogroup1'
}

module stgModule '../create-storage-account/main.bicep' = {
  name: 'storageDeploy'
  scope: demoRG
  params: {
    storagePrefix: namePrefix
    ___location: demoRG.___location
  }
}

output storageEndpoint object = stgModule.outputs.storageEndpoint

Con la versión 0.35.1 de Bicep y posteriores, el decorador @secure() se puede aplicar a las salidas del módulo para marcarlas como sensibles, lo que garantiza que sus valores no se exponen en registros o historial de implementación. Esto resulta útil cuando un módulo necesita devolver datos confidenciales, como una clave generada o una cadena de conexión, al archivo primario de Bicep sin riesgo de exposición. Para obtener más información, consulte Salidas seguras.

Contenido relacionado

• Para ver un tutorial, consulte Compilar el primer archivo de Bicep.
• Para pasar un valor confidencial a un módulo, use la funcióngetSecret.