Share via

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. Los módulos se publican en ese registro y se proporciona acceso de lectura a los usuarios que necesitan implementarlos. Una vez que los módulos se comparten en los registros, puede hacer referencia a ellos desde los archivos de Bicep. Para contribuir al registro de módulos públicos, consulte la guía de contribución.

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 publish creará una plantilla de ARM que se almacenará en el registro. Esto significa que si publica un archivo Bicep que hace referencia a otros módulos locales, estos módulos se expandirán completamente como un archivo JSON y se publicarán 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

Cuando cambie a código fuente, verá una capa adicional en el manifiesto:

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

Tenga en cuenta que si el módulo de Bicep hace referencia a un módulo en un registro privado, el punto de conexión de ACR será 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 de artefacto coincide con la referencia que usará en el archivo de 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 aprovechar los archivos de Bicep hospedados en un registro remoto, es importante comprender cómo interactuará la máquina local con el registro. Cuando declare por primera vez la referencia al registro, el editor local intentará 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 no reconocerá los cambios realizados en el registro remoto hasta que se haya ejecutado 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