本ページは、Indexクラウドにおけるリアルタイム・エンリッチメントに使用されるコンテナの実装に関するガイドラインおよびベストプラクティスを概説します。
エンドポイントの条件
リアルタイム・エンリッチメントに使用されるコンテナは、以下に記されたエンドポイント 特定の方法でサーバーと通信するように設定されたURL。を開示し、HTTPまたはHTTPS経由で公開されている必要があります。エンドポイントは、SERVER_PORT環境変数を使用し、設定されたポートに公開されていなければいけません。
制御エンドポイント
コンテナは、LivenessエンドポイントとReadinessエンドポイントを公開しなければいけません。
| エンドポイント | 詳細 | 推奨する実装 |
|---|---|---|
| Livenessエンドポイント | コンテナは、Livenessエンドポイントを開示する必要があります。ここで、コンテナが正常であるか、または、再起動が必要か確認するためにオーケストレーションレイヤーを使用します。このエンドポイントは、Kubernetes documentation for liveness endpointsに記載された仕様に沿ってください。 | Index Exchange (Index)は、/heartbeatでエンドポイントを開示することを推奨します。 |
| Readinessエンドポイント | コンテナは、Readinessエンドポイントを提供する必要があります。ここで、コンテナがトラフィックを受信する準備が整っているかどうか確認するために、オーケストレーションレイヤーを使用します。このエンドポイントは、Kubernetes documentation for readiness endpointsに記載された仕様に沿ってください。 | Indexは、/healthcheckでエンドポイントを開示することを推奨します。 |
メトリクスエンドポイント
コンテナが、メトリクスエンドポイントを開示する必要があります。Prometheus形式が、ランタイム・メトリクスを提供します。
| メトリクス | 詳細 |
|---|---|
|
http.server.request.duration |
OpenTelemetry specificationに記載されたヒストグラムの測定方法。ヒストグラムの境界値は、秒単位で[0.0025, 0.005, 0.01, 0.025, 0.05]とします。これらのメトリック境界値は、低レイテンシーの範囲において、より詳細な情報が必要とされたため、OpenTelemetryの仕様とは異なります。このメトリクスにタグ付けされるその他すべての属性は、OpenTelemetry の仕様に従ってください。 |
必要に応じて、その他メトリックを開示できます。Indexは、これらのメトリックを収集し、貴社がアクセスできるようにします。合計メトリックカーディナリティは、10,000以下にしてください。
データパートナー独自の仕様エンドポイント
| エンドポイント | 詳細 | 推奨する実装 |
|---|---|---|
|
パートナー企業は、Indexのリアルタイムデータ接続の仕様に沿ったHTTP POSTリクエストを介して、アクセス可能なエンドポイントを開示しなければいけません。 注意：この仕様は、新しい要件に対応するため継続的に更新します。Indexをサポートするための新しいフィールドがある場合は、ご連絡ください。 |
|
Indexは、 |
ログ
貴社のコンテナは、STDOUTおよび/あるいはSTDERRへ適切に書き込んでください。Indexは、これらのログを収集し、貴社がアクセスできるようにします。コンテナが、過剰なログメッセージを生成しないようにしてください。メトリクスは、コンテナのパフォーマンスを把握するために使用してください。
データパートナー独自のリソース使用要件
現在、Indexクラウド上のコンテナのメインタスクは、リアルタイムに広告リクエストを分類することです。そのため、コンテナ上の負荷と比例し、リソースの使用量が増加します。
Indexクラウド上のコンテナは、10CPUコアおよび10GiBメモリを使用するclassificationエンドポイントに対して、x86アーキテクチャで実行し、一秒あたり100,000クエリを処理できるよう開発されている必要があります。 リソースの使用量は、負荷と比例して増加します。リソースの使用が制限を超える場合は、Indexと話し合ってください。画像は、1GiBを超えないようにしてください。
貴社のコンテナをテストする
Indexクラウドで展開する前に、全てのコンテナをテストする必要があります。パ―トナー企業は、Indexクラウドで展開前に、正確性およびパフォーマンスをローカルで検証してください。
当社のクラウド管理システムで展開する前に、Indexが、貴社のAPIで機能テストを実行します。貴社のコンテナが、このドキュメントに記載された仕様に沿わない場合は、稼動できない場合があります。
Indexテストツールを使用する
Indexが、Indexのクラウド管理システムで、貴社のコンテナが受ける負荷を再現する、テストツールを提供します。このテストツールのためのDockerイメージは、IndexのDocker Hubインスタンスにホストされます。テストツールを利用するには、Index担当者に、ツールへのアクセスが必要なDocker Hubアカウントに関連するメールアドレスを共有してください。
以下のコマンドを使い、コンテナを起動できます。
docker run --network="host" -t --rm --name send-rtd-requests -e COMMAND_LINE_FLAGS="-e TEST_ENDPOINT" indexexchangehub/ext-data-provider-test-tools:2024.11.20上記のコマンドのTEST_ENDPOINTを、テストしたいURLに置き換えてください。例：「http://myapi.com/test」テストツールを更にカスタマイズするには、起動時に、COMMAND_LINE_FLAGS環境変数を使い、コンテナに追加のフラグをパスしてください。利用可能なフラグは、以下の通りです。
-
-c：コンテナが確立するHTTP接続の数を指定デフォルト100（Indexのクラウド管理システムに対して現実的な数） -
-e：テスト用HTTPエンドポイントを指定 -
-l：テストツールのログレベルを指定 -
-q：コンテナが生成する最大QPSを指定貴社のコンテナが、Indexのクラウド管理システムに送るQPSは、コンテナの拡張性により変更します。（水平 vs 垂直）、また貴社が実現したい、ビットストリームの対応範囲によります。 -
-t：ミリ秒単位でHTTPタイムアウトを指定（デフォルトが30で、Indexのクラウド管理システムと一致します）
インストール
ネットワークの条件
Indexクラウド上に展開されたクラウドは、Indexクラウド外部への通信は制限されています。これらのコンテナへのIngressは、Indexクラウド内でのみ利用可能です。そのため、コンテナが起動に必要ないずれの情報（設定ファイル、Seedデータなど）は、コンテナに含むか、設定ファイルを介してマウントされます。
セキュリティ
Indexクラウドに展開された全てのコンテナは、最初のダウンロード、および継続的にSonatype Vulnerability Scannerによりスキャンされます。コンテナが、重大度9～10の脅威に脆弱性があると判断された場合は、Indexクラウドに展開されません。
コンテナは、読み込み専用ファイルシステムで展開され、ルートとして実行することは許可されていません。
設定ファイル
設定ファイルは、Indexクラウド用にカスタマイズ可能です。また、起動時に、TOML formatの希望するロケーションで、貴社のコンテナにマウントできます。
Index Exchangeとコンテナを共有する
Indexとコンテナを共有するには、貴社のイメージをホストするためにDocker Hub repositoryを作成します。Indexのnexus@indexexchange.onmicrosoft.comメールアドレスが、Docker Hubレポジトリにアクセスできるようにします。さらに、Indexクラウドにホストしたいイメージを、貴社のDocker Hubレポジトリにプッシュします。イメージは自動的に削除され、Indexのセキュリティ検出パイプラインに送られます。Indexがイメージを登録後、パートナー企業のレジストリ内のイメージに対する変更は無視されます。
イメージ名は、SemVer versioning systemに従い、各イメージが識別できるようにします（例：2025年3月18日に設計されたことを示す名前「2025_3_18.2」）
貴社のコンテナを更新する
貴社のコンテナに対する全ての変更は、Indexが適用します。Indexは、展開の予定を通知するために最低1営業日が必要です。更新は、1週間に2回までです。
Kubernetesポリシー
コンテナは、専用のNamespace（名前空間）に展開します。Pods namespaceからのEgress In Kubernetes, egress refers to the traffic that flows out of a cluster, from a pod to an external endpoint.Egress traffic can be used to access external services such as databases, APIs, and other services running outside of the cluster.は、デフォルトで拒否されます。Egressポリシーに対する例外を申請できます。コンテナは、非rootアクセス、ユーザー ID 1000、グループID 1000、読み取り専用ファイルシステムのセキュリティコンテキストで実行されます。
HelmとArgo CDを使いインストールする
Index Exchangeは、Helmチャートを使い貴社のコンテナをIndexのKubernetes環境に展開します（必要に応じて提供します）。Helmチャートが、遅延を軽減させるために、ホスト・ネットワーキングを使い、貴社のコンテナのAPIエンドポイントを開示します。
ロールアウト戦略
コンテナの新しいバージョンは、段階的に展開されます。 始めは、小規模なインスタンスのセットを起動します。これらのインスタンスのパフォーマンスが良好な場合、残りのインスタンスも起動されます。期待以下のパフォーマンスの場合、自動的に前のバージョンにロールバックされます。
期待される分析
二つのメトリクスが、アプリケーションのパフォーマンスを決定します。
-
Classification（分類）エンドポイントのレイテンシーは、SLA（5ミリ秒）を超えてはいけません。
-
Classificationエンドポイントのエラーレートは、5%以下である必要があります。
追加で確認を希望する場合、Indexにご連絡ください。追加の確認は、ロールアウト戦略に組み込むことができます。
期待する動作
ロールアウト中、新しいバージョンのコンテナ（カナリアセット）は、すぐに実際の分類リクエストを受け取り始めます。古いバージョンの既存のインスタンス（安定セット）は、実際の分類リクエストを受信し続けます。
両セットのインスタンス総数は、一定のままです。カナリアセットがスケールアップ（増加）するにつれて、安定セットは比例して減少します。カナリアセットが予想されるインスタンス数に達すると、古い安定セットは完全に削除され、カナリアセットが新しい安定セットになります。
本番環境でのコンテナのモニタリング
現在、Indexが、以下の条件を基に、貴社のコンテナのパフォーマンスを監査しています。
-
メモリとCPUの使用が、上記のガイドラインに記載された、リソース使用量に沿っている
-
Classification（分類）エンドポイントのレイテンシーは、SLA（5ミリ秒）を超えるリクエストの割合
-
エラーになるリクエストの割合
ご要望に応じて、これらの指標をお客様と共有します。近日中に、Indexが、Grafanaダッシュボードを提供するので、これらのメトリクスを自分で監視できるようになります。
