Note : il s’agit d’un sujet un peu plus avancé sur les services de livraison en Edge et la création de documents. Pour une introduction à l’EDS et à la rédaction de documents, veuillez d’abord consulter ceci pour le contexte.

Contexte sur les configurations et services de configuration de livraison AEM Edge basés sur des fichiers

Lorsque Adobe a lancé Edge Delivery Services (ou Helix comme on l’appelle en interne), toutes les configurations majeures à l’échelle du site étaient effectuées à l’aide de fichiers de configuration enregistrés dans le dépôt du site. Le déploiement d’une nouvelle configuration se faisait en poussant vers la branche main du dépôt, ce qui mettait cette configuration en ligne sur le site. Un inconvénient était que chaque dépôt devait être directement lié à un site et à un dépôt de documents. Vous ne pourriez alors pas avoir un seul dépôt de code qui pilote plusieurs sites – ou même plusieurs versions d’un même site (comme des environnements de type dev/stg/prd pour le contenu ou la configuration en staning).

En conséquence de cela, et d’autres préoccupations techniques, Adobe a évolué vers une nouvelle architecture basée sur le Service de Configuration. Dans ce paradigme, les configurations sont stockées et versionnées centralement par Adobe dans leur service de configuration piloté par API, et une fois migrés vers ce service, les fichiers de votre projet Edge Delivery n’auront plus aucun effet sur le site.

Prérequis pour passer au service de configuration

Comme indiqué sur https://www.aem.live/docs/config-service-setup#prerequisites, avant de commencer la transition vers le service de configuration, vous devez d’abord vous assurer que votre utilisateur Adobe est mappé comme administrateur pour votre organisation Github, afin d’avoir l’autorité dans le service de configuration pour effectuer des modifications. Votre contact technique Adobe avec qui vous traitez généralement devrait pouvoir vous mettre en contact avec ce problème.

Points de terminaison et surfaces de configuration affectés par un passage au service de configuration

Cela affecte les surfaces de configuration suivantes dans un projet de livraison d’arêtes :

• Cartographie du bus de contenu: La configuration en /fstab.yaml où le projet est mappé vers un emplacement soit dans DA (soit ailleurs, comme AEM/Universal Editor ou Sharepoint) est désormais dans le service de configuration. C’est la partie la plus critique qui permet à un seul dépôt de piloter plusieurs sites (anciennement appelé configuration « sans repos », car cela signifiait que le dépôt de code et le dépôt de contenu n’étaient pas inextricablement liés).

• Index de requête: La configuration d’index pour toutes les langues était auparavant stockée dans le projet dans /helix-query.yaml

• Configuration de la carte de site: La configuration de la carte de site auparavant créée en /helix-sitemap.yaml sera désormais intégrée au Service de Config.

• Configuration Sidekick: Il existe deux types différents de configurations Sidekick qui étaient auparavant conservées dans le projet git, mais qui sont maintenant disponibles ailleurs.

  • Plugins DA : Autrefois, aux débuts de DA, nous gardions les plugins DA dans le fichier /tools/sidekick/config.json du dépôt de code. Cela concerne des choses comme les différentes améliorations de l’interface DA comme notre sélecteur de date, le plugin AEM Tags, etc. Cela est désormais conservé dans la feuille Library de la configuration DA elle-même, plutôt que dans la base de code.
  • Plugins/Config Sidekick : D’autres configurations AEM Sidekick, comme celles pour Quick Edit ou pour AEM Experimentation, sont désormais conservées directement dans le service de configuration, plutôt que dans DA. La configuration Sidekick dans le projet GIT d’EDS n’aura plus aucun effet.

• Configuration des en-têtes HTTP: Cela était auparavant conservé dans la feuille headers de DA, mais sera maintenant intégré au service de configuration. C’est pour la configuration CORS comme coller un en-tête access-control-allow-origin sur certains hôtes.

• Aperçu/authentification de publication Helix: Pour le contrôle d’accès authentifié à l’aperçu/publication, nous utilisons un modèle d’authentification basé sur des feuilles, où vous avez une feuille de data dans https://da.live/sheet#/[orgname]/[sitename]/.helix/config, dans laquelle nous listons les rôles admin.role.author ou admin.role.publish pour chaque identifiant d’entité Adobe qui correspondent aux utilisateurs/profils. Cela est désormais supprimé avec Config Service, et les utilisateurs sont gérés directement dans Config Service pour ces rôles de prévisualisation/publication, mais aussi pour les demandes d’accès. De plus, auparavant, la publication authentifiée exigeait que vous utilisiez un profil/identifiant utilisateur Adobe illisible comme « [email protected] » qui serait associé à la connexion d’un utilisateur auprès d’une organisation spécifique. Maintenant, dans Config Service, Helix vous permet d’utiliser votre adresse e-mail au lieu de l’ID d’entité non intelligible, et permet même aux utilisateurs de « demander l’accès » lorsqu’ils rencontrent des problèmes de prévisualisation/publication, ce qui apparaît ensuite dans une application d’interface d’administration dans DA pour approuver ou refuser les demandes d’accès.

• Robots.txt Configuration: Cela était auparavant conservé en /robots.txt dans le projet git, mais est maintenant configuré dans Config Service.

• Configuration CDN: Cela était auparavant conservé dans la feuille .helix/config dans DA, mais est maintenant intégré au Service de configuration. Cela concerne la définition de valeurs telles que :

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

Étapes pour déplacer un site de livraison edge existant basé sur des fichiers vers un service de configuration

Il existe une commande migrate dans l’API AEM Admin (Helix) qui permet de migrer automatiquement une configuration Edge Delivery basée sur des fichiers vers Config Service. Il y a cependant quelques réserves, voici donc ce qu’il faut savoir à ce sujet.

Tout d’abord, supposons que vous ayez un site existant créé sur DA en utilisant une configuration basée sur des fichiers (je sais que j’en ai quelques-uns de ce genre, je suis peut-être dans la minorité, mais ceci est mon article de blog – vous voudrez réévaluer les étapes pour votre propre cas d’usage).

Étapes :

1. Assurez-vous d’être administrateur de votre organisation : Comme mentionné plus haut, travaillez avec Adobe pour vous assurer que vous avez admin sur votre organisation Github. Validez cela en allant sur https://tools.aem.live/tools/site-admin/index.html puis en vous connectant. Si ça fonctionne correctement, vous devriez voir une demande réussie de 200 https://admin.hlx.page/config/[orgname]/sites.json

2. Prenez votre jeton d’authentification : Fais un shift+ctrl+I ou shift+cmd+I pour faire apparaître des outils développeur, et regarde cette sites.json demande mentionnée ci-dessus. Si vous ouvrez l’onglet réseau et regardez En-têtes, vous verrez une valeur x-auth-token . Copiez cette valeur, car c’est le jeton porteur que vous devrez utiliser pour les requêtes API suivantes afin d’interagir avec le service de configuration AEM.

3. Faites une copie de votre site : C’est une bonne idée de faire un test sur votre site (celui avec des configurations basées sur des fichiers) afin de pouvoir tester ce processus avant de l’exécuter en production. Créez un nouveau dépôt et site EDS et remplissez-le avec la même base de code que votre site actuel (si vous n’avez pas déjà de dépôt développeur). Idéalement, il vaut aussi remplir une source de contenu de développement pour avoir un bac à sable entièrement armé et opérationnel avec lequel s’amuser.

4. Exécutez la commande Migrer à blanc : exécutez la commande suivante, qui effectuera un test à blanc de la migration du fichier vers le service de configuration :
   
   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 cela fonctionne, il affichera un texte de validation comme le suivant, qui vous indiquera si la migration fonctionnera ou non. Dans mon cas ici, cela signifie que je ne suis PAS prêt à migrer et que j’ai des choses à corriger :
   
   "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",
   
   De plus, si vous recevez une requête 400 mauvaise lors de votre invocation, vous pouvez aussi utiliser l’en-tête x-error dans la réponse HTTP qui vous indiquera aussi tout problème dans la requête de migration à blanc :

   

   Dans ce cas, l’erreur m’indique que dans ma liste de plugins AEM Sidekick, le premier plugin dans /tools/sidekick/config.json est invalide, car configurer un plugin de cette manière n’est plus pris en charge dans Config Service. Dans cet exemple, je dois migrer ce plugin dans la fiche DA Library pour les plugins DA.

   

5. Corrigez les problèmes de validation comme indiqué ci-dessus : Vous devrez passer en revue et corriger tout problème qui survient, puis relancer votre demande de validation.
   
   Prenez tous les plugins existants définis comme des plugins Sidekick dans le projet, et mettez-les dans DA. Dans le cas de problèmes de plugins Sidekick comme celui-ci, les plugins DA seraient configurés en https://da.live/config#/[orgname]/[sitename]/ dans l’onglet « bibliothèque » de la feuille.

   

   Ou un autre problème comme celui-ci :

   

   Cela indique que nous avions des propriétés illégales dans nos en-têtes qui ne sont plus prises en charge (ou peut-être ne l’ont jamais été, et ne cassaient rien donc nous avons été laissés par erreur).
   
   Une fois ces problèmes réglés, vous êtes prêt à lancer la migration elle-même.

6. Poussez/migrez la configuration propre et validée vers le service de configuration : Pour pousser la configuration, utilisez la commande suivante :
   
   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"
   
   Essentiellement la même commande que ci-dessus, mais avec un POST au lieu d’un GET. Cela vous migrera vers le service de configuration.

7. Valider : Il y a quelques éléments à valider immédiatement une fois la migration.

   1. Validez les index : Allez sur https://tools.aem.live/tools/index-admin/index.html et validez que vos indices ont été correctement intégrés
   2. Validez les plans de site : Allez sur https://tools.aem.live/tools/sitemap-admin/index.html et validez que tous les sitemaps sont passés
   3. Valider les utilisateurs : Allez sur https://tools.aem.live/tools/user-admin/index.html?org={orgname}&site={sitename} et assurez-vous que vos utilisateurs de Prévisualisation/Publication y apparaissent.
   4. Validez les utilisateurs dans DA: Allez sur https://da.live/apps/aem-permissions#/{orgname}/{sitename} qui vous permettra de voir une liste conviviale des permissions de prévisualisation/publication au fur et à mesure qu’ils sont exposés à DA. C’est aussi là que vous pourrez désormais
   5. Valider l’aperçu/publier : Lorsque vous êtes connecté en tant qu’utilisateur avec des permissions d’aperçu/publication, assurez-vous de pouvoir prévisualiser ou publier correctement. Faites en sorte qu’un utilisateur qui n’a PAS accès à l’aperçu ou à la publication, et assurez-vous que tout est verrouillé correctement.
   6. Toute autre validation diverse que vous jugez nécessaire pour votre site.

8. Burn-in : Contrôle qualité et burn-in avec l’équipe, corriger tout autre problème de prévisualisation/publication qui survient, et laisser la nouvelle configuration s’installer pendant au moins une semaine pour éliminer tout autre problème éventuel.

9. Nettoyez les fichiers de configuration: Une fois le burn-in terminé, vous n’aurez plus besoin de vos configurations en dépôt, et vous pourrez commencer à les retirer une par une. Je recommande de conserver des copies propres de vos configurations actuelles jusqu’à git pour la gestion des versions, juste pour des raisons de gestion des données, au cas où quelqu’un ferait une requête API erronée qui, pour une raison quelconque, ne pourra pas être annulée.

Notes sur les implications CI/CD du service de configuration

Une note ici sur CI/CD : Maintenant que vous avez la flexibilité inhérente d’un service de configuration piloté par une API, vous avez aussi l’inconvénient que votre CI/CD piloté par git n’a plus aucun effet.

La bonne nouvelle, c’est qu’il existe des outils comme l’administrateur de version pour suivre les modifications de configuration et qui effectue quoi :

La mauvaise nouvelle, c’est que cela supprime le cadre CI/CD intégré et centré sur les requêtes de retrait que nous connaissons tous et adorons absolument dans Edge Delivery. Donc, si vous avez des situations où vous souhaitez qu’un ingénieur junior propose des modifications, il sera beaucoup plus compliqué pour lui de vous fournir une pull request démontrant que leur modification de configuration est sûre à faire avancer.

C’est d’autant plus compliqué que l’autorisation de l’API repose sur votre utilisateur connecté actuel, ce qui la rend légèrement résistante à l’intégration d’un ensemble persistant de clés dans un pipeline CI/CD. Je suis sûr que c’est faisable, il faudra juste un peu de bricolage.

Donc, pour cela (au moment d’écrire ces lignes), vous devrez créer votre propre processus CI/CD avec lequel vous vous sentez à l’aise, pour la taille et la composition de votre organisation.

J’espère que cela vous aide, et n’hésitez pas à me contacter si vous avez des problèmes avec tout cela !

À propos de l’auteur

Tu as aimé ce que tu as entendu ? Vous avez des questions sur ce qui vous convient ? Nous serions ravis de discuter ! Contactez-nous

Plus d’articles que vous pourriez aimer