Adobe Experience Manager as a Cloud Service の OSGi の設定

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

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

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

OSGi の設定ファイル

設定の変更は、 AEM プロジェクトのコードパッケージ（ui.apps）で、実行モード固有の 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 設定形式に従います。

実行モードの解決

実行モードを使用すると、特定の 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 全体に対して効果的です。

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

OSGi 設定値のタイプ

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

1. インライン値：OSGi 設定にハードコーディングされ、Git に保存される値です。次に例を示します。

   {
      "connection.timeout": 1000
   }
   

2. シークレット値：セキュリティ上の理由から Git に保存してはいけない値です。次に例を示します。

   {
   "api-key": "$[secret:server-api-key]"
   } 
   

3. 環境固有値：開発環境間で変化する値なので、実行モードで正確にターゲットを設定できません（Adobe Experience Manager as a Cloud Service には 1 つの dev 実行モードのみ存在するため）。次に例を示します。

   {
    "url": "$[env:server-url]"
   }
   

   1 つの OSGi 設定ファイルで、これらの設定値タイプの任意の組み合わせを併用できます。次に例を示します。

   {
   "connection.timeout": 1000,
   "api-key": "$[secret:server-api-key]",
   "url": "$[env:server-url]"
   }
   

適切な OSGi 設定値タイプの選択方法

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

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

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

インライン設定値を使用する場合

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

• Git でガバナンスとバージョン履歴に基づいて管理される
• 値はコードデプロイメントに暗黙的に結び付けられる
• デプロイメントに関する検討事項や調整を追加する必要がない

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

非シークレットの環境固有の設定値を使用する場合

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

• 非シークレットの環境固有の設定は、パブリッシュ層とプレビュー層で異なる設定値、または開発環境(ローカル開発インスタンスを含む)で異なる値に対してのみ使用します。
• プレビュー層をパブリッシュ層と異なる必要がある場合のシナリオの他に、ステージと実稼動の非シークレット値のOSGi設定で標準のインライン値を使用します。 これに関連して、ステージング環境と実稼働環境に対して、環境固有の設定を使用して、実行時に設定を変更しやすくすることは勧められません。これらの変更は、ソースコード管理を通じて導入する必要があります。

シークレットの環境固有の設定値を使用する場合

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

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

OSGi 設定の作成

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

OSGi 設定の書き込み

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

1. IDE で ui.apps プロジェクトを開き、新しい OSGi 設定が有効となる実行モードをターゲットに設定する config フォルダー（/apps/.../config.<runmode>）を探すか作成します。
2. この config フォルダーに、新しい <PID>.cfg.json ファイルを作成します。PID は OSGi コンポーネントの永続的な ID です。通常、OSGi コンポーネントの実装の完全なクラス名です。次に例を示します。
   /apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
   OSGi 設定ファクトリのファイル名には <PID>-<factory-name>.cfg.json 命名規則を使用します。
3. 新しい .cfg.json ファイルを開き、JSON OSGi 設定形式に従って、OSGi プロパティと値のペアのキー／値の組み合わせを定義します。
4. 変更を新しい .cfg.json ファイルに保存します。
5. 新しい追加 OSGi 構成ファイルを Git にコミットします。

AEM SDK Quickstart を使用した OSGi 設定の生成

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

1. AEM SDK Quickstart Jar の AEM Web コンソールに管理者ユーザーとしてログインします。
2. OSGi／設定に移動します。
3. 設定するには、該当する OSGi コンポーネントを見つけ、タイトルをタップして編集に入ります。
   
4. 必要に応じて Web UI を使用して OSGi 設定プロパティの値を編集します。
5. 永続 ID（PID）を安全な場所に記録します。これは後で OSGi 設定 JSON の生成に使用します。
6. 「保存」をタップします。
7. OSGi／OSGi インストーラー設定プリンターに移動します。
8. 手順 5 でコピーした PID に貼り付け、シリアル化形式が「OSGi Configurator JSON」に設定されていることを確認します。
9. 「印刷」をタップします。
10. JSON 形式の OSGi 設定は、「シリアライズされた設定プロパティ」セクションに表示されます。
    
11. IDE で ui.apps プロジェクトを開き、新しい OSGi 設定が有効となる実行モードをターゲットに設定する config フォルダー（/apps/.../config.<runmode>）を探すか作成します。
12. この config フォルダーに、新しい <PID>.cfg.json ファイルを作成します。PID は、手順 5 と同じ値です。
13. 手順 10 のシリアライズされた設定プロパティを .cfg.json ファイルに貼り付けます。
14. 変更を新しい .cfg.json ファイルに保存します。
15. 新しい追加 OSGi 構成ファイルを Git にコミットします。

OSGi 構成プロパティの形式

インライン値

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

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

環境固有の設定値

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

use $[env:ENV_VAR_NAME]

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

シークレットの設定値

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

use $[secret:SECRET_VAR_NAME]

変数の命名

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

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

• 最小長：2
• 最大長：100
• 正規表現 [a-zA-Z_][a-zA-Z_0-9]* と一致する必要があります。

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

デフォルト値

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

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

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

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

ローカル開発

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

変数は、実行時にローカル 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 は、そのローカルディレクトリを使用して設定する必要があります。

オーサーとパブリッシュの設定

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

• 実行モードの解決の節で説明したように、config.author と config.publish の別個の OSGi フォルダーを使用する必要があります。
• 独立した変数名を作成する場合、次の 2 つのオプションを使用できます。

  • 最初のオプション（推奨）：異なる値を定義するように宣言されたすべての OSGI フォルダー（config.author と config.publish など）で、同じ変数名を使用します。例：

    $[env:ENV_VAR_NAME;default=<value>]：デフォルトは、その層（オーサーまたはパブリッシュ）のデフォルト値です。環境変数を Cloud Manager API またはクライアントを使用して設定する場合は、この API リファレンスドキュメントで説明されているように、「service」パラメーターを使用して層を区別します。「service」パラメーターは、変数の値を適切な OSGI 層にバインドします。「author」、「publish」、「preview」のいずれかです。

  • 2 つ目のオプション：author_<samevariablename> や publish_<samevariablename> などのプレフィックスを使用して個別の変数を宣言します。

設定例

以下の例では、ステージング環境と実稼働環境に加えて、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 形式

API の設定方法については、こちらのページを参照してください。

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 を使用した値の取得

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

詳しくは、こちらのページを参照してください。

API を使用した値の削除

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

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

詳しくは、こちらのページを参照してください。

コマンドラインを使用した値の取得

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

コマンドラインを使用した値の設定

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

コマンドラインを使用した値の削除

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

変数の数

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

シークレットおよび環境固有の設定値のデプロイメントに関する考慮事項

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

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

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

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

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

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