Adición y configuración de un catálogo desde GitHub o Azure Repos

En esta guía se explica cómo agregar y configurar un catálogo en el centro de desarrollo de Azure Deployment Environments. Un catálogo es un repositorio hospedado en GitHub o en Azure DevOps.

Los catálogos proporcionan a los equipos de desarrollo un conjunto mantenido de plantillas de infraestructura como código (IaC) denominadas definiciones de entornos.

Deployment Environments admite los catálogos hospedados en Azure Repos (el servicio de repositorio de Azure, comúnmente denominado Azure DevOps) y los catálogos hospedados en GitHub. Azure Repos admite la autenticación mediante la asignación de permisos a una identidad administrada. Azure Repos y GitHub admiten el uso de un token de acceso personal (PAT) para la autenticación. Para proteger mejor sus plantillas, el catálogo está cifrado; Azure Deployment Environments admite el cifrado en reposo con claves de cifrado administradas por la plataforma, que administra Microsoft para servicios de Azure.

• Para obtener información sobre cómo hospedar un repositorio en GitHub, consulte Introducción a GitHub.
• Para obtener información sobre cómo hospedar un repositorio de Git en un proyecto de Azure Repos, consulte Azure Repos.

Microsoft ofrece un catálogo de inicio rápido que se puede agregar al centro de desarrollo y un catálogo de ejemplo que puede usar como repositorio. También puede usar un repositorio propio privado, o puede bifurcar y personalizar las definiciones del entorno en el catálogo de ejemplo.

Configuración de una identidad administrada para el centro de desarrollo

Tras crear un centro de desarrollo, para poder adjuntar un catálogo, es preciso configurar una identidad administrada, también denominada "identidad de servicio administrada" (MSI), para el centro de desarrollo. Puede adjuntar una identidad administrada asignada por el sistema (MSI asignada por el sistema) o una identidad administrada asignada por el usuario (MSI asignada por el usuario). Luego, asigne roles a la identidad administrada para permitir que el centro de desarrollo cree tipos de entorno en la suscripción y lea el proyecto de Azure Repos que contiene el catálogo del repositorio.

Si el centro de desarrollo no tiene un MSI asociado, siga los pasos que se indican en Configuración de una identidad administrada para crear una y asignar roles para la identidad administrada del centro de desarrollo.

Para más información sobre las identidades administradas, consulte ¿Qué son las identidades administradas para los recursos de Azure?

Adición de un catálogo

Los catálogos se pueden agregar desde un repositorio de Azure Repos o un repositorio de GitHub. Puede optar por autenticarse mediante la asignación de permisos a un MSI o mediante un PAT, que se almacena en un almacén de claves.

Seleccione la pestaña del tipo de repositorio y la autenticación que desea usar.

Repositorio de Azure Repos con MSI

Para agregar un catálogo, realice las tareas que se indican a continuación:

• Asigne permisos en Azure Repos para la identidad administrada del centro de desarrollo.
• Agregue el repositorio como catálogo.

Asignación de permisos en Azure Repos para la identidad administrada del centro de desarrollo

Debe conceder permisos de identidad administrada del centro de desarrollo al repositorio en Azure Repos.

1. Inicie sesión en su organización de Azure DevOps.

   Nota:

   La organización de Azure DevOps debe estar en el mismo directorio que la suscripción de Azure que contiene el centro de desarrollo.

2. Seleccione Configuración de la organización.

   

3. En la página Información general, seleccione Usuarios.

   

4. En la página Usuarios, seleccione Agregar usuarios.

   

5. Complete Agregar nuevos usuarios escribiendo o seleccionando la siguiente información y, a continuación, seleccione Agregar:

   NOMBRE	Valor
   Usuarios o entidades de servicio	Escriba el nombre del centro de desarrollo. Si usa una MSI asignada por el sistema, especifique el nombre del centro de desarrollo, no el identificador de objeto de la cuenta administrada. Cuando use una MSI asignada por el usuario, use el nombre de la cuenta administrada.
   Nivel de acceso	Seleccione Básica.
   Agregar a proyectos	Seleccione el proyecto que contenga el repositorio.
   Grupos de Azure DevOps	Seleccione Lectores del proyecto.
   Enviar invitaciones por correo electrónico (solo a usuarios)	Desactive la casilla.

   

Adición del repositorio como catálogo

Azure Deployment Environments admite la asociación de repositorios de Azure Repos y de GitHub. Puede almacenar un conjunto de plantillas de IaC seleccionadas en un repositorio. Asociar el repositorio a un centro de desarrollo como catálogo proporciona a los equipos de desarrollo acceso a las plantillas y les permite crear rápidamente entornos coherentes.

Los siguientes pasos le permiten adjuntar un repositorio de Azure Repos.

1. En Azure Portal, vaya al centro de desarrollo.

2. En el menú de la izquierda, en Configuración del entorno, seleccione Catálogos y, luego, elija Agregar.

   

3. En Agregar catálogo, escriba la siguiente información y seleccione Agregar:

   Campo	Valor
   Nombre	Escriba un nombre para el catálogo.
   Ubicación del catálogo	Seleccione Azure DevOps.
   Tipo de autenticación	Seleccione Identidad administrada.
   Organización	Seleccione la organización de Azure DevOps.
   Proyecto	De la lista de proyectos, seleccione el proyecto que almacena el repositorio.
   Repo	De la lista de repositorios, seleccione el repositorio que desee agregar.
   Rama	Seleccione la rama.
   Folder path (Ruta de acceso a la carpeta)	Dev Box recupera una lista de carpetas de la rama. Seleccione la carpeta que almacena las plantillas de IaC.

   

4. En Catálogos del centro de desarrollo, compruebe que aparece el catálogo. Si la conexión se realiza correctamente, el estado se muestra como Sincronización correcta. La conexión a un catálogo podría tardar unos minutos la primera vez.

Repositorio de Azure Repos con PAT

Para agregar un catálogo, realice las tareas que se indican a continuación:

• Obtenga la dirección URL de clonación de un repositorio de Azure Repos.
• Cree un token de acceso personal (PAT).
• Almacene el PAT como un secreto del almacén de claves en Azure Key Vault.
• Agregue el repositorio como catálogo.

Obtenga la dirección URL de clonación de un repositorio de Azure Repos.

1. Vaya a la página principal de la colección de equipo (por ejemplo, https://contoso-web-team.visualstudio.com) y, después, seleccione el proyecto.

2. Obtenga la dirección URL de clonación del repositorio de Git de Azure Repos.

3. Copie y guarde la URL.

Creación de un token de acceso personal en Azure Repos

1. Vaya a la página principal de la colección de equipo (por ejemplo, https://contoso-web-team.visualstudio.com) y seleccione el proyecto.

2. Cree un PAT.

3. Copie y guarde el token generado para usarlo más adelante.

Creación de un almacén de claves

Necesita una instancia de Azure Key Vault para almacenar el PAT utilizado para otorgar acceso a Azure a su repositorio. Los almacenes de claves pueden controlar el acceso mediante directivas de acceso o control de acceso basado en roles (RBAC). Si tiene un almacén de claves existente, puede usarlo, pero debe comprobar si usa directivas de acceso o asignaciones de RBAC para controlar el acceso. Para obtener ayuda sobre la configuración de una directiva de acceso para un almacén de claves, consulte Asignar una directiva de acceso a un almacén de claves.

Siga estos pasos para crear un almacén de claves de RBAC:

1. Inicie sesión en Azure Portal.

2. En el cuadro de búsqueda, escriba Key Vault.

3. En la lista de resultados, seleccione Key Vault.

4. En la página Key Vault, seleccione Crear.

5. En la pestaña Crear almacén de claves, especifique la siguiente información:

   Nombre	Valor
   Nombre	Escriba un nombre para el almacén de claves.
   Suscripción	Seleccione la suscripción en la que quiere crear el almacén de claves.
   Grupos de recursos	Use un grupo de recursos existente o seleccione Crear nuevo y escriba un nombre para el grupo de recursos.
   Ubicación	Seleccione la ubicación o región en la que quiere crear el almacén de claves.

   Deje las demás opciones con sus valores predeterminados.

6. En la pestaña Directiva de acceso, seleccione Control de acceso basado en roles de Azure y, después, seleccione Revisar y crear.

7. En la pestaña Revisar y crear, seleccione Crear.

Almacenamiento del token de acceso personal en el almacén de claves

1. En el menú de la izquierda de la instancia de Key Vault, seleccione Secretos.

2. En la página Secretos, seleccione Generar o importar.

3. En la página Crear un secreto, haga lo siguiente:

   • En el cuadro Nombre, escriba un nombre descriptivo para el secreto.
   • En el cuadro Valor de secreto, pegue el PAT que copió anteriormente.
   • Seleccione Crear.

Obtención del identificador del secreto

Obtención de la ruta de acceso al secreto que creó en el almacén de claves.

1. En Azure Portal, vaya al almacén de claves.

2. En el menú de la izquierda de la página del almacén de claves, seleccione Secretos.

3. En la página Secretos, seleccione el secreto que ha creado anteriormente.

4. En la página de versiones, seleccione la VERSIÓN ACTUAL.

5. En la página de la versión actual, en el Identificador secreto, seleccione Copiar.

Adición del repositorio como catálogo

1. En Azure Portal, vaya al centro de desarrollo.

2. Asegúrese de que la identidad adjunta al centro de desarrollo tiene acceso al secreto del almacén de claves donde se almacena el token de acceso personal.

3. En el menú de la izquierda, en Configuración del entorno, seleccione Catálogos y, luego, elija Agregar.

4. En Agregar catálogo, escriba la siguiente información y seleccione Agregar:

   Campo	Valor
   Nombre	Escriba un nombre para el catálogo.
   Ubicación del catálogo	Seleccione Azure DevOps.
   Tipo de autenticación	Seleccione Token de acceso personal.
   Organización	Seleccione la organización que hospeda el repositorio de catálogos.
   Proyecto	Seleccione el proyecto que almacena el repositorio de catálogos.
   Repositorio	Seleccione el repositorio que almacena el catálogo.
   Folder path (Ruta de acceso a la carpeta)	Seleccione la carpeta que hospeda las plantillas de IaC.
   Identificador secreto	Escriba el identificador del secreto que contiene el token de acceso personal del repositorio. Al copiar un identificador secreto, la cadena de conexión incluye un identificador de versión al final, como en este ejemplo: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a. Al quitar el identificador de versión, se garantiza que los entornos de implementación capturan la versión más reciente del secreto del almacén de claves. Si su PAT expira, solo debe actualizarse el almacén de claves. Identificador secreto de ejemplo:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat

   

5. En Catálogos del centro de desarrollo, compruebe que aparece el catálogo. Si la conexión se realiza correctamente, el valor de Estado será Conectado.

Aplicación del Centro de desarrollo del repositorio de GitHub

Para agregar un catálogo, realice las tareas que se indican a continuación:

1. Instalación y configuración de la aplicación del Centro de desarrollo de Microsoft
2. Asigne permisos en GitHub para los repositorios.
3. Agregue el repositorio como catálogo.

Instalación de la aplicación del Centro de desarrollo de Microsoft

1. Inicie sesión en Azure Portal.

2. Vaya al centro de desarrollo.

3. En el menú de la izquierda, en Configuración del entorno, seleccione Catálogos y, luego, elija Agregar.

4. En el panel Agregar catálogo, escriba o seleccione lo siguiente:

   Campo	Valor
   Nombre	Escriba un nombre para el catálogo.
   Origen del catálogo	Seleccione GitHub.
   Tipo de autenticación	Seleccione Aplicación de GitHub.

5. Para instalar la aplicación del Centro de desarrollo de Microsoft, seleccione Configurar los repositorios.

   

6. Si se le pide, autentíquese en GitHub.

7. En la página Centro de desarrollo de Microsoft, seleccione Configurar.

   

8. Seleccione la organización de GitHub que contenga el repositorio que quiera agregar como catálogo. Para poder instalar esta aplicación, la organización debe ser de su propiedad.

   

9. En la página Instalar Centro de desarrollo de Microsoft, seleccione Solo determinados repositorios y después el repositorio que quiera agregar como catálogo. A continuación, seleccione Instalar.

   

   Puede seleccionar varios repositorios para agregarlos como catálogos. Debe agregar cada repositorio como catálogo independiente, tal y como se describe en Agregar el repositorio como un catálogo.

10. En la página Microsoft quiere permiso para: del Centro de desarrollo de Microsoft, revise los permisos necesarios y, a continuación, seleccione Autorizar el Centro de desarrollo de Microsoft.

    

Adición del repositorio como catálogo

1. Vuelva a Azure Portal.

2. En Agregar catálogo, escriba la siguiente información y seleccione Agregar:

   Campo	Value
   Repo	Seleccione el repositorio que quiera agregar como catálogo.
   Rama	Seleccione la rama.
   Folder path (Ruta de acceso a la carpeta)	Seleccione la carpeta que contenga las subcarpetas con las definiciones de entorno.

   

3. En Catálogos del centro de desarrollo, compruebe que aparece el catálogo. Si la conexión se realiza correctamente, el estado se muestra como Sincronización correcta.

   

Repositorio de GitHub con PAT

Para agregar un catálogo, realice las tareas que se indican a continuación:

• Obtenga la dirección URL de clonación de un repositorio de GitHub.
• Cree un token de acceso personal (PAT) en GitHub.
• Almacene el PAT como un secreto del almacén de claves en Azure Key Vault.
• Agregue el repositorio como catálogo.

Obtención de la dirección URL de clonación de un repositorio de GitHub

1. Vaya a la página principal del repositorio de GitHub que contiene las definiciones de plantilla.

2. Obtenga la dirección URL de clonación de un repositorio de GitHub.

3. Copie y guarde la URL.

Creación un token de acceso personal en GitHub

Azure Deployment Environments admite la autenticación en repositorios de GitHub mediante tokens clásicos o tokens específicos. En este ejemplo, se crea un token específico.

1. Vaya a la página principal del repositorio de GitHub que contiene las definiciones de plantilla.

2. En la esquina superior derecha de GitHub, seleccione la imagen del perfil y, después, seleccione Configuración.

3. En la barra lateral izquierda, seleccione Configuración de desarrollador>Tokens de acceso personal>Tokens específicos.

4. Seleccione Generar nuevo token.

5. En la página Nuevo token de acceso personal específico, especifique la siguiente información:

   Nombre	Value
   Nombre del token	Escriba un nombre descriptivo para el token.
   Expiración	Seleccione el periodo de expiración del token en días.
   Descripción	Introduzca una descripción para el token.
   Propietario del recurso	Seleccione el propietario del repositorio.
   Acceso a los repositorios	Elige Solo seleccionar repositorios.
   Seleccionar repositorios	Seleccione el repositorio que contiene las definiciones del entorno.
   Permisos del repositorio	Expanda Permisos del repositorio y en Contenido, en la lista Acceso, seleccione Lectura de código.

   

6. Seleccione Generar token.

7. Copie y guarde el token generado para usarlo más adelante.

Importante

Si utiliza un repositorio privado almacenado en una organización de GitHub, debe asegurarse de que el token de acceso personal de GitHub está configurado para conceder acceso a la organización correcta y a los repositorios que contiene.

• Los tokens clásicos de la organización deben tener autorización para el inicio de sesión único en la organización concreta después de crearlos.
• Los tokens específicos deben tener el propietario del token establecido como la propia organización que se va a autorizar.

Los tokens de acceso de red configurados incorrectamente pueden generar el error Repositorio no encontrado.

Creación de un almacén de claves

Necesita una instancia de Azure Key Vault para almacenar el PAT que se usa para conceder al repositorio acceso a Azure. Los almacenes de claves pueden controlar el acceso mediante directivas de acceso o control de acceso basado en roles (RBAC). Si tiene un almacén de claves existente, puede usarlo, pero debe comprobar si usa directivas de acceso o asignaciones de RBAC para controlar el acceso. Para obtener ayuda sobre la configuración de una directiva de acceso para un almacén de claves, consulte Asignación de directivas de acceso a un almacén de claves.

Siga estos pasos para crear un almacén de claves de RBAC:

1. Inicie sesión en Azure Portal.

2. En el cuadro de búsqueda, escriba key vault.

3. En la lista de resultados, seleccione Key Vault.

4. En la página Key Vault, seleccione Crear.

5. En la pestaña Crear almacén de claves, especifique la siguiente información:

   Nombre	Valor
   Nombre	Escriba un nombre para el almacén de claves.
   Suscripción	Seleccione la suscripción en la que quiere crear el almacén de claves.
   Grupos de recursos	Use un grupo de recursos existente o seleccione Crear nuevo y escriba un nombre para el grupo de recursos.
   Ubicación	Seleccione la ubicación o región en la que quiere crear el almacén de claves.

   Deje las demás opciones con sus valores predeterminados.

6. En la pestaña Directiva de acceso, seleccione Control de acceso basado en roles de Azure y, después, seleccione Revisar y crear.

7. En la pestaña Revisar y crear, seleccione Crear.

Almacenamiento del token de acceso personal en el almacén de claves

1. En el menú de la izquierda de la instancia de Key Vault, seleccione Secretos.

2. En la página Secretos, seleccione Generar o importar.

3. En la página Crear un secreto, haga lo siguiente:

   • En el cuadro Nombre, escriba un nombre descriptivo para el secreto.
   • En el cuadro Valor del secreto, pegue el PAT.
   • Seleccione Crear.

Obtención del identificador del secreto

Obtención de la ruta de acceso al secreto que creó en el almacén de claves.

1. En Azure Portal, vaya al almacén de claves.

2. En el menú de la izquierda de la página del almacén de claves, seleccione Secretos.

3. En la página Secretos, seleccione el secreto que ha creado anteriormente.

4. En la página de versiones, seleccione la VERSIÓN ACTUAL.

5. En la página de la versión actual, en el Identificador secreto, seleccione Copiar.

Adición del repositorio como catálogo

1. En Azure Portal, vaya al centro de desarrollo.

2. Asegúrese de que la identidad administrada adjunta al centro de desarrollo tiene acceso al secreto del almacén de claves en el que se almacena el token de acceso personal.

3. En el menú de la izquierda, en Configuración del entorno, seleccione Catálogos y, luego, elija Agregar.

4. En Agregar catálogo, escriba la siguiente información y seleccione Agregar.

   Campo	Valor
   Nombre	Escriba un nombre para el catálogo.
   Ubicación del catálogo	Seleccione GitHub.
   Repo	Escriba o pegue la dirección URL de clonación del repositorio de GitHub o del repositorio de Azure Repos. Ejemplo de catálogo:https://github.com/Azure/deployment-environments.git
   Rama	Escriba la rama del repositorio a la que quiere conectarse. Ejemplo de catálogo:main
   Folder path (Ruta de acceso a la carpeta)	Escriba la ruta de acceso de carpeta relativa al URI de clonación que contiene subcarpetas con las definiciones de entorno. La ruta de acceso de carpeta es para la carpeta con subcarpetas que contienen archivos de entorno de definiciones del entorno, no para la carpeta con el propio archivo de entorno de las definiciones del entorno. Esta imagen muestra la estructura de carpetas del catálogo de ejemplo. Ejemplo de catálogo:/Environments La ruta de acceso de la carpeta puede comenzar con o sin una barra diagonal (/).
   Identificador secreto	Escriba el identificador del secreto que contiene el token de acceso personal del repositorio. Al copiar un identificador secreto, la cadena de conexión incluye un identificador de versión al final, como en este ejemplo: https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat/9376b432b72441a1b9e795695708ea5a. La eliminación del identificador de versión garantiza que Deployment Environments captura la versión más reciente del secreto del almacén de claves. Si su PAT expira, solo debe actualizarse el almacén de claves. Identificador secreto de ejemplo:https://contoso-kv.vault.azure.net/secrets/GitHub-repo-pat

   

5. En Catálogos del centro de desarrollo, compruebe que aparece el catálogo. Si la conexión se realiza correctamente, el estado se muestra como Sincronización correcta.

Actualización de un catálogo

Si actualiza el contenido o la definición de la plantilla en el repositorio adjunto, proporcione el conjunto más reciente de definiciones de entorno a los equipos de desarrollo sincronizando el catálogo.

Para sincronizar un catálogo actualizado en Azure Deployment Environments:

1. En el menú izquierdo del centro de desarrollo, en Configuración del entorno, seleccione Catálogos.

2. Seleccione el catálogo específico y seleccione Sincronizar. El servicio examina el repositorio y hace que la lista más reciente de definiciones de entorno esté disponible para todos los proyectos asociados en el centro de desarrollo.

Eliminación de un catálogo

Puede eliminar un catálogo para quitarlo del centro de desarrollo de Azure Deployment Environments. Las plantillas de un catálogo eliminado no están disponibles para los equipos de desarrollo cuando implementen nuevos entornos. Actualice la referencia de la definición de entorno en los entornos existentes creados mediante las definiciones de entorno del catálogo eliminado. Si la referencia no se actualiza y se vuelve a implementar el entorno, se produce un error en la implementación.

Para eliminar un catálogo:

1. En el menú izquierdo del centro de desarrollo, en Configuración del entorno, seleccione Catálogos.

2. Seleccione el catálogo específico y seleccione Eliminar.

3. En el cuadro de diálogo Eliminar catálogo, seleccione Continuar para eliminar el catálogo.

Errores de sincronización del catálogo

Al agregar o sincronizar un catálogo, es posible que encuentre un error de sincronización. Un error de sincronización indica que algunas de las definiciones de entorno, o todas ellas, tienen errores. Use la CLI de Azure o la API REST para obtener el catálogo. La respuesta de GET muestra el tipo de error:

• Las definiciones duplicadas se omiten.
• Definiciones de entorno no válidas que no se pudieron realizar debido a errores de esquema, referencia o validación.

Resolución de errores de definición de entorno omitidos

Si se agregan dos o más definiciones de entorno que tienen el mismo nombre, se produce un error de definición de entorno omitida. Para resolver este problema, cambie el nombre de las definiciones de entorno para que cada una de ellas tenga un nombre único en el catálogo.

Resolución de errores de definición de entorno no válida

Los errores de definición de entorno no válida puede producirse por varios motivos:

• Errores de esquema de manifiesto. Asegúrese de que el archivo de entorno de la definición del entorno tenga el esquema necesario.

• Errores de validación. Compruebe los siguientes elementos para resolver los errores de validación:

  • Asegúrese de que el tipo de motor del archivo de entorno esté configurado correctamente.
  • Asegúrese de que el nombre de la definición de entorno tenga entre 3 y 63 caracteres.
  • Asegúrese de que el nombre de la definición del entorno solo incluye caracteres válidos para una dirección URL, es decir, caracteres alfanuméricos y estos símbolos: ~!,.';:=-_+()*&$@

• Errores de referencia. Asegúrese de que la ruta de acceso de la plantilla a la que hace referencia el archivo de entorno es una ruta relativa válida a un archivo en el repositorio.

Contenido relacionado

• Configuración de tipos de entorno para centros de desarrollo
• Creación y configuración de un proyecto mediante la CLI de Azure
• Configuración de tipos de entorno de proyecto