Adobe Experience Manager as a Cloud Service の OSGi の設定 configuring-osgi-for-aem-as-a-cloud-service

OSGi は Adobe Experience Manager（AEM）のテクノロジースタックの基本要素です。AEM とその設定の複合バンドルを制御するために使用されます。

OSGi で提供されている標準化されたプリミティブにより、サイズが小さく再利用やコラボレーションが可能なコンポーネントからアプリケーションを構築できます。これらのコンポーネントからアプリケーションを作成し、デプロイすることができます。これにより、OSGi バンドルの管理が容易になり、バンドルを個別に停止、インストール、開始できます。相互依存関係は自動的に処理されます。各 OSGi コンポーネントは、様々なバンドルの 1 つに含まれています。詳しくは、OSGi の仕様を参照してください。

AEM コードプロジェクトに含まれる設定ファイルを使用して、OSGi コンポーネントの設定を管理できます。

OSGi の設定ファイル osgi-configuration-files

設定の変更は、 AEM プロジェクトのコードパッケージ（ui.config）で、実行モード固有の config フォルダーの下に設定ファイル（.cfg.json）として定義されます。

/apps/example/config.<runmode>

OSGi 設定ファイルは、Apache Sling プロジェクトで定義されている .cfg.json 形式を使用した JSON ベース形式です。

OSGi 設定は Persistent Identity（PID）を介して OSGi コンポーネントをターゲットに設定します。デフォルトは、OSGi コンポーネントの Java™ クラス名です。例えば、OSGi サービス用の OSGi 設定を提供するには、次のように実装します。

com.example.workflow.impl.ApprovalWorkflow.java

OSGi 設定ファイルは次の場所で定義されます。

/apps/example/config/com.example.workflow.impl.ApprovalWorkflow.cfg.json

cfg.json OSGi 設定形式に従います。

実行モードの解決 runmode-resolution

実行モードを使用すると、特定の OSGi 設定を特定の AEM インスタンスにターゲット設定できます。実行モードを使用するには、次の形式で、/apps/example（「example」はプロジェクト名）の下に config フォルダーを作成します。

/apps/example/config.<author|publish>.<dev|stage|prod>/

config フォルダー名で定義された実行モードが AEM で使用される実行モードと一致する場合、このようなフォルダー内の OSGi 設定が使用されます。

例えば、AEM がオーサーと開発の実行モードを使用している場合、/apps/example/config.author/ および /apps/example/config.author.dev/ の設定ノードが適用され、/apps/example/config.publish/ および /apps/example/config.author.stage/ の設定ノードは適用されません。

同じ PID に複数の設定が該当する場合は、一致する実行モードの数が最も大きい設定が適用されます。

このルールの精度は PID レベルです。つまり、/apps/example/config.author/ で同じ PID の一部のプロパティと、/apps/example/config.author.dev/ で同じ PID のより具体的なプロパティを定義することはできません。一致する実行モードの数が最も多い設定は、PID 全体に対して効果的です。

ローカルで開発する場合、実行モードの起動パラメーター -r を使用して、実行モードの OSGI 設定を指定します。

$ java -jar aem-sdk-quickstart-xxxx.x.xxx.xxxx-xxxx.jar -r publish,dev

実行モードの検証

AEM as a Cloud Service の実行モードは、環境のタイプとサービスに基づいて適切に定義されています。使用可能な AEM as a Cloud Service 実行モードの完全なリストをご確認ください。

実行モードで指定された OSGi 設定値は、次の方法で検証できます。

結果には、選択した層のすべての OSGi コンポーネント設定と、該当する OSGi 設定値が表示されます。 これらの値は、/apps/example/osgiconfig/config.<runmode(s)> の下にある AEM プロジェクトのソースコード内の OSGi 設定値と相互参照できます

適切な OSGi 設定値が適用されていることを確認するには：

OSGi 設定値のタイプ types-of-osgi-configuration-values

Adobe Experience Manager as a Cloud Service で使用できる OSGi 設定値は 3 種類あります。

適切な OSGi 設定値タイプの選択方法 how-to-choose-the-appropriate-osgi-configuration-value-type

OSGi では、インライン OSGi 設定値を使用する場合が多くあります。環境固有の設定は、開発環境間で値が異なる特定の使用例に対してのみ使用します。

環境固有の設定は、インライン値を含む、従来の静的に定義された OSGi 設定を拡張し、Cloud Manager API を介して OSGi 設定値を外部で管理できるようにします。インライン値を定義して Git に保存する一般的で従来の方法を使用する必要がある場合と、値を環境固有の設定に抽象化する必要がある場合を理解することが重要です。

次のガイダンスは、非シークレットの場合とシークレットの場合の環境固有の設定を使用する手順を示しています。

インライン設定値を使用する場合 when-to-use-inline-configuration-values

インライン設定の値は標準的なアプローチと見なされるので、可能であればこの設定を使用してください。インライン設定には次のような利点があります。

OSGi 設定値を定義する場合は、インライン値から開始し、必要な場合にのみシークレット設定または環境固有の設定を選択します。

非シークレットの環境固有の設定値を使用する場合 when-to-use-non-secret-environment-specific-configuration-values

非シークレットの設定値に対しては、プレビュー層で値が異なる場合や、開発環境間で値が異なる場合にのみ、環境固有の設定（$[env:ENV_VAR_NAME]）を使用してください。これには、ローカル開発インスタンスと、Adobe Experience Manager as a Cloud Service 開発環境が含まれます。プレビュー層に一意の値を設定する場合を除き、Adobe Experience Manager as a Cloud Service の非シークレットの環境固有の設定をステージ環境または実稼動環境で使用しないでください。

シークレットの環境固有の設定値を使用する場合 when-to-use-secret-environment-specific-configuration-values

Adobe Experience Manager as a Cloud Service では、セキュリティ上の理由から、パスワード、プライベート API キー、Git に保存できない他の値など、シークレットの OSGi 設定値に対して環境固有の設定（$[secret:SECRET_VAR_NAME]）を使用する必要があります。

シークレットの環境固有の設定を使用して、ステージングや実稼働などのあらゆる Adobe Experience Manager as a Cloud Service 環境にシークレットの値を保存します。

OSGi 設定の作成 creating-osgi-configurations

以下に説明するように、OSGi 設定を作成する方法は 2 とおりあります。前者の方法は、通常、開発者によってよく知られている OSGi のプロパティと値を持つカスタム OSGi コンポーネントの設定に使用され、後者は AEM が提供する OSGi コンポーネントの設定に使用されます。

OSGi 設定の書き込み writing-osgi-configurations

JSON 形式の OSGi 設定ファイルは、AEM プロジェクト内から直接手動で書き込むことができます。これは、よく知られている OSGi コンポーネント、特に、設定を定義した同じ開発者により設計および開発されたカスタム OSGi コンポーネントに対して、OSGi 設定をすばやく作成する方法です。この方法は、同じ OSGi コンポーネントの設定を様々な実行モードフォルダーにコピー／貼り付け、更新する場合にも使用できます。

AEM SDK Quickstart を使用した OSGi 設定の生成 generating-osgi-configurations-using-the-aem-sdk-quickstart

AEM SDK Quickstart Jar の AEM Web コンソールは、OSGi コンポーネントの設定、および JSON として OSGi 設定を書き出すために使用できます。これが役に立つのは、AEM 提供の OSGi コンポーネントを設定する際に、その OSGi プロパティと値の形式を、AEM プロジェクトで OSGi 設定を定義する開発者がよく理解できない可能性がある場合です。

OSGi 構成プロパティの形式 osgi-configuration-property-formats

インライン値 inline-values

インライン値は、標準の JSON 構文に従って、標準の名前と値のペアとして形式設定されます。例：

{
   "my_var1": "val",
   "my_var2": [ "abc", "def" ],
   "my_var3": 500
}

環境固有の設定値 environment-specific-configuration-values

OSGi 設定では、環境ごとに定義する変数にプレースホルダーを割り当てる必要があります。

use $[env:ENV_VAR_NAME]

顧客は、カスタムコードに関連する OSGi 設定プロパティに対してのみ、この手法を使用する必要があります。アドビ定義の OSGi 設定を上書きする場合は使用しないでください。

シークレットの設定値 secret-configuration-values

OSGi 設定では、環境ごとに定義するシークレットにプレースホルダーを割り当てる必要があります。

use $[secret:SECRET_VAR_NAME]

変数の命名 variable-naming

環境固有の設定値とシークレットの設定値の両方に次のことが適用されます。

変数名は、次の規則に従う必要があります。

変数の値は 2048 文字を超えないようにします。

デフォルト値 default-values

環境固有の設定値とシークレットの設定値の両方に次のことが適用されます。

環境単位の値を設定しない場合、補間が行われないので、プレースホルダーは実行時に置き換えられず、配置されたままになります。これを回避するには、プレースホルダーの一部として次の構文でデフォルト値を指定します。

$[env:ENV_VAR_NAME;default=<value>]

デフォルト値を指定すると、プレースホルダーは、環境ごとの値（指定した場合）または指定したデフォルト値に置き換えられます。

ローカル開発 local-development

環境固有の設定値とシークレットの設定値の両方に次のことが適用されます。

変数は、実行時にローカル AEM によって取得されるように、ローカル環境で定義できます。例えば、Linux® の場合は次のようになります。

export ENV_VAR_NAME=my_value

設定で使用される環境変数を設定し、AEM を起動する前に実行する、単純な bash スクリプトを記述することをお勧めします。https://direnv.net/ などのツールを使うと、このアプローチを簡略化できます。すべてのユーザー間で共有できる場合は、値のタイプに応じて、値をソースコード管理にチェックインできることがあります。

シークレットの値はファイルから読み取られます。したがって、シークレットを使用するプレースホルダーごとに、シークレット値を含むテキストファイルを作成する必要があります。

例えば、$[secret:server_password] を使用する場合は、server_password という名前のテキストファイルを作成する必要があります。これらのシークレットファイルはすべて同じディレクトリに保存する必要があり、フレームワークプロパティ org.apache.felix.configadmin.plugin.interpolation.secretsdir は、そのローカルディレクトリを使用して設定する必要があります。

org.apache.felix.configadmin.plugin.interpolation.secretsdir は Sling フレームワークのプロパティです。そのため、このプロパティは felix コンソール（/system/console）では設定しませんが、システムの起動時に使用する sling.properties ファイルで設定します。このファイルは、抽出された Jar/install フォルダー（crx-quickstart/conf）の /conf サブディレクトリにあります。

例：「crx-quickstart/conf/sling.properties」ファイルの末尾に次の行を追加して、「crx-quickstart/secretsdir」をシークレットフォルダーとして設定します。

org.apache.felix.configadmin.plugin.interpolation.secretsdir=${sling.home}/secretsdir

オーサーとパブリッシュの設定 author-vs-publish-configuration

OSGi プロパティで、オーサーとパブリッシュで異なる値が必要な場合：

設定例 configuration-examples

以下の例では、ステージング環境と実稼働環境に加えて、3 つの開発環境があると仮定します。

例 1

OSGi プロパティ my_var1 の値を、ステージング環境と実稼働環境では同じ値にしつつ、3 つの開発環境ではそれぞれ異なる値にします。

{
 "my_var1": "val",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1" : "$[env:my_var1]"
 "my_var2": "abc",
 "my_var3": 500
}

例 2

OSGi プロパティ my_var1 の値をステージング環境、実稼働環境、3 つの開発環境でそれぞれ異なる値にします。したがって、開発環境ごとに my_var1 の値を設定するには、Cloud Manager API を呼び出す必要があります。

{
 "my_var1": "val1",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1": "val2",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1" : "$[env:my_var1]"
 "my_var2": "abc",
 "my_var3": 500
}

例 3

OSGi プロパティ my_var1 の値をステージング環境、実稼働環境、1 つの開発環境では同じ値、他の 2 つの開発環境では異なる値にします。この場合は、ステージング環境および実稼働環境と同じ値にする必要がある開発環境も含め、Cloud Manager API を呼び出して各開発環境の my_var1 の値を設定する必要があります。フォルダー config に設定された値は継承されません。

{
 "my_var1": "val1",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1" : "$[env:my_var1]"
 "my_var2": "abc",
 "my_var3": 500
}

これを行う別の方法は、config.dev フォルダーの置き換えトークンのデフォルト値を、config フォルダーと同じ値に設定することです。

{
 "my_var1": "val1",
 "my_var2": "abc",
 "my_var3": 500
}

{
 "my_var1": "$[env:my_var1;default=val1]"
 "my_var2": "abc",
 "my_var3": 500
}

プロパティ設定用の Cloud Manager API 形式 cloud-manager-api-format-for-setting-properties

Cloud Manager API とその設定方法について詳しくは、Adobe Developer web サイトの Adobe Cloud Manager を参照してください。

API を使用した値の設定 setting-values-via-api

API を呼び出すと、一般的なカスタマーコードのデプロイメントパイプラインと同様に、新しい変数と値がクラウド環境にデプロイされます。オーサーサービスおよびパブリッシュサービスが再起動され、新しい値が参照されます（通常、数分かかります）。

PATCH /program/{programId}/environment/{environmentId}/variables

[
        {
                "name" : "MY_VAR1",
                "value" : "plaintext value",
                "type" : "string"  <---default
        },
        {
                "name" : "MY_VAR2",
                "value" : "<secret value>",
                "type" : "secretString"
        }
]

API を使用した値の取得 getting-values-via-api

GET /program/{programId}/environment/{environmentId}/variables

詳しくは、Cloud Manager API を参照してください。

API を使用した値の削除 deleting-values-via-api

PATCH /program/{programId}/environment/{environmentId}/variables

変数を削除するには、空の値を含めます。

詳しくは、Cloud Manager API を参照してください。

コマンドラインを使用した値の取得 getting-values-via-cli

$ aio cloudmanager:list-environment-variables ENVIRONMENT_ID
Name     Type         Value
MY_VAR1  string       plaintext value
MY_VAR2  secretString ****

コマンドラインを使用した値の設定 setting-values-via-cli

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --variable MY_VAR1 "plaintext value" --secret MY_VAR2 "some secret value"

コマンドラインを使用した値の削除 deleting-values-via-cli

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --delete MY_VAR1 MY_VAR2

変数の数 number-of-variables

1 つの環境につき最大 200 個の変数を宣言できます。

シークレットおよび環境固有の設定値のデプロイメントに関する考慮事項 deployment-considerations-for-secret-and-environment-specific-configuration-values

シークレットと環境に固有の設定値は Git の外部に存在するので、Adobe Experience Manager as a Cloud Service の正式なデプロイメントメカニズムには含まれません。そのため、顧客が管理および統括し、Adobe Experience Manager as a Cloud Service のデプロイメントプロセスに統合する必要があります。

前述したように、API を呼び出すと、一般的なカスタマーコードのデプロイメントパイプラインと同様に、新しい変数と値がクラウド環境にデプロイされます。オーサーサービスおよびパブリッシュサービスが再起動され、新しい値が参照されます（通常、数分かかります）。通常のコードのデプロイメント中に Cloud Manager によって実行される品質ゲートおよびテストは、このプロセス中は実行されません。

通常、Cloud Manager で API を使用するコードをデプロイする前に、API を呼び出して環境変数を設定します。場合によっては、コードが既にデプロイされた後で既存の変数を変更する必要があります。

予定されている顧客コードのデプロイメントが、新しい値を持つ既存の変数に依存している場合があります。これは、現在のコードには適していません。これが問題となる場合は、変数の変更を追加方式で行うことをお勧めします。そのためには、古いコードが新しい値を参照しないように、古い変数の値を変更する代わりに、新しい変数名を作成します。後日、新しいカスタマーリリースが安定したら、古い値を削除できます。

同様に、変数の値はバージョン管理されないので、コードのロールバックによって、新しい値を参照することで問題を引き起こす場合があります。上記の変数追加方式戦略は、この場合にも役に立ちます。

このような変数の追加方式戦略は、数日前のコードを再デプロイする必要がある災害復旧シナリオにも役に立ちます。コードが参照する変数名と値は変わりません。これは、顧客が古い変数を削除する前に数日間待機するという手法に依存しています。この手法を使用していない場合、古いコードには参照できる適切な変数はありません。