Creación de un registro privado para módulos de Bicep

  • Artículo

Para compartir módulos en la organización, puede crear un registro de módulo privado. Después, puede publicar módulos en ese registro y conceder acceso de lectura a los usuarios que necesitan implementar los módulos. Una vez que los módulos se comparten en los registros, puede hacer referencia a ellos desde los archivos de Bicep. Para usar módulos públicos, consulte Módulos de Bicep.

Para trabajar con registros de módulo, debe tener la versión 0.4.1008 o posterior de la CLI de Bicep. Para usarlo con la CLI de Azure, también debe tener la versión 2.31.0 o posterior; para usarlo con Azure PowerShell, también debe tener la versión 7.0.0 o posterior.

Recursos de aprendizaje

Si prefiere información sobre los parámetros mediante instrucciones paso a paso, consulte Uso compartido de módulos de Bicep mediante registros privados.

Configuración de un registro privado

Un registro de Bicep se hospeda en Azure Container Registry (ACR). Siga los pasos que se indican a continuación para configurar el registro para los módulos.

  1. Si ya tiene un registro de contenedor, puede usarlo. Si necesita crear un registro de contenedor, consulte Inicio rápido: Creación de un registro de contenedor mediante un archivo de Bicep.

    Puede usar cualquiera de las SKU de registro disponibles para el registro del módulo. La replicación geográfica del registro proporciona a los usuarios presencia local o una copia de seguridad activa.

  2. Obtenga el nombre del servidor de inicio de sesión. Necesita este nombre al vincular con el registro desde los archivos de Bicep. El formato del nombre del servidor de inicio de sesión es: <registry-name>.azurecr.io.

    Para obtener el nombre del servidor de inicio de sesión, use Get-AzContainerRegistry.

    Get-AzContainerRegistry -ResourceGroupName "<resource-group-name>" -Name "<registry-name>"  | Select-Object LoginServer

  3. Para publicar módulos en un registro, debe tener permiso para insertar una imagen. Para implementar un módulo desde un registro, debe tener permiso para extraer la imagen. Para obtener más información sobre los roles que conceden el acceso adecuado, consulte Roles y permisos de Azure Container Registry

  4. Según el tipo de cuenta que use para implementar el módulo, es posible que tenga que personalizar las credenciales que se usan. Estas credenciales son necesarias para obtener los módulos del registro. De forma predeterminada, las credenciales se obtienen de la CLI de Azure o de Azure PowerShell. Puede personalizar la precedencia para obtener las credenciales en el archivo bicepconfig.json. Para obtener más información, consulte Credenciales para restaurar módulos.

Importante

El registro de contenedor privado solo está disponible para los usuarios con el acceso necesario. Sin embargo, se accede a ella a través de Internet público. Para mayor seguridad, puede requerir acceso mediante un punto de conexión privado. Consulte Conexión privada a un registro de contenedor de Azure mediante Azure Private Link.

El registro de contenedor privado debe tener la directiva azureADAuthenticationAsArmPolicy establecida en enabled. Si azureADAuthenticationAsArmPolicy se estableciera en disabled, recibirá un mensaje de error 401 (no autorizado) al publicar módulos. Consulte Azure Container Registry presenta la directiva de acceso condicional.

Publicación de archivos en el registro

Después de configurar el registro de contenedor, puede publicar archivos en este. Use el comando publish y proporcione los archivos de Bicep que tenga previsto usar como módulos. Especifique la ubicación de destino del módulo en el registro. El comando publicar crea una plantilla de ARM, que se almacena en el registro. Esto significa que si publica un archivo de Bicep que hace referencia a otros módulos locales, estos módulos se expanden completamente como un archivo JSON y se publican en el registro.

Publish-AzBicepModule -FilePath ./storage.bicep -Target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 -DocumentationUri https://www.contoso.com/exampleregistry.html

Con la versión 0.27.1 o posterior de la CLI de Bicep, puede publicar un módulo con el código fuente de Bicep, además de la plantilla JSON compilada. Si un módulo se publica con el código fuente de Bicep en un registro, puede presionar F12 (Ir a la definición) desde Visual Studio Code para ver el código de Bicep. Se requiere la versión 0.27 o posterior de la extensión de Bicep para ver el archivo de Bicep.

Publish-AzBicepModule -FilePath ./storage.bicep -Target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 -DocumentationUri https://www.contoso.com/exampleregistry.html -WithSource

Con el modificador de origen, verá otra capa en el manifiesto:

Captura de pantalla del registro del módulo de Bicep con el código fuente.

Si el módulo de Bicep hace referencia a un módulo en un registro privado, el punto de conexión de ACR está visible. Para ocultar el punto de conexión completo, puede configurar un alias para el registro privado.

Visualización de archivos en el registro

Para ver el módulo publicado en el portal:

  1. Inicie sesión en Azure Portal.

  2. Busque los registros de contenedor.

  3. Seleccione el registro.

  4. Seleccione Servicios ->Repositorios en el menú de la izquierda.

  5. Seleccione la ruta de acceso del módulo (repositorio). En el ejemplo anterior, el nombre de la ruta de acceso del módulo es bicep/modules/storage.

  6. Seleccione la etiqueta. En el ejemplo anterior, la etiqueta es v1.

  7. La referencia del artefacto coincide con la referencia que utiliza en el archivo Bicep.

    Referencia de artefacto del registro del módulo de Bicep

Ya está listo para hacer referencia al archivo del registro desde un archivo de Bicep. Para obtener ejemplos de la sintaxis que se va a usar para hacer referencia a un módulo externo, consulte los Módulos de Bicep.

Trabajar con archivos del registro de Bicep

Al usar archivos bicep hospedados en un registro remoto, es importante comprender cómo interactúa la máquina local con el registro. Cuando declara por primera vez la referencia al registro, el editor local intenta comunicarse con Azure Container Registry y descargar una copia del registro en la memoria caché local.

La caché local se encuentra en:

  • En Windows

    %USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

  • En Linux

    /home/<username>/.bicep

  • En Mac

    ~/.bicep

El equipo local puede reconocer los cambios realizados en el registro remoto hasta que ejecute un restore con el archivo especificado que incluya la referencia del registro.

az bicep restore --file <bicep-file> [--force]

Para más información, consulte el comando restore.

Pasos siguientes