Creación y uso de módulos de Bicep

Completado

Los módulos son archivos de Bicep independientes. Normalmente contienen conjuntos de recursos que se implementan juntos. Los módulos se pueden consumir desde cualquier otra plantilla de Bicep.

Mediante el uso de módulos, puede reutilizar fácilmente el código de Bicep y mejorar la legibilidad y la comprensibilidad de los archivos de Bicep, ya que cada uno se centra en un trabajo específico. A continuación, las plantillas principales componen varios módulos juntos.

Ventajas de los módulos

En su empresa de juguetes, ha estado aprovisionando recursos en la nube mediante muchos archivos de Bicep individuales. Con el tiempo, estas plantillas crecen significativamente. Finalmente, acabará teniendo un código monolítico, difícil de leer y de desplazarse por él, incluso más difícil de mantener.

Este enfoque también le obliga a duplicar partes del código cuando quiera reutilizarlo en otras plantillas. Al cambiar algo, debe buscar en varios archivos y actualizarlos.

Los módulos de Bicep ayudan a abordar estos desafíos mediante la división del código en archivos más pequeños y fáciles de administrar a los que varias plantillas pueden hacer referencia. Los módulos le dan algunas ventajas clave.

Reusabilidad

Después de crear un módulo, puede reutilizarlo en varios archivos de Bicep, incluso si los archivos son para diferentes proyectos o cargas de trabajo. Por ejemplo, al compilar una solución, puede crear módulos independientes para los componentes de la aplicación, la base de datos y los recursos relacionados con la red. A continuación, cuando empiece a trabajar en otro proyecto con requisitos de red similares, puede reutilizar el módulo correspondiente.

Incluso puede compartir módulos dentro de su equipo, dentro de su organización o con la comunidad de Azure. Aprenderá más sobre el uso compartido de módulos de Bicep en un módulo futuro de Microsoft Learn.

Encapsulación

Los módulos ayudan a mantener juntas las definiciones de recursos relacionadas. Por ejemplo, al definir una aplicación de Azure Functions, normalmente se implementa la aplicación, un plan de hospedaje para la aplicación y una cuenta de almacenamiento para los metadatos de la aplicación. Estos tres componentes se definen por separado, pero representan una agrupación lógica de recursos, por lo que podría tener sentido definirlos como un módulo.

De esa forma, no es necesario que la plantilla principal conozca los detalles de cómo se implementa una aplicación de funciones. Es responsabilidad del módulo.

Composición

Después de crear un conjunto de módulos, puede componerlos conjuntamente. Por ejemplo, puede crear un módulo que implemente una red virtual y otro módulo que implemente una máquina virtual. Defina los parámetros y las salidas de cada módulo para que pueda tomar la información importante de uno y enviarla al otro.

Sugerencia

Resulta útil pensar en los módulos de Bicep como en bloques de creación que se pueden combinar de diferentes maneras para admitir las implementaciones.

Funcionalidad

En ocasiones, es posible que tenga que usar módulos para acceder a determinadas funcionalidades. Por ejemplo, puede usar módulos y bucles juntos para implementar varios conjuntos de recursos. También puede usar módulos para definir recursos en distintos ámbitos en una sola implementación.

Creación de un módulo

Un módulo es un archivo de Bicep normal. Lo creará igual que cualquier otro archivo de Bicep.

Por lo general, no es un procedimiento recomendado crear un módulo para cada recurso que implemente. Un buen módulo de Bicep normalmente define varios recursos relacionados. Sin embargo, si tiene un recurso especialmente complejo con una gran cantidad de configuración, podría tener sentido crear un solo módulo para encapsular la complejidad. Este enfoque mantiene las plantillas principales simples y ordenadas.

División de una plantilla de Bicep existente en módulos

Puede crear una plantilla de Bicep de gran tamaño y, a continuación, decidir que se debe dividir en módulos. A veces resulta obvio cómo debe dividir un archivo de Bicep grande. Es posible que tenga un conjunto de recursos que pertenecen claramente a un módulo. Otras veces, no es tan sencillo determinar los recursos que se deben agrupar en un módulo.

El visualizador de Bicep puede ayudarle a poner todo el archivo de Bicep en perspectiva. El visualizador se incluye en la extensión de Bicep para Visual Studio Code.

Para ver el visualizador, abra el explorador de Visual Studio Code, mantenga presionado (o haga clic con el botón derecho) el archivo de Bicep y seleccione Abrir visualizador de Bicep. El visualizador muestra una representación gráfica de los recursos en el archivo de Bicep. Incluye líneas entre recursos para mostrar las dependencias que detecta Bicep.

Puede usar el visualizador para ayudarle a dividir los archivos. Considere si la visualización ilustra los clústeres de recursos. Puede que tenga sentido mover conjuntamente estos clústeres a un módulo.

Por ejemplo, considere la siguiente visualización para un archivo de Bicep. Se definen dos conjuntos distintos de recursos. Puede que tenga sentido agruparlos en módulos de base de datos y de redes independientes.

Visualizador

Agrupación

Anidamiento de módulos

Los módulos pueden incluir otros módulos. Mediante esta técnica de anidamiento, puede crear algunos módulos que implementan pequeños conjuntos de recursos y, después, componer estos en módulos más grandes que definen topologías complejas de recursos. Una plantilla combina estas partes en un artefacto que se puede implementar.

Sugerencia

Aunque es posible anidar varias capas de módulos, esto puede volverse complejo. Si recibe un error o algo más sale mal, es más difícil averiguar lo que necesita corregir cuando tiene muchas capas de anidamiento.

En el caso de las implementaciones complejas, a veces tiene sentido usar canalizaciones de implementación para implementar varias plantillas en lugar de crear una sola plantilla que lo haga todo con el anidamiento. Obtendrá más información sobre las canalizaciones de implementación en un módulo futuro de Microsoft Learn.

Elección de nombres de archivo adecuados

Asegúrese de usar un nombre de archivo descriptivo para cada módulo. El nombre de archivo se convierte eficazmente en el identificador del módulo. Es importante que los compañeros puedan comprender el propósito del módulo con tan solo mirar el nombre de archivo.

Uso del módulo en una plantilla de Bicep

Usará un módulo en una plantilla de Bicep mediante la palabra clave module, de esta forma:

module appModule 'modules/app.bicep' = {
  name: 'myApp'
  params: {
    location: location
    appServiceAppName: appServiceAppName
    environmentType: environmentType
  }
}

Una definición de módulo incluye los siguientes componentes:

• La palabra clave module.
• Un nombre simbólico, como appModule. Este nombre se usa dentro de este archivo de Bicep siempre que quiera hacer referencia al módulo. El nombre simbólico nunca aparece en Azure.
• Ruta de acceso del módulo, como modules/app.bicep. Esta suele ser la ruta de acceso a un archivo de Bicep en el sistema de archivos local. En un módulo futuro de Microsoft Learn, aprenderá a compartir módulos mediante registros y especificaciones de plantilla, que tienen sus propios formatos de ruta de acceso de módulo.

  Sugerencia

  También puede usar una plantilla de Azure Resource Manager de JSON (plantilla de ARM) como módulo. Esta capacidad puede ser útil si tiene un conjunto de plantillas que aún no ha migrado a Bicep.

• La propiedad name, que especifica el nombre de la implementación. En la siguiente sección, aprenderá más sobre las implementaciones.
• La propiedad params, donde puede especificar valores para los parámetros que espera el módulo. En la siguiente unidad, aprenderá más sobre los parámetros del módulo.

Cómo funcionan los módulos

No es necesario comprender cómo funcionan los módulos para usarlos, pero puede ayudarle a investigar problemas con las implementaciones o a explicar un comportamiento inesperado.

Implementaciones

En Azure, una implementación es un recurso especial que representa una operación de implementación. Las implementaciones son recursos de Azure que tienen el tipo de recurso Microsoft.Resources/deployments. Al enviar una implementación de Bicep, se crea o actualiza un recurso de implementación. Del mismo modo, al crear recursos en Azure Portal, el portal crea un recurso de implementación en su nombre.

Sin embargo, no todos los cambios en los recursos de Azure crean o usan implementaciones. Por ejemplo, cuando se usa Azure Portal para modificar un recurso existente, por lo general no se crea una implementación para realizar el cambio. Cuando se usan herramientas de terceros como Terraform para implementar o configurar los recursos, es posible que no creen implementaciones.

Al implementar un archivo de Bicep mediante la CLI de Azure o Azure PowerShell, opcionalmente puede especificar el nombre de la implementación. Si no especifica un nombre, la CLI de Azure o Azure PowerShell crean automáticamente un nombre de implementación a partir del nombre de archivo de la plantilla. Por ejemplo, si implementa un archivo denominado main.bicep, el nombre de implementación predeterminado es main.

Cuando se usan módulos, Bicep crea una implementación independiente para cada módulo. La propiedad name que especifique para el módulo se convierte en el nombre de la implementación. Al implementar un archivo de Bicep que contiene un módulo, se crean varios recursos de implementación: uno para la plantilla principal y otro para cada módulo.

Por ejemplo, supongamos que crea un archivo de Bicep denominado main.bicep. Define un módulo denominado myApp. Al implementar el archivo main.bicep, se crean dos implementaciones. La primera se denomina main y crea otra implementación denominada myApp que contiene los recursos de la aplicación.

Puede enumerar y ver los detalles de los recursos de implementación para supervisar el estado de las implementaciones de Bicep o para ver el historial de implementaciones. Sin embargo, cuando se reutiliza el mismo nombre para una implementación, Azure sobrescribe la última implementación con el mismo nombre. Si necesita mantener el historial de implementación, asegúrese de usar un nombre único para cada implementación. Puede incluir la fecha y hora de la implementación en el nombre para ayudar a que sea única.

Plantillas de ARM de JSON generadas

Al implementar un archivo de Bicep, Bicep lo convierte en una plantilla de ARM de JSON. Esta conversión también se denomina transpilación. Los módulos que usa la plantilla se insertan en el archivo JSON. Independientemente del número de módulos que incluya en la plantilla, solo se creará un único archivo JSON.

En el ejemplo que se describe en la sección anterior, Bicep genera un único archivo JSON aunque originalmente había dos archivos de Bicep.