AEM Edge 配信をファイルベースの設定から設定サービスに移行するためのガイド

注: これは、Edge Delivery Services とドキュメント作成に関するやや高度なトピックです。EDS とドキュメント作成の概要については、まずこちらを参照してください。

ファイルベースの AEM Edge 配信設定と設定サービスの背景

Adobe が初めて Edge Delivery Services (社内では Helix と呼ばれていました) をリリースしたとき、サイト全体の主要な構成はすべて、サイトのリポジトリにチェックインされた構成ファイルを使用して実行されていました。新しい構成のデプロイは、リポジトリのmainブランチにプッシュすることによって実行され、その構成がサイトにプッシュされます。この方法の欠点は、特定のリポジトリをサイトとドキュメント リポジトリに直接結び付ける必要があることです。そうすると、単一のコード リポジトリで複数のサイトを駆動することができなくなり、さらには単一のサイトの複数のバージョン (コンテンツや構成のステージング用のdev / stg / prdスタイルの環境など) も駆動できなくなります。

この結果とその他の技術的な懸念から、Adobe はConfiguration Serviceを中心とした新しいアーキテクチャ設計に移行しています。このパラダイムでは、設定は Adobe の API 駆動型設定サービスで一元的に保存およびバージョン管理され、このサービスに移行すると、Edge Delivery プロジェクト内のファイルはサイトに影響を与えなくなります。

Config Service への移行の前提条件

https://www.aem.live/docs/config-service-setup#prerequisitesに記載されているように、Config Service への移行を開始する前に、まず Adobe ユーザーが Github 組織の管理者としてマッピングされ、Config Service で変更を行う権限があることを確認する必要があります。普段やり取りしている Adobe の技術担当者が、この件について案内してくれるはずです。

Config サービスへの移行によって影響を受けるエンドポイントと構成サーフェス

これは、Edge Delivery プロジェクトの次の構成サーフェスに影響します。

• コンテンツ バス マッピング: プロジェクトが DA (または AEM/ユニバーサル エディターや Sharepoint などの他の場所) 内の場所にマップされる/fstab.yaml内の構成が、現在、構成サービスにあります。これは、単一のリポジトリで複数のサイトを操作できるようにする最も重要な部分です (コード リポジトリとコンテンツ リポジトリが密接にリンクされていないことを意味していたため、以前は「リポジトリレス」セットアップと呼ばれていました)。

• クエリインデックス: すべての言語のインデックス設定は、以前はプロジェクトに保存されていました。 /helix-query.yaml

• サイトマップの構成: 以前/helix-sitemap.yamlで行われたサイトマップの構成は、Config Service に保存されます。

• Sidekick 構成: 以前は git プロジェクトに保存されていましたが、現在は別の場所にある 2 種類の Sidekick 構成があります。

  • DA プラグイン:以前、DA の初期の頃は、DA プラグインをコード リポジトリの/tools/sidekick/config.jsonファイルに保存していました。これは、日付ピッカー、AEM タグ プラグインなどのさまざまな DA UI 拡張機能のためのものです。これは、コードベースではなく、DA 自体の DA 構成のLibraryシートに保存されるようになりました。
  • サイドキック プラグイン/設定:クイック編集や AEM 実験などのその他の AEM サイドキック設定は、DA ではなく設定サービスに直接保存されるようになりました。EDS git プロジェクトの Sidekick 構成は、もはや効果がありません。

• HTTP ヘッダー構成: これは以前は DA のheadersシートに保存されていましたが、現在は構成サービスにプッシュされます。これは、特定のホストにaccess-control-allow-originヘッダーを貼り付けるなどの CORS 構成用です。

• Helix プレビュー/公開認証: 認証されたプレビュー/公開アクセス制御では、シートベースの認証モデルを使用しています。このモデルでは、 https://da.live/sheet#/[orgname]/[sitename]/.helix/configにdataシートがあり、ユーザー/プロファイルにマップされる個々の Adobe エンティティ ID のadmin.role.authorまたはadmin.role.publishロールがリストされます。これは現在 Config Service で廃止されており、これらのプレビュー/公開ロールだけでなくアクセス リクエストについてもユーザーは Config Service で直接管理されます。また、以前は、認証された公開には、特定の組織でのユーザーのログインにマッピングされる「[email protected]」のような判読できない Adobe プロファイル/ユーザー ID を使用する必要がありました。現在、Config Service では、Helix により、判読できないエンティティ ID の代わりに電子メール アドレスを使用できるようになり、プレビュー/公開の問題に遭遇したときにユーザーが「アクセスをリクエスト」することもできるようになりました。その後、DA の管理インターフェース アプリに表示され、アクセス リクエストを承認/拒否できます。

• Robots.txt 構成: 以前は git プロジェクトの/robots.txtに保存されていましたが、現在は Config Service で構成されます。

• CDN 構成: 以前は DA の.helix/configシートに保存されていましたが、現在は Config Service にプッシュされています。これは次のような値を設定するためです:

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

既存のファイルベースのエッジ配信サイトを構成サービスに移動する手順

AEM Admin (Helix) APIには、ファイルベースの Edge Delivery セットアップを Config Service に自動的に移行できるmigrateコマンドがあります。ただし、いくつか注意点がありますので、これについて知っておくべきことを以下に示します。

まず、ファイルベースの構成を使用して DA 上に作成された既存のサイトがあると仮定します (私自身もそのようなサイトをいくつか持っており、少数派かもしれませんが、これは私のブログ投稿なので、独自のユースケースに合わせて手順を再評価する必要があります)。

手順:

1. 組織の管理者であることを確認してください。上記のとおり、Adobe と協力して、Github 組織にadminがあることを確認してください。https://tools.aem.live/tools/site-admin/index.htmlに移動してログインし、これを検証してください。正常に動作している場合は、200リクエストが成功しているはずです。 https://admin.hlx.page/config/[orgname]/sites.json

2. 認証トークンを取得します。Shift + Ctrl + I または Shift + cmd + I を実行して開発者ツールをポップアップし、上記のsites.jsonリクエストを確認します。ネットワーク タブを開いてヘッダーを確認すると、 x-auth-token値が表示されます。この値は、AEM 構成サービスと対話するための次の API リクエストで使用する必要があるベアラー トークンなので、コピーします。

3. サイトのコピーを作成する:本番環境で実行する前にこのプロセスをテストできるように、サイト (ファイルベースの構成を持つサイト) でテスト実行を行うことをお勧めします。新しい EDS リポジトリとサイトを作成し、現在のサイトと同じコードベースを入力します (開発リポジトリがまだない場合)。理想的には、開発コンテンツ ソースも用意して、完全に装備され、操作可能なサンドボックスで操作できるようにします。

4. 移行コマンドのドライランを実行します。 次のコマンドを実行すると、ファイルベースから 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"
   
   これが機能する場合は、次のような検証テキストが出力され、移行が機能するかどうかがわかります。私の場合、これは移行の準備ができていず、修正すべき点があることを意味します。
   
   "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",
   
   また、呼び出し時に 400 の不正なリクエストを受け取った場合は、HTTP レスポンスのx-errorヘッダーを使用することもできます。これにより、移行のドライ ラン リクエストに問題があるかどうかもわかります。

   

   この場合、このエラーは、AEM Sidekick プラグインのリストで、 /tools/sidekick/config.jsonの最初のプラグインが無効であることを示しています。この方法でのプラグインの構成は、Config Service ではサポートされなくなりました。この例では、このプラグインを DA プラグインの DA ライブラリ シートに移行する必要があります。

   

5. 上記のように検証の問題を修正します。発生した問題をすべて確認して修正し、検証リクエストを再実行する必要があります。
   
   プロジェクト内で Sidekick プラグインとして定義されている既存のプラグインをすべて取得し、DA に配置します。このような Sidekick プラグインの問題の場合、DA プラグインはシートの「ライブラリ」タブのhttps://da.live/config#/[orgname]/[sitename]/で設定されます。

   

   あるいは次のような問題もあります:

   

   これは、ヘッダー内に、サポートされなくなった不正なプロパティがいくつかあったことを示しています (または、そもそもサポートされておらず、何も壊れていなかったため、誤って残されていた可能性があります)。
   
   これらの問題に対処したら、移行自体を実行する準備が整います。

6. クリーンかつ検証済みの構成を構成サービスにプッシュ/移行します。構成をプッシュするには、次のコマンドを使用します。
   
   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"
   
   基本的には上記と同じコマンドですが、 GETの代わりにPOSTを使用します。これにより、構成サービスに移行します。

7. 検証:移行したらすぐに検証する必要がある項目がいくつかあります。

   1. インデックスの検証: https://tools.aem.live/tools/index-admin/index.htmlに移動して、インデックスが適切に取り込まれたかどうか検証します。
   2. サイトマップの検証: https://tools.aem.live/tools/sitemap-admin/index.htmlにアクセスし、すべてのサイトマップが送信されたことを確認します。
   3. ユーザーの検証: https://tools.aem.live/tools/user-admin/index.html?org={orgname}&site={sitename}に移動し、プレビュー/公開ユーザーがそこに表示されていることを確認します。
   4. DA でユーザーを検証します。 https://da.live/apps/aem-permissions#/{orgname}/{sitename}に移動すると、DA に公開されるプレビュー/公開権限のユーザーフレンドリーなリストが表示されます。ここで、
   5. プレビュー/公開の検証:プレビュー/公開権限を持つユーザーとしてログインしている場合は、適切にプレビュー/公開できるかどうかを確認します。プレビューや公開のアクセス権を持たないユーザーを取得し、適切にロックダウンされていることを確認します。
   6. サイトに必要と思われるその他のさまざまな検証。

8. バーンイン:チームと QA およびバーンインを実施し、発生する可能性のあるその他のプレビュー/公開の問題を修正し、発生する可能性のあるその他の問題を洗い出すために新しい構成を少なくとも 1 週間バーンインします。

9. 構成ファイルのクリーンアップ: バーンインが完了すると、リポジトリ内の構成は必要なくなるため、これらを 1 つずつ削除できるようになります。誰かが何らかの理由で取り消しできない誤った API リクエストを行った場合に備えて、DR の目的で、現在の構成のクリーンなコピーをバージョン管理のために Git に保存しておくことをお勧めします。

Config Service の CI/CD への影響に関するメモ

CI/CD に関する注意: API 駆動型の構成サービスには固有の柔軟性がありますが、git 駆動型の CI/CD が効力を持たないという欠点も生じています。

幸いなことに、構成の変更と誰がどのような変更を行ったかを追跡するための Version Admin などのツールがあります。

残念なことに、これにより、Edge Delivery で私たち全員が知っていて愛用している、組み込みのプル リクエスト中心の CI/CD フレームワークが削除されてしまいます。したがって、ジュニア エンジニアに変更を提案してもらいたい状況では、構成変更がロールフォワードしても安全であることを示すプル リクエストをジュニア エンジニアが提出するのは非常に困難になります。

API の認証は現在ログインしているユーザーに基づいているため、さらに複雑になり、永続的なキーセットを CI/CD パイプラインに統合しようとすると、若干抵抗が生じます。きっとできると思います。ただ、少し手直しが必要です。

したがって、このためには (この記事の執筆時点では)、組織の規模と構成に合わせて、使いやすい独自の CI/CD プロセスを展開する必要があります。

これがお役に立てば幸いです。何か問題があれば、ぜひご連絡ください。

著者について

聞いてみてどうでしたか？自分に合ったものについてご質問がありますか?ぜひご相談ください！お問い合わせ