Uwaga: jest to nieco bardziej zaawansowany temat dotyczący usług Edge Delivery Services & Document Authoring. Aby zapoznać się z wprowadzeniem do EDS & Document Authoring, zapoznaj się najpierw z tym kontekstem.

Informacje ogólne na temat konfiguracji AEM Edge Delivery opartych na plikach & Config Service

Kiedy firma Adobe po raz pierwszy uruchomiła usługi Edge Delivery Services (lub Helix, jak jest znana wewnętrznie), cała główna konfiguracja całej witryny została wykonana przy użyciu plików konfiguracyjnych sprawdzonych w repozytorium witryny. Wdrażanie nowej konfiguracji odbywało się poprzez wypychanie do gałęzi main repozytorium, co powodowało uruchomienie tej konfiguracji w witrynie. Wadą tego rozwiązania było to, że każde repozytorium musiało być bezpośrednio powiązane z witryną i repozytorium dokumentów. Pojedyncze repozytorium kodu nie mogłoby wtedy obsługiwać wielu witryn - ani nawet wielu wersji jednej witryny (takich jak środowiska w stylu dev/stg/prd do przechowywania treści lub konfiguracji).

W związku z tym i innymi problemami technicznymi firma Adobe przechodzi na nowy projekt architektury oparty na usłudze konfiguracji. W tym paradygmacie konfiguracje są centralnie przechowywane i wersjonowane przez Adobe w ich usłudze konfiguracji opartej na interfejsie API, a po migracji do tej usługi pliki w projekcie Edge Delivery nie będą już miały żadnego wpływu na witrynę.

Wymagania wstępne dotyczące przejścia do usługi konfiguracji

Jak wspomniano na stronie https://www.aem.live/docs/config-service-setup#prerequisites, przed rozpoczęciem przenoszenia do usługi Config Service należy najpierw upewnić się, że użytkownik Adobe jest zmapowany jako administrator organizacji Github, aby mieć uprawnienia do wprowadzania zmian w usłudze Config Service. Osoba kontaktowa z działu technicznego Adobe, z którą zazwyczaj współpracujesz, powinna być w stanie podłączyć Cię do tego.

Punkty końcowe & Powierzchnie konfiguracji, na które ma wpływ przejście do usługi konfiguracji

Ma to wpływ na następujące powierzchnie konfiguracyjne w projekcie Edge Delivery:

• Mapowanie magistrali treści: Konfiguracja w /fstab.yaml, w której projekt jest mapowany do lokalizacji w DA (lub w innym miejscu, takim jak AEM/Universal Editor lub Sharepoint), znajduje się teraz w usłudze Config Service. Jest to najbardziej krytyczny element, który pozwala pojedynczemu repozytorium obsługiwać wiele witryn (wcześniej znany jako konfiguracja "repoless", ponieważ oznaczało to, że repozytorium kodu i repozytorium treści nie były nierozerwalnie połączone).

• Indeksy zapytań: Konfiguracja indeksów dla wszystkich języków była wcześniej przechowywana w projekcie w sekcji /helix-query.yaml

• Konfiguracja mapy witryny: Konfiguracja mapy witryny dokonywana wcześniej w witrynie /helix-sitemap.yaml będzie teraz dostępna w usłudze Config Service.

• Konfiguracja Sidekick: Istnieją dwa różne typy konfiguracji Sidekick, które wcześniej były przechowywane w projekcie git, a teraz znajdują się w innym miejscu.

  • Wtyczki DA: Dawniej, we wczesnych dniach DA, przechowywaliśmy wtyczki DA w pliku /tools/sidekick/config.json w repozytorium kodu. Dotyczy to takich rzeczy, jak różne ulepszenia interfejsu użytkownika DA, takie jak nasz selektor dat, wtyczka AEM Tags itp. Jest to teraz przechowywane w arkuszu Library w konfiguracji DA w samym DA, a nie w bazie kodu.
  • Sidekick Plugins/Config: Inne konfiguracje AEM Sidekick, takie jak konfiguracja szybkiej edycji lub eksperymentów AEM, są teraz przechowywane bezpośrednio w usłudze konfiguracji, a nie w DA. Konfiguracja Sidekick w projekcie EDS git nie będzie już miała żadnego wpływu.

• Konfiguracja nagłówków HTTP: Było to wcześniej przechowywane w arkuszu headers DA, ale teraz zostanie przeniesione do usługi konfiguracji. Służy do konfiguracji CORS, np. umieszczania nagłówka access-control-allow-origin na niektórych hostach.

• Uwierzytelnianie Helix Preview/Publish: W przypadku uwierzytelnionej kontroli dostępu do podglądu/publikacji używamy modelu uwierzytelniania opartego na arkuszach, w którym masz arkusz data w https://da.live/sheet#/[orgname]/[sitename]/.helix/config, w którym wymieniamy role admin.role.author lub admin.role.publish dla poszczególnych identyfikatorów podmiotów Adobe, które mapują się na użytkownika/profile. Zostało to teraz usunięte dzięki usłudze Config Service, a użytkownicy są zarządzani bezpośrednio w usłudze Config Service dla tych ról podglądu/publikacji, ale także dla żądań dostępu. Ponadto wcześniej uwierzytelnione publikowanie wymagało użycia nieczytelnego profilu Adobe / identyfikatora użytkownika, takiego jak "[email protected]", który byłby mapowany na login użytkownika z określoną organizacją. Teraz w usłudze Config Service Helix pozwala na użycie adresu e-mail zamiast niezamierzonego identyfikatora podmiotu, a nawet pozwala użytkownikom na żądanie dostępu "" , gdy napotkają problemy z podglądem / publikacją, które następnie pojawią się w aplikacji interfejsu administratora w DA w celu zatwierdzenia / odrzucenia żądań dostępu.

• Konfiguracja pliku robots.txt: Było to wcześniej przechowywane w /robots.txt w projekcie git, ale teraz jest skonfigurowane w Config Service.

• Konfiguracja CDN: Wcześniej było to przechowywane w arkuszu .helix/config w DA, ale teraz zostało przeniesione do Config Service. Służy to do ustawiania wartości takich jak:

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

Kroki przeniesienia istniejącej witryny Edge Delivery opartej na plikach do usługi Config Service

W interfejsie API AEM Admin (Helix ) znajduje się polecenie migrate, które umożliwia automatyczną migrację konfiguracji Edge Delivery opartej na plikach do usługi Config Service. Istnieją jednak pewne zastrzeżenia, więc oto, co warto wiedzieć na ten temat.

Po pierwsze, załóżmy, że masz istniejącą witrynę, która została utworzona w DA przy użyciu konfiguracji opartej na plikach (wiem, że mam kilka takich witryn, być może jestem w mniejszości, ale to jest mój wpis na blogu - będziesz chciał ponownie przeanalizować kroki dla własnego przypadku użycia).

Kroki:

1. Upewnij się, że jesteś administratorem swojej organizacji: Jak wspomniano powyżej, współpracuj z Adobe, aby upewnić się, że masz admin w swojej organizacji Github. Potwierdź to, przechodząc na stronę https://tools.aem.live/tools/site-admin/index.html, a następnie zaloguj się. Jeśli działa poprawnie, powinieneś zobaczyć pomyślne żądanie 200 dla https://admin.hlx.page/config/[orgname]/sites.json

2. Pobierz swój auth token: Wykonaj shift+ctrl+I lub shift+cmd+I, aby wyświetlić narzędzia deweloperskie i spójrz na powyższe żądanie sites.json. Jeśli otworzysz kartę sieci i spojrzysz na nagłówki, zobaczysz wartość x-auth-token. Skopiuj tę wartość, ponieważ jest to token na okaziciela, którego będziesz musiał użyć w następujących żądaniach API do interakcji z usługą konfiguracji AEM.

3. Utwórz kopię swojej witryny: Dobrym pomysłem jest wykonanie testowego uruchomienia na swojej witrynie (tej z konfiguracją opartą na plikach), aby można było przetestować ten proces przed uruchomieniem go na prod. Utwórz nową witrynę EDS repo & i wypełnij ją tą samą bazą kodu, co obecna witryna (jeśli nie masz jeszcze repozytorium deweloperskiego). Idealnym rozwiązaniem jest również wypełnienie źródła zawartości deweloperskiej, aby mieć w pełni uzbrojoną i działającą piaskownicę do zabawy.

4. Uruchom polecenie Migrate Dry-Run: Uruchom następujące polecenie, które wykona suchy przebieg migracji z usługi opartej na plikach do usługi 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"
   
   Jeśli to zadziała, wypluje tekst walidacji, taki jak poniższy, który powie, czy migracja będzie działać, czy nie. W moim przypadku oznacza to, że NIE jestem gotowy na migrację i mam rzeczy do naprawienia:
   
   "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",
   
   Ponadto, jeśli otrzymasz 400 bad request przy wywołaniu, możesz również użyć nagłówka x-error w odpowiedzi HTTP, który również poinformuje Cię o wszelkich problemach w żądaniu migracji na sucho:

   

   W tym przypadku błąd informuje mnie, że na mojej liście wtyczek AEM Sidekick pierwsza wtyczka w /tools/sidekick/config.json jest nieprawidłowa, ponieważ konfigurowanie wtyczki w ten sposób nie jest już obsługiwane w usłudze Config Service. W tym przykładzie muszę zmigrować tę wtyczkę do arkusza DA Library dla wtyczek DA.

   

5. Napraw wszelkie problemy z walidacją, jak wspomniano powyżej: Będziesz musiał przejść i naprawić wszelkie problemy, które się pojawią, a następnie ponownie uruchomić żądanie walidacji.
   
   Weź wszystkie istniejące wtyczki zdefiniowane jako wtyczki Sidekick w projekcie i umieść je w DA. W przypadku takich wtyczek Sidekick, wtyczki DA byłyby konfigurowane na stronie https://da.live/config#/[orgname]/[sitename]/ w zakładce "library" arkusza.

   

   Albo inna kwestia, taka jak ta:

   

   Wskazuje to, że w naszych nagłówkach znajdowały się nielegalne właściwości, które nie są już obsługiwane (lub być może nigdy nie były obsługiwane i po prostu niczego nie łamały, więc zostały tam omyłkowo pozostawione).
   
   Gdy te kwestie zostaną rozwiązane, można przystąpić do samej migracji.

6. Wypchnij/migruj czystą, zweryfikowaną konfigurację & do usługi config: Aby wypchnąć konfigurację, użyj następującego polecenia:
   
   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"
   
   Zasadniczo to samo polecenie, co powyżej, ale z POST zamiast GET. Spowoduje to migrację do usługi konfiguracji.

7. Weryfikacja: Istnieje kilka rzeczy, które należy natychmiast zweryfikować po migracji.

   1. Sprawdź poprawność indeksów: Przejdź na stronę https://tools.aem.live/tools/index-admin/index.html i sprawdź, czy indeksy zostały poprawnie pobrane.
   2. Sprawdź poprawność map witryn: Przejdź na stronę https://tools.aem.live/tools/sitemap-admin/index.html i sprawdź, czy wszystkie mapy witryn zostały przesłane.
   3. Zweryfikuj użytkowników: Przejdź na stronę https://tools.aem.live/tools/user-admin/index.html?org={orgname}&site={sitename} i upewnij się, że użytkownicy Preview/Publish są tam widoczni.
   4. Weryfikacja użytkowników w DA: Przejdź na stronę https://da.live/apps/aem-permissions#/{orgname}/{sitename}, która pozwoli Ci zobaczyć przyjazną dla użytkownika listę uprawnień do podglądu/publikowania, ponieważ są one widoczne w DA. Jest to również miejsce, w którym możesz teraz
   5. Sprawdź podgląd/publikację: Po zalogowaniu się jako użytkownik z uprawnieniami do podglądu/publikowania upewnij się, że nadal masz możliwość odpowiedniego podglądu/publikowania. Znajdź użytkownika, który NIE ma dostępu do podglądu lub publikowania i upewnij się, że jest odpowiednio zablokowany.
   6. Wszelkie inne weryfikacje, które uważasz za niezbędne dla swojej witryny.

8. Wdrożenie: QA: & wdrożenie z zespołem, naprawienie wszelkich innych problemów związanych z podglądem/publikacją, które się pojawią, i pozostawienie nowej konfiguracji na co najmniej tydzień, aby wyeliminować wszelkie inne problemy, które mogą się pojawić.

9. Czyszczenie plików konfiguracyjnych: Po zakończeniu wypalania nie będziesz już potrzebować konfiguracji w repozytorium i możesz zacząć wycofywać je pojedynczo. Zalecałbym przechowywanie czystych kopii bieżących konfiguracji w git w celu wersjonowania, tylko dla celów DR, na wypadek gdyby ktoś wykonał błędne żądanie API, którego z jakiegokolwiek powodu nie można cofnąć.

Uwagi na temat implikacji CI/CD dla usługi Config Service

Uwaga na temat CI/CD: teraz, gdy masz nieodłączną elastyczność usługi konfiguracyjnej opartej na API, masz również tę wadę, że CI/CD oparty na git nie ma już żadnego efektu.

Dobrą wiadomością jest to, że istnieje kilka narzędzi, takich jak Version Admin, do śledzenia zmian konfiguracji i tego, kto dokonał jakiej zmiany:

Zła wiadomość jest taka, że usuwa to wbudowany, skoncentrowany na pull-request framework CI/CD, który wszyscy poznaliśmy i absolutnie uwielbiamy w Edge Delivery. Tak więc, jeśli masz sytuacje, w których chcesz, aby młodszy inżynier zaproponował zmiany, znacznie trudniej będzie im przekazać żądanie ściągnięcia, które wykaże, że ich zmiana konfiguracji jest bezpieczna do przeniesienia.

Sprawę komplikuje fakt, że autoryzacja API opiera się na aktualnie zalogowanym użytkowniku, co sprawia, że próba zintegrowania trwałego zestawu kluczy z potokiem CI/CD jest nieco oporna. Jestem pewien, że da się to zrobić, tylko trzeba będzie trochę pomajsterkować.

W tym celu (w chwili pisania tego tekstu) będziesz musiał wdrożyć własny proces CI/CD, z którym czujesz się komfortowo, w zależności od wielkości i składu Twojej organizacji.

Mamy nadzieję, że to pomoże i prosimy o kontakt, jeśli masz z tym problem!

O autorze

Podoba ci się to, co usłyszałeś? Masz pytania dotyczące tego, co jest dla Ciebie odpowiednie? Chętnie porozmawiamy! Skontaktuj się z nami

Więcej artykułów, które mogą Ci się spodobać