Nota: questo è un argomento leggermente più avanzato su Edge Delivery Services e Documentazione Documentale. Per un'introduzione su EDS e Authoring di Documenti, consulta prima questo per il contesto.

Contesto sulle configurazioni di consegna edge e servizio di configurazione AEM basate su file

Quando Adobe ha lanciato per la prima volta Edge Delivery Services (o Helix come è conosciuto internamente), tutte le principali configurazioni a livello del sito venivano effettuate utilizzando file di configurazione registrati nel repository del sito. Il deployment di una nuova configurazione avveniva inviando il push al main branch del repository, che spingeva quella configurazione live sul sito. Uno svantaggio di ciò era che ogni archivio doveva essere collegato direttamente a un sito e a un archivio documentale. Non potresti quindi avere un singolo repository di codice che gestisca più siti - o anche più versioni di un singolo sito (come ambienti in stile dev/stg/prd per contenuti o configurazioni staging).

A causa di questo e di altre preoccupazioni tecniche, Adobe si sta spostando verso un nuovo design architettonico basato sul Configuration Service. In questo paradigma, le configurazioni vengono memorizzate centralmente e versionate da Adobe nel loro Configuration Service guidato dall'API, e una volta migrati su questo servizio, i file nel tuo progetto Edge Delivery non avranno più alcun effetto sul sito.

Prerequisiti per il passaggio al servizio di configurazione

Come indicato su https://www.aem.live/docs/config-service-setup#prerequisites, prima di iniziare il passaggio al Config Service, devi prima assicurarti che il tuo utente Adobe sia mappato come amministratore della tua organizzazione Github, così da avere l'autorità nel Config Service per apportare modifiche. Il tuo referente tecnico Adobe con cui di solito hai a che fare dovrebbe essere in grado di metterti in contatto su questo.

Endpoint e superfici di configurazione influenzati da uno spostamento al servizio di configurazione

Questo influisce sulle seguenti superfici di configurazione in un progetto di consegna degli arzi:

• Content Bus Mapping: La configurazione in /fstab.yaml in cui il progetto si mappa a una posizione sia in DA (sia altrove, come AEM/Universal Editor o Sharepoint) ora è nel Config Service. Questo è il bit più critico che permette a un singolo repository di gestire più siti (precedentemente noto come configurazione "repoless", poiché significava che il repository di codice e il repository di contenuto non erano indissolubilmente collegati).

• Indici di Query: La configurazione dell'indice per tutte le lingue era precedentemente memorizzata nel progetto in /helix-query.yaml

• Configurazione della mappa del sitemap: La configurazione della mappa del sito precedentemente realizzata in /helix-sitemap.yaml ora sarà nel Servizio di Configurazione.

• Configurazione Sidekick: Esistono due diversi tipi di configurazioni Sidekick che in passato erano conservate nel progetto git, che ora sono altrove.

  • Plugin DA: In passato, nei primi giorni di DA, tenevamo i plugin DA nel file /tools/sidekick/config.json nel repository di codice. Questo sarebbe per cose come i vari miglioramenti dell'interfaccia DA come il nostro selettore di date, il plugin AEM Tag, ecc. Questo ora è conservato nel foglio Library nella configurazione di DA in DA, invece che nella base di codice.
  • Plugin/Configurazione Sidekick: Altre configurazioni AEM Sidekick, come quelle per Quick Edit o per AEM Experimentation, ora sono mantenute direttamente nel servizio di configurazione, anziché in DA. La configurazione di Sidekick nel progetto EDS git non avrà più alcun effetto.

• Configurazione delle intestazioni HTTP: Questo era precedentemente mantenuto nel foglio headers di DA, ma ora verrà inserito nel servizio di configurazione. Questo vale per configurazioni CORS come fissare un header access-control-allow-origin su certi host.

• Anteprima/Pubblicazione di Helix: Per il controllo di accesso autenticato a Anteprima/Pubblicazione, abbiamo utilizzato un modello di autenticazione basato su fogli, in cui avresti un foglio di data in https://da.live/sheet#/[orgname]/[sitename]/.helix/config, in cui elenchiamo i ruoli admin.role.author o admin.role.publish per i singoli ID di entità Adobe che si mappano a utenti/profili. Questo è ora eliminato con Config Service, e gli utenti sono gestiti direttamente in Config Service per questi ruoli di anteprima/pubblicazione, ma anche per le richieste di accesso. Inoltre, in passato, la pubblicazione autenticata richiedeva di usare un profilo/ID utente Adobe illeggibile come "[email protected]" che veniva mappato all'accesso dell'utente con un'organizzazione specifica. Ora in Config Service, Helix ti permetterà di usare il tuo indirizzo email invece dell'ID entità non comprensibile, e permetterà persino agli utenti di "richiedere accesso" quando incontrano problemi di anteprima o pubblicazione, che poi appariranno su un'app di interfaccia amministrativa in DA per approvare/negare le richieste di accesso.

• Robots.txt Configurazione: In precedenza era mantenuto in /robots.txt nel progetto git, ma ora è configurato in Config Service.

• Configurazione CDN: Questo era precedentemente mantenuto nel foglio .helix/config in DA, ma ora viene inserito nel Config Service. Questo servirebbe per impostare valori come:

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

Passaggi per spostare un sito di consegna edge basato su file esistente verso il servizio di configurazione

C'è un comando migrate nell'API AEM Admin (Helix) che permette di migrare automaticamente una configurazione di consegna Edge basata su file su Config Service. Ci sono però alcune precisazioni, quindi ecco cosa sapere a riguardo.

Prima di tutto, supponiamo che tu abbia un sito esistente creato su DA usando una configurazione basata su file (so di avere alcuni siti simili, potrei essere in minoranza, ma questo è il mio post sul blog - vorrai rivalutare i passaggi per il tuo caso d'uso).

Passaggi:

1. Assicurati di essere amministratore della tua organizzazione: Come detto sopra, collabora con Adobe per assicurarti di avere admin sulla tua organizzazione su Github. Valida questo andando su https://tools.aem.live/tools/site-admin/index.html e poi accedi. Se funziona correttamente, dovresti vedere una richiesta di successo da 200 https://admin.hlx.page/config/[orgname]/sites.json

2. Prendi il tuo token di autorizzazione: Fai shift+ctrl+I o shift+cmd+I per far apparire gli strumenti di sviluppo, e guarda quella sites.json richiesta menzionata sopra. Se apri la scheda rete e guardi Headers, vedrai un valore x-auth-token . Copia quel valore, poiché è il token portatore che dovrai usare per le seguenti richieste API per interagire con il Servizio di Configurazione AEM.

3. Fai una copia del tuo sito: È una buona idea fare un test sul tuo sito (quello con configurazioni basate su file) così puoi testare questo processo prima di eseguirlo in produzione. Crea un nuovo repository e sito EDS e popolalo con la stessa base di codice del tuo sito attuale (se non hai già un repository per sviluppatori). Idealmente, inoltre, popola una fonte di contenuti per sviluppatori così da avere un sandbox completamente armato e operativo con cui sperimentare.

4. Esegui il comando Migrate Dry-Run: esegui il seguente comando, che eseguirà una prova a secco della migrazione dal file basato al servizio Config:
   
   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"
   
   Se funziona, mostrerà un testo di validazione come il seguente, che ti dirà se la migrazione funzionerà o meno. Nel mio caso, significa che NON sono pronto a migrare e che devo sistemare le cose:
   
   "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",
   
   Inoltre, se ricevi una richiesta 400 male nella tua invocazione, puoi anche usare l'intestazione x-error nella risposta HTTP che ti informerà anche di eventuali problemi nella richiesta di migrazione a vuoto:

   

   In questo caso, l'errore mi dice che nella mia lista di plugin AEM Sidekick, il primo plugin in /tools/sidekick/config.json è invalido, poiché configurare un plugin in questo modo non è più supportato nel Servizio di Configurazione. In questo esempio, devo migrare questo plugin nel foglio DA Library per i plugin DA.

   

5. Risolvi eventuali problemi di validazione come detto sopra: Dovrai risolvere eventuali problemi che si presentano, e poi rieseguire la tua richiesta di validazione.
   
   Prendi tutti i plugin esistenti definiti come plugin Sidekick nel progetto e mettili in DA. Nel caso di problemi con i plugin Sidekick come questo, i plugin DA sarebbero configurati in https://da.live/config#/[orgname]/[sitename]/ nella scheda "libreria" del foglio.

   

   O un altro problema simile:

   

   Questo indica che avevamo alcune proprietà illegali nelle nostre intestazioni che non sono più supportate (o forse non sono mai state supportate, e semplicemente non rompevano nulla, quindi siamo state lasciate lì per errore).
   
   Una volta risolti questi problemi, sei pronto a eseguire la migrazione vera e propria.

6. Push/Migra la configurazione pulita e validata al servizio di configurazione: Per spingere la configurazione, usa il seguente 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"
   
   Essenzialmente lo stesso comando di sopra, ma con un POST invece di un GET. Questo ti migrerà al servizio di configurazione.

7. Valida: Ci sono alcune cose da validare immediatamente una volta migrato.

   1. Valida gli indici: Vai su https://tools.aem.live/tools/index-admin/index.html e verifica che i tuoi indici siano stati recuperati correttamente
   2. Valida le Sitemap: Vai su https://tools.aem.live/tools/sitemap-admin/index.html e verifica che tutte le sitemap siano arrivate
   3. Valida gli utenti: Vai su https://tools.aem.live/tools/user-admin/index.html?org={orgname}&site={sitename} e assicurati che i tuoi utenti di Anteprima/Pubblicazione compaiano lì.
   4. Valida gli utenti in DA: vai su https://da.live/apps/aem-permissions#/{orgname}/{sitename} che ti permetterà di vedere una lista intuitiva di permessi di anteprima/pubblicazione man mano che vengono esposti a DA. Qui è anche dove ora potrai poter
   5. Valida l'anteprima/Pubblica: Quando sei loggato come utente con permessi di anteprima o pubblicazione, assicurati di avere ancora la possibilità di anteprimare/pubblicare correttamente. Fai in modo che un utente che NON abbia accesso possa visualizzare o pubblicare, e assicurati che sia bloccato correttamente.
   6. Qualsiasi altra validazione varia che ritieni necessaria per il tuo sito.

8. Burn-in: QA e burn-in con il team, correggere eventuali altri problemi di anteprima/pubblicazione che si presentano, e lasciare che la nuova configurazione si sviluppi per almeno una settimana per eliminare eventuali altri problemi che potrebbero sorgere.

9. Pulire i file di configurazione: una volta completato il burn-in, non avrai più bisogno delle configurazioni in-repo e potrai iniziare a ritirarle una per una. Consiglierei di mantenere copie pulite delle tue configurazioni attuali fino a git per il versioning, solo per scopi di DR, nel caso qualcuno faccia una richiesta API errata che per qualsiasi motivo non può essere annullata.

Note sulle implicazioni CI/CD del servizio di configurazione

Una nota qui su CI/CD: ora che hai la flessibilità intrinseca di un servizio di configurazione guidato da API, hai anche lo svantaggio che il tuo CI/CD guidato da git non ha più alcun effetto.

La buona notizia è che esistono alcuni strumenti come il Version Admin per tenere traccia delle modifiche di configurazione e chi fa quali modifiche:

La cattiva notizia è che questo elimina il framework CI/CD integrato, incentrato sulle pull request, che tutti conosciamo e adoriamo in Edge Delivery. Quindi, se ti trovi in situazioni in cui vuoi che un ingegnere junior proponga modifiche, sarà molto più complicato per lui darti una pull request che dimostri che la loro modifica di configurazione è sicura da roll-forward.

È reso più complicato dal fatto che l'autorizzazione per l'API si basa sul tuo utente attualmente logato, il che la rende leggermente resistente a tentare di integrare in un insieme persistente di chiavi in una pipeline CI/CD. Sono sicuro che si può fare, ci vorrà solo qualche smanettamento.

Quindi, per questo (al momento della scrittura) dovrai creare un tuo processo CI/CD con cui ti senti a tuo agio, in base alla dimensione e alla composizione della tua organizzazione.

Spero che questo ti sia utile, e per favore scrivi se hai problemi con tutto questo!

Informazioni sull'autore

Ti è piaciuto quello che hai sentito? Hai domande su cosa sia giusto per te? Ci piacerebbe parlare! Contattaci

Altri articoli che potrebbero piacerti