Nota: este es un tema algo más avanzado sobre Servicios de Entrega en Edge y Autoría de Documentos. Para una introducción sobre EDS y Creación de Documentos, por favor, consulta esto primero para contexto.

Antecedentes sobre las configuraciones y el servicio de configuración de entrega de borde de AEM basados en archivos

Cuando Adobe lanzó por primera vez Edge Delivery Services (o Helix, como se le conoce internamente), toda la configuración principal a nivel del sitio se realizaba mediante archivos de configuración registrados en el repositorio del sitio. Desplegar una nueva configuración se hacía enviando a la main rama del repositorio, que enviaba esa configuración activa en el sitio. Una desventaja de esto era que cualquier repositorio tenía que estar vinculado directamente a un sitio y a un repositorio de documentos. No podrías entonces tener un único repositorio de código que maneje varios sitios, ni siquiera varias versiones de un mismo sitio (como entornos de estilo dev/stg/prd para contenido o configuración staging).

Como resultado de esto, y otras preocupaciones técnicas, Adobe ha estado avanzando hacia un nuevo diseño arquitectónico basado en el Servicio de Configuración. En este paradigma, Adobe almacena y versiona centralizadamente las configuraciones en su Servicio de Configuración impulsado por API, y una vez migrado a este servicio, los archivos de tu proyecto Edge Delivery dejarán de tener ningún efecto en el sitio.

Requisitos previos para pasar al servicio de configuración

Como se ha señalado en https://www.aem.live/docs/config-service-setup#prerequisites, antes de empezar el traslado a Config Service, primero debes asegurarte de que tu usuario de Adobe esté asignado como administrador de tu organización en Github, para que tengas autoridad en el Config Service para hacer cambios. Tu contacto técnico de Adobe con el que normalmente tratas debería poder ponerte en contacto con esto.

Endpoints y superficies de configuración afectados por un movimiento a servicio de configuración

Esto afecta a las siguientes superficies de configuración en un proyecto de Entrega de Aristas:

• Mapeo del bus de contenido: La configuración en /fstab.yaml donde el proyecto se mapea a una ubicación ya sea en DA (o en otro lugar, como AEM/Universal Editor o Sharepoint) ahora está en el Servicio de Configuración. Este es el punto más crítico que permite que un solo repositorio maneje múltiples sitios (anteriormente conocido como configuración "sin repo", ya que significaba que el repositorio de código y el repositorio de contenido no estaban inextricablemente vinculados).

• Índices de consulta: La configuración de índices para todos los lenguajes se almacenaba previamente en el proyecto en /helix-query.yaml

• Configuración del mapa del sitio: La configuración del mapa del sitio que antes se creaba en /helix-sitemap.yaml ahora estará en el Servicio de Configuración.

• Configuración de Sidekick: Existen dos tipos diferentes de configuraciones de Sidekick que antes se guardaban en el proyecto git, pero que ahora están en otros lugares.

  • Plugins DA: Antes, en los primeros días de DA, manteníamos los plugins de DA en el archivo /tools/sidekick/config.json del repositorio de código. Esto sería para cosas como las diversas mejoras de la interfaz de DA como nuestro selector de fechas, el plugin de etiquetas AEM, etc. Esto ahora se guarda en la hoja de Library en la configuración de DA dentro del propio DA, en lugar de en la base de código.
  • Plugins/Configuración de Sidekick: Otras configuraciones de AEM Sidekick, como la configuración para Quick Edit o para AEM Experimentation, ahora se mantienen directamente en el servicio de configuración, en lugar de en DA. La configuración de Sidekick en el proyecto GIT de EDS ya no tendrá ningún efecto.

• Configuración de encabezados HTTP: Esto se mantenía antes en la hoja de headers de DA, pero ahora se enviará al servicio de configuración. Esto es para configuraciones de CORS, como poner un encabezado de access-control-allow-origin en ciertos hosts.

• Autenticación de Vista Previa/Publicación Helix: Para el control de acceso autenticado a Vista previa/Publicación, hemos estado usando un modelo de autenticación basado en hojas, donde tendrías una hoja de data en https://da.live/sheet#/[orgname]/[sitename]/.helix/config, en la que listamos los roles admin.role.author o admin.role.publish para los IDs individuales de entidad de Adobe que se asignan a usuarios/perfiles. Esto ahora se elimina con Config Service, y los usuarios se gestionan directamente en Config Service para estos roles de previsualización/publicación, pero también para solicitudes de acceso. Además, antes, la publicación autenticada requería que usaras un perfil/ID de usuario de Adobe ilegible como "[email protected]" que se asignaba al inicio de sesión del usuario en una organización específica. Ahora, en Config Service, Helix te permite usar tu dirección de correo electrónico en lugar del ID de entidad ininteligible, e incluso permite a los usuarios "solicitar acceso" cuando tengan problemas de previsualización o publicación, que luego aparecerán en una aplicación de interfaz de administración en DA para aprobar o denegar solicitudes de acceso.

• Robots.txt Configuración: Antes se mantenía en /robots.txt en el proyecto git, pero ahora está configurado en Config Service.

• Configuración CDN: Antes se mantenía en la hoja de .helix/config en DA, pero ahora se inserta en Config Service. Esto sería para establecer valores como:

  • cdn.prod.host
  • cdn.prod.type
  • cdn.prod.serviceId
  • cdn.prod.authToken

Pasos para mover un sitio de entrega de borde basado en archivos existente a un servicio de configuración

Hay un comando migrate en la API AEM Admin (Helix) que permite migrar automáticamente una configuración de Edge Delivery basada en archivos a Config Service. Sin embargo, hay algunas salvedades, así que esto es lo que hay que saber al respecto.

Primero, supongamos que tienes un sitio existente creado en DA usando configuración basada en archivos (sé que tengo algunos sitios así, puede que sea minoría, pero esta es mi entrada en el blog; querrás reevaluar los pasos para tu propio caso de uso).

Pasos:

1. Asegúrate de ser administrador de tu organización: Como se ha mencionado antes, colabora con Adobe para asegurarte de que tienes admin en tu organización de Github. Valida esto yendo a https://tools.aem.live/tools/site-admin/index.html y luego iniciando sesión. Si funciona correctamente, deberías ver una solicitud exitosa de 200 https://admin.hlx.page/config/[orgname]/sites.json

2. Consigue tu token de autenticación: Haz shift+ctrl+I o shift+cmd+I para que aparezcan herramientas de desarrollador, y mira esa petición sites.json mencionada arriba. Si abres la pestaña de red y miras Encabezados, verás un valor x-auth-token . Copia ese valor, ya que es el token portador que necesitarás usar para las siguientes solicitudes API para interactuar con el Servicio de Configuración AEM.

3. Haz una copia de tu sitio: Es buena idea hacer una prueba en tu sitio (el que tiene configuraciones basadas en archivos) para poder probar este proceso antes de ejecutarlo en producción. Crea un nuevo repositorio y sitio de EDS y replétalo con la misma base de código que tu sitio actual (si no tienes ya un repositorio de desarrollo). Idealmente, también, llena una fuente de contenido para desarrolladores para tener un sandbox completamente armado y operativo con el que trastear.

4. Ejecuta el comando Migrate Dry-Run: Ejecuta el siguiente comando, que realizará un ensayo general de la migración de archivo a servicio de configuración:
   
   curl --request GET --url 'https://admin.hlx.page/config/{my-org}/sites/{my-site}.json?migrate=true&validate=true' -H "Authorization: token $MY_AUTH_TOKEN_NOTED_ABOVE"
   
   Si esto funciona, te dará un texto de validación como el siguiente, que te dirá si funcionará o no migrar esto. En mi caso, significa que NO estoy listo para migrar y que tengo cosas que arreglar:
   
   "error": "validation failed.", "message": "/sidekick/plugins/0/environments/0 must be equal to one of the allowed values; /sidekick/plugins/2/environments/0 must be equal to one of the allowed values",
   
   Además, si recibes una petición 400 mala en tu invocación, también puedes usar el encabezado x-error en la respuesta HTTP que también te informará sobre cualquier problema en la solicitud de migración en seco:

   

   En este caso, el error me indica que en mi lista de plugins AEM Sidekick, el primer plugin de /tools/sidekick/config.json es inválido, ya que configurar un plugin de esta manera ya no se soporta en Config Service. En este ejemplo, necesito migrar este plugin a la hoja de la Biblioteca de DA para plugins de DA.

   

5. Soluciona cualquier problema de validación como se ha indicado antes: Tendrás que revisar y solucionar cualquier problema que surja, y luego volver a ejecutar tu solicitud de validación.
   
   Toma cualquier plugin existente definido como Sidekick en el proyecto y colócalos en DA. En el caso de problemas con plugins de Sidekick como este, los plugins de DA se configurarían en https://da.live/config#/[orgname]/[sitename]/ en la pestaña "biblioteca" de la hoja.

   

   O otro problema como este:

   

   Esto indica que teníamos algunas propiedades ilegales en nuestros encabezados que ya no están soportadas (o quizás nunca lo estuvieron, y simplemente no rompían nada, por lo que nos dejamos ahí por error).
   
   Una vez resueltos esos problemas, estás listo para ejecutar la migración en sí.

6. Push/migra la configuración limpia y validada al servicio de configuración: Para impulsar la configuración, usa el siguiente comando:
   
   curl --request POST --url 'https://admin.hlx.page/config/{my-org}/sites/{my-site}.json?migrate=true' -H "Authorization: token $MY_AUTH_TOKEN_NOTED_ABOVE"
   
   Esencialmente el mismo comando que antes, pero con un POST en lugar de un GET. Esto te migrará al servicio de configuración.

7. Validar: Hay algunas cosas que debes validar inmediatamente una vez que migras.

   1. Validar índices: Ve a https://tools.aem.live/tools/index-admin/index.html y valida que tus índices han sido correctamente incorporados
   2. Validar los Sitemaps: Ve a https://tools.aem.live/tools/sitemap-admin/index.html y valida que todos los sitemaps han llegado
   3. Validar usuarios: Ve a https://tools.aem.live/tools/user-admin/index.html?org={orgname}&site={sitename} y asegúrate de que tus usuarios de Previsualización/Publicación aparecen allí.
   4. Validar usuarios en DA: Ve a https://da.live/apps/aem-permissions#/{orgname}/{sitename} que te permitirá ver una lista fácil de usar de permisos de previsualización/publicación a medida que estén expuestos a DA. Aquí es también donde ahora podrás
   5. Validar la vista previa/publicar: Cuando inicies sesión como usuario con permisos de previsualización/publicación, asegúrate de que aún tienes la capacidad de previsualizar/publicar adecuadamente. Consigue que un usuario que NO tenga acceso para previsualizar o publicar, y asegúrate de que esté correctamente bloqueado.
   6. Cualquier otra validación diversa que consideres necesaria para tu sitio.

8. Burn-in: QA y burn-in con el equipo, arreglar cualquier otro problema de previsualización o publicación que surja, y dejar que la nueva configuración siga funcionando al menos una semana para eliminar cualquier otro problema que pueda surgir.

9. Limpiar los archivos de configuración: Una vez completado el burn-in, ya no necesitarás tus configuraciones dentro del repositorio y podrás empezar a retirarlas una a una. Recomendaría mantener copias limpias de tus configuraciones actuales hasta git para el versionado, solo por motivos de recuperación de datos, por si alguien hace una solicitud de API errónea que por cualquier motivo no se pueda deshacer.

Notas sobre las implicaciones de CI/CD del servicio de configuración

Una nota aquí sobre CI/CD: Ahora que tienes la flexibilidad inherente de un servicio de configuración impulsado por API, también tienes la desventaja de que tu CI/CD dirigido por git ya no tiene ningún efecto.

La buena noticia es que hay herramientas como el Administrador de Versiones para llevar un control de los cambios de configuración y quién hace qué cambio:

La mala noticia es que esto elimina el framework CI/CD incorporado y centrado en pull requests que todos conocemos y adoramos absolutamente en Edge Delivery. Así que, si tienes situaciones en las que quieres que un ingeniero junior proponga cambios, será mucho más complicado para él darte una pull request que demuestre que su cambio de configuración es seguro para hacer rollforward.

Se complica aún más porque la autorización de la API se basa en tu usuario conectado actual, lo que hace que sea algo resistente a intentar integrar un conjunto persistente de claves en una pipeline CI/CD. Seguro que se puede hacer, solo que va a requerir algunos ajustes.

Así que, para esto (en el momento de escribir esto) tendrás que crear tu propio proceso CI/CD con el que te sientas cómodo, para el tamaño y composición de tu organización.

¡Espero que esto ayude, y por favor escribe si tienes algún problema con esto!

Sobre el autor

¿Te ha gustado lo que has oído? ¿Tienes preguntas sobre lo que es lo mejor para ti? ¡Nos encantaría hablar! Contáctenos

Más artículos que quizá te interesen