Kibana Dashboards APIにおける後方互換性の意味

テクニカルプレビュー中はリリース間でAPIの仕様が変更される可能性があります。[1]現在はこれは該当しません。一般提供（GA）開始とは、以下のことを意味します。

• 完全な後方互換性。新しいフィールドやパネルの種類は今後追加されますが、既存のフィールドや動作は変更されません。今後、互換性を損なうような変更を行う場合は、非常に慎重に検討し、新しいメジャーバージョンでのみ導入します。

• 本番環境での利用に対応し、完全にサポートさ。このAPIには、Elasticの完全なサポート保証が付いています。本番環境では、自動化された導入、環境の昇格、およびプログラムによるダッシュボード管理に安全にご利用いただけます。

タグ、マークダウン、リンクパネル用の新しいKibana APIエンドポイント

Elastic 9.5では、タグ用の新しいスタンドアロンエンドポイントも導入され、ダッシュボードの分類やフィルタリングが可能になりました。専用のCRUDエンドポイントによりプログラムによる管理が可能になり、複数の環境にわたって大規模にダッシュボードを整理しやすくなりました。

新しいマークダウンおよびリンクパネルエンドポイントは現在Serverlessで利用可能で、次回のスタックリリース（9.6）に搭載される予定です。

Kibana Dashboards APIはどのようなパネル型をサポートしていますか？

Dashboards APIは、9.5のすべての値渡しパネル（再利用のために保存されたライブラリパネルとは対照的に、ダッシュボードで直接定義されたもの）をサポートしています。サポートされているすべてのパネル型には、型指定され検証済みのスキーマがあります。

パネル型

ステータス

XYチャート

サポートあり

メトリクス

サポートあり

円グラフ

サポートあり

ゲージ

サポートあり

ヒートマップ

サポートあり

データ表

サポートあり

ツリーマップ

サポートあり

Discoverセッション

サポートあり

コントロール

サポートあり

マークダウン

サポートあり

リンク

サポートあり

MLパネル

サポートあり

オブザーバビリティパネル

サポートあり

マップ

まもなくリリース

Vega

まもなくリリース

Kibanaのダッシュボードをコードとして管理する方法

Dashboards APIを使用すると、完全なダッシュボード・アズ・コードのワークフローが実現できます。ダッシュボードをクリーンで差分比較可能なJSONとしてエクスポートし、それをGitにコミットして真の情報源とし、プルリクエストで変更内容を確認し、開発環境、ステージング環境、本番環境に同じ定義をデプロイできます。ダッシュボードをコードとして管理するようになったら、Gitを唯一の信頼できる情報源として扱います。UIで直接行った変更は、次回デプロイ時に上書きされます。

ダッシュボードをスペース、クラスター、またはステージ間で移動する際の主な課題は、ダッシュボードがデータビューやライブラリの視覚化などのオブジェクトをIDで参照することです。これらのIDは自動生成され、環境ごとに異なるため、ある環境からエクスポートされたダッシュボードが、別の環境には存在しないオブジェクトを指し示すことがあります。この問題を解決するには3つの方法があり、自動化の度合いが高い順に以下に示します。

• Terraformを使用する。Elastic Stack Terraformプロバイダーは各リソースを追跡し、環境ごとにIDを自動マッピングするため、開発から本番環境へダッシュボードを移行する際に参照が一貫して保たれます。

• 値渡しのElasticsearchクエリ言語（ES|QL）パネルを定義する。パネルを構築する最もポータブルな方法は、ES|QLを使用してダッシュボードで直接可視化を定義することです。ES|QLクエリは、クエリ内で指定したインデックスからデータを読み取るため、パネルにはData viewやライブラリオブジェクトへの外部参照は含まれません。その結果、完全に自己完結型のポータブルダッシュボードとなります。

• 一致するIDを割り当てる。Data viewやライブラリの視覚化など、保存済みのオブジェクトを参照する場合は、POST（IDを自動生成）ではなく、PUT（アップサート）を使用して、選択したIDでオブジェクトを作成してください。「logs-prod」のような人間が読みやすいIDを使うことで、環境を超えて再利用・認識しやすくなります。

これらの移植性パターンとダッシュボード・アズ・コードのワークフロー全体に関する詳細な説明については、「ダッシュボードをコードとして管理する」ドキュメントをご覧ください。

PUTメソッドを使用してDashboards APIでKibanaダッシュボードを作成

ここでは、ダッシュボード名（service-health-overview）を使用してカスタムIDを割り当てるために、POSTではなくPUTを使用してメトリックパネルを含むダッシュボードを作成する簡単な例を示します。ライブラリに保存されたスタンドアロンの可視化を作成する場合も、同じロジックが適用されます。

Kibana Dashboards APIロードマップ：マップ、Vega、スタンドアロンのエンドポイント

APIの展開範囲を積極的に拡大していきます。次に、マップとVegaパネルのサポートを進め、それらに型付きスキーマを追加します。また、ダッシュボードのライフサイクルから切り離したDiscoverセッション（既存のダッシュボードパネルのサポートを超えて）、Vega、マップ、Annotations向けのスタンドアロンCRUDエンドポイントも構築しています。

スキーマ定義の詳細は、Dashboards APIドキュメントをご覧ください。Terraformユーザー向けにはElastic Stack Terraformプロバイダーが一般提供のDashboards APIをサポートしています。

注

1. コアエンドポイントはテクニカルプレビュー版から変更されていません。9.4向けに構築した統合機能は、9.5でも動作します。唯一の破壊的変更は、ダッシュボード一覧と所要時間単位のフォーマットに影響を与える2つの小さな変更で、こちらに記載されています。

今日では、こうした局面でもずっとシンプルになります。Elastic Cloud APIキーが、Elastic Cloud Serverless上でElasticsearchとKibana APIに対する直接認証に使用できるようになりました。単一の認証情報を使用して、組織のリソースを管理したり、 Elasticsearchクエリ言語（ES|QL）クエリ、データ取り込み、アラートなどのデータ操作を実行したりできるようになりました。

当社がこれを構築した理由、グローバルに分散されたIDレイヤーをどのように設計して実現した方法、そしてこれがクロスプロジェクト検索の基盤をどのように築くのかを見ていきましょう。

シークレット管理の負担

信頼性の高いCI/CDパイプライン、GitOpsワークフロー、またはTerraformの自動化をデータプラットフォームに構築する際には、隠れたコストが伴います。それは、シークレットの無秩序な拡散です。

以前のモデルでは、開発者は断片的な認証プロセスに直面していました。

• コントロールプレーン（Elastic Cloud APIキー）： Elastic Cloud API経由でプロジェクトの作成、ユーザーの招待、課金管理などを行う際に使用する組織スコープのキー。

• データプレーン（Elasticsearch APIキー）：特定のサーバーレスプロジェクト内で作成され、ElasticsearchおよびKibana APIとやり取りするために使用されるプロジェクトスコープのキー。

つまり、導入スクリプトがElastic Cloudに対して認証を行い、Serverlessプロジェクトをプロビジョニングし、その特定のプロジェクトから新しく作成されたElasticsearch APIキーを抽出し、その後、その2番目のキーを下流のアプリケーションまたは自動化ツールに注入する必要があったことになります。結果として複雑なパイプライン、断片化された監査ログ、認証情報漏洩のリスクの増加につながっていました。

Elastic Cloud Serverlessでの統合認証

このリリースにより、サーバーレスプロジェクトの分割はなくなりました。クラウド、Elasticsearch、Kibana APIsに対して明示的に認可されたElastic Cloud APIキーを作成できるようになりました。

• 以前：Elastic Cloud APIキーは、厳密にはコントロールプレーントークンでした。プロジェクトの作成、請求管理、ユーザー招待は可能だったが、プロジェクト内でElasticsearchやKibanaのAPIを呼び出せないという明確な制限がありました。データ操作には、常にプロジェクト固有の2つ目のキーが必要でした。

• 現在：Elastic Cloud APIキーを作成する際にCloud、Elasticsearch、Kibana APIへのアクセスを選択することで、Serverlessの境界が解除され、そのAPIキーが真に統一された認証情報となります。組織のインフラを管理する能力を維持しながら、同時に任意の認可されたサーバーレスプロジェクトでデータをクエリ、取り込み、分析するためのネイティブアクセスを獲得できます。

これを単一のElastic Cloud APIキーに統合することで、スコープ、監査、ローテーション、取り消しを1つのユニットとして行うことができる単一のIDが得られます。新しいプロジェクトのプロビジョニングであれ、ES|QLクエリの実行であれ、すべてのAPI呼び出しは監査ログに同じ認証情報で記録されるため、インシデント調査やコンプライアンスレビューの際に追跡できる単一の履歴が提供されます。認証情報のローテーションは、分離されたコントロールプレーンとデータプレーンのシークレット間での調整された更新ではなく、ワンステップの操作になります。また、役割の割り当てはプロジェクトごとに行われるため、1つのキーで複数のプロジェクトを横断的に管理でき、監視プロジェクトでのデータ取り込みを管理したり、セキュリティプロジェクトでクエリを実行したりすることが可能になり、プロジェクトごとに個別の認証情報を管理する手間が省けます。

重要なのは、統一されているということは決して全能であることを意味しない点です。role_assignments ペイロードを使用することで、統一されたキーを厳密に単一のプロジェクトと特定のロール（例: 読み取り専用）にスコープすることができ、認証情報が漏洩した場合でも、影響範囲を完全に制限することができます。開発者が退職した場合やアプリケーションが廃止された場合も、Elastic Cloudコンソールから単一のキーを取り消すことで、コントロールプレーンと関連するすべてのElasticsearchプロジェクトへのアクセスを即座に停止できます。

（注：Elastic Cloud Hosted/マネージド導入では、Cloud APIキーは依然としてコントロールプレーンのみを管理します。ホスト型スタックAPIへの対応は今後のリリースで予定されています。）

ワークフローの自動化

始めるのは簡単です。Elastic Cloudコンソールから完全に設定するか、Elastic Cloud APIを使って自動化できます。

UIの操作手順は変わりませんが、プロジェクトロールの割り当て時にCloud、Elasticsearch、Kibana APIへのアクセスを選択できるようになりました。

Elastic Cloud APIを使用してプログラムで統合キーを作成する方法を以下に示します。application_roles配列に注目してください。これが、Elasticsearch データプレーンへのキーのネイティブアクセスを許可します。

一度作成すると、このまったく同じキーをAuthorization: ApiKeyヘッダーでapi.elastic-cloud.comと特定のサーバーレスElasticsearchエンドポイントの両方に渡すだけです。

内部構造：分散型IDレイヤーの構築

Cloud APIキーをコントロールプレーンとデータプレーンの両方で使えるようにするのは、トークンを渡すほど単純ではありません。分散システムの根本的な課題を解決する必要があります。

歴史的に、Cloud APIキーは中央集権的なグローバルセキュリティクラスターに存在していました。これは、より高いレイテンシが許容されるコントロールプレーン操作には問題なく機能しますが、Elasticsearchのデータリクエストには超低レイテンシが求められます。すべての検索クエリやデータ取り込みリクエストを検証するために、地球を横断して中央コントロールプレーンまで往復する余裕はありません。

この問題を解決するため、グローバルに分散されたデータストアを基盤とする新しい認証アーキテクチャを導入しました。次のシーケンス図は、Elastic Cloud APIキーを使用してクライアントがElasticsearchクエリを送信する流れを示しています。グローバルコントロールプレーンへの往復なしに、認証がローカルリージョン内で完結することを示しています。Elasticsearchは認証を地域IAMサービスに委任します。このサービスはキーを検証し、グローバルに分散されたデータベースのローカルレプリカに照らしてロール割り当てを解決します。認可されると、Elasticsearchはクエリを実行し、結果をクライアントに返します。

グローバルに分散された永続性

Elastic Cloud APIキーとそれに関連付けられたロール定義は、中央集権型のセキュリティクラスターにのみ依存するのではなく、グローバルに分散された高可用性データベースに永続的に保存されるようになりました。このデータベースは、サーバーレスプロジェクトが実際に実行されるグローバルコントロールプレーンとリージョナルデータプレーン間で、アイデンティティおよびアクセス管理（IAM）データを同期します。

地域IAMによるローカル検証

クライアントがElastic Cloud APIキーを使用してElasticsearchにリクエストを送信した場合、そのリクエストはグローバルコントロールプレーンには返されません。代わりに、新しい地域IAMサービスにルーティングされます。ローカルデータベースのレプリカに対してキーを検証することで、認証がほぼゼロ遅延で行われ、グローバルなコントロールプレーンの障害から完全に隔離されることを保証します。

動的ロールマッピング

認証は戦いの半分に過ぎず、システムはリクエストを承認する必要もあります。地域IAMサービスは、クラウドレベルのロール割り当て（例：application_roles）をネイティブのElasticsearch権限に即座に変換します。Elasticsearch は、ローカルで.securityインデックスを必要とすることなく、ローカルでリクエストを承認し、実行することができます。

プロジェクト横断検索の基礎

この分散型IDアーキテクチャは、Elastic Platformの将来を支える基本的な構成要素です。

IDとアクセス権限が統一され、グローバルに同期されたことで、異なるプロジェクト間で安全に身元情報をやり取りするために必要なフレームワークが整いました。これにより、Serverless向けのプロジェクト横断検索（CPS）機能が有効になります。

CPSを使用すると、セキュリティとオブザーバビリティのワークロードを組み合わせるなど、複数のリモートServerlessプロジェクトにまたがるデータを、あたかも1つのデータセットであるかのように簡単にクエリできるようになります。統一されたAPIキーを利用することで、システムはすべてのプロジェクトにわたるユーザーの権限を同時に自動的に評価できます。対象プロジェクトごとに複雑な信頼関係、証明書、重複した認証情報を設定する必要はありません。

詳しくはこちら

スタックを簡素化する準備はできていますか？

• スタックアクセスの割り当て方法についてはElastic Cloud APIキーのドキュメントをお読みください。

• キー生成を自動化するには、「APIキーを作成する（Elastic Cloud API）」のリファレンスを参照してください。

• Elasticプラットフォーム全体で使用されているキーの種類を包括的に比較するには、 Elastic APIキーに関するドキュメントを参照してください。

Elastic Cloudでの構築を今すぐ開始または継続しましょう。

免責事項

本記事に記述されているあらゆる機能ないし性能のリリースおよびタイミングは、Elasticの単独裁量に委ねられます。現時点で提供されていないあらゆる機能ないし性能は、すみやかに提供されない可能性、または一切の提供が行われない可能性があります。

Elastic WorkflowsはKibana内部に組み込まれた自動化エンジンで、シンプルなYAML構成を使用して多段階プロセスを定義できます。各ワークフローはスケジュールやイベント、またはElastic Agent Builderのツールとしてトリガーでき、各ステップでKibana APIを呼び出し、Elasticsearchをクエリし、データを変換できます。

具体的な例としてダッシュボードのビュー数を使用しますが、同じパターンがKibanaの保存済みオブジェクトAPIを通じて提供されるすべてのメトリックにも当てはまります。

要件

• Elastic Cloudまたはセルフマネージドクラスター（バージョン9.3を実行）

• ワークフローが有効（詳細設定）

ステップ1：開発ツールで生データを調べます

何かを作る前に、どんなデータがあるのかを理解しましょう。Kibanaはほとんどの設定やメタデータを専用の内部インデックスに保存済みオブジェクトとして保存しています。Kibanaがこの方法で追跡している項目の一つに、使用量カウンターと呼ばれる、特別な保存オブジェクトタイプを使ったダッシュボードの閲覧数があります。次のように、開発ツールから直接クエリできます。

応答は下記のようになります。

counterNameフィールドはダッシュボードIDであり、countはそのダッシュボードに対する当日中の累積閲覧数です。Kibanaは、1つのダッシュボードにつき1日に1つのカウンターオブジェクトを作成します。オブジェクトIDに日付サフィックス（...views:server:20260310）が表示されます。ユーザーがダッシュボードを開くにつれて、その数は一日を通して増加していきます。

この日常的なドキュメントモデルをインデックスで複製するのではなく、ワークフローの実行ごとに1つのドキュメントを作成します。各ドキュメントは、キャプチャの瞬間におけるその日のダッシュボードの累積ビュー数を記録します。

ステップ2：宛先インデックスの作成

ダッシュボードビューのスナップショットを格納するためのインデックスが必要です。次のコマンドは明示的なマッピングで作成し、後で集約や可視化ができるようにします。Dev Toolsで実行してください：

IDと名前にkeywordマッピングを使用すると、アグリゲーションが可能になります。view_countのためにintegerを使用することは安全なデフォルト設定です。Kibanaはカウンターを毎日リセットするため、32ビットの制限（1日で20億回以上のビュー）に達することは現実的な懸念事項ではありません。数値演算も引き続きサポートしており、max、avg、minなどが含まれます。

ステップ3: ワークフローを作成する

Stack Management > Workflows > New Workflowに移動し、次のワークフローのYAML構成を貼り付けます。

次のセクションでは、ワークフローをステップごとに分解していきます。

ワークフローの仕組み

トリガー

ワークフローは30分ごとにスケジュールされたトリガーで実行されます。これにより、APIに負担をかけずに時系列データが得られます。

ダッシュボードビューを取得

kibana.requestを使ってKibanaの保存済みオブジェクトAPIを呼び出します。認証の設定は不要です。ワークフローエンジンは実行コンテキストに基づいて適切なヘッダーを自動的に添付します。

index_each_dashboard (foreach)

前のステップで返された saved_objects 配列を反復します。各反復の現在の項目は foreach.itemとして利用可能です。ループ内では、各ダッシュボードごとに2つの入れ子手順を実行します。

1. fetch_dashboard_name：

人間が読み取れるダッシュボードのタイトルを GET /api/saved_objects/dashboard/{id} を呼び出して解決します。on-failure: continue: true を追加することで、ダッシュボードが削除されてもビューカウンターが残っている場合、ループが継続して全体の実行が失敗しないようにします。

2. index_doc：

各ドキュメントをPOST /dashboard-views/_doc（明示的なIDなし）でインデックス化することで、Elasticsearchが自動でIDを生成します。これにより、毎回の実行時に新しいドキュメントが作成され、以前のスナップショットを上書きするのではなく、時間の経過とともにビューカウントの履歴が構築されます。

次の2点にご注意ください。

• captured_atフィールドは日付フィルターを使ってタイムスタンプをISO 8601としてフォーマットします。それなしでは、値はJavaScriptの日付文字列として出力され（例：Tue Mar 10 2026 05:03:47 GMT+0000）、Elasticsearchは日付としてマップしません。

• view_countは数値型を保持するために${{ }}構文を| plus: 0と共に用います。{{ }}を使うと文字列としてレンダリングされ、ダッシュボードでの計算操作ができなくなります。

UIでは、各ワークフローステップを快適にデバッグできます。

ステップ4：統計ダッシュボードを構築

ワークフローが数回実行されてデータが収集されたら、dashboard-views Data viewを使用してKibanaで新しいダッシュボードを作成します。

まずは以下のパネルから始めましょう：

• トップのダッシュボード（閲覧数別）： X軸にdashboard_name、Y軸にlast_value(view_count)を持つ棒グラフを使用します。これはダッシュボードごとの現在の日次閲覧数を示しています。

• 時間経過に伴うビュー：X軸にcaptured_at、Y軸にlast_value(view_count)を用いた折れ線グラフを使用し、dashboard_nameで分類されます。各実行が新しいドキュメントを追加するため、重複を合計するのではなく、最後の値を使用して時間バケットごとのピークカウントを取得します。

• 現在のスナップショット：すべてのダッシュボードの最新のビュー数を表示するには、最新のcaptured_at を含むデータテーブルを使用します。

各ワークフローが新しいドキュメントを作成するため、時間範囲でフィルタリングして特定の期間のアクティビティを分析したり、週ごとの比較を行ったり、ダッシュボードのビューしきい値を下回ったときにアラートを設定したりすることができます。

まとめ

Elastic Workflowsは、ソース（Kibana API）と送信先（Elasticsearch）の両方がネイティブであるため、認証管理が全く必要なく、この種の定期的なデータ収集に適しています。ワークフローエンジンはkibana.requestとelasticsearch.requestのステップで認証を自動的に処理するため、記述するのはロジックだけです。

資料

• Elastic Workflows

• Kibana API

Elasticでの依存関係管理

Elasticでは、プライベートとパブリックの両方で、数百、数千ものリポジトリを管理する必要があります。重大なCVEが発見された場合、どのリポジトリが脆弱であるかを即座に回答して対処する必要があります。どれくらい早くパッチを当てられるでしょうか。セキュリティとは別に、生産性に関する質問も出てきます。手動のタスクにあまり時間をかけずに、新しいパッケージバージョンのリリースを、それに依存するすべてのリポジトリに迅速に広めるにはどうすればよいでしょうか。

依存関係管理の方法を探す最初のきっかけは、CVE削減のための自動更新を備えた安全な基盤を確立する必要性でした。依存関係管理に関するソリューションを慎重に検討した後、まずセルフホスト型のインフラストラクチャーの作業を開始しました。私たちは独自のKubernetesクラスターを使用して、Mend Renovate Community Self-Hostedを実行していました。ユーザーがセルフサービスでアクセスできる依存関係管理プラットフォームを提供するというアイデアがありました。

最初の実験が成功したため、より多くのチームが私たちのプラットフォームを導入し、日常のリポジトリのライフサイクルにおける更新やCVEパッチ適用に使用するようになりました。この展開は非常に速く、私たちはすぐにセルフマネージドインストールの限界に達しました。

課題：多数のリポジトリを持つ大規模な組織で依存関係管理プラットフォームを拡張するにはどうすればよいでしょうか。

当社の依存関係管理プラットフォームは、一度に1つのリポジトリを処理しており、シーケンシャルな処理モデルでは、当社の所有する多数のリポジトリに対応できませんでした。依存関係管理ツールの単一のインスタンスで拡大し続けるリポジトリのリストを処理するという概念に問題があることは、すでに認識していました。リポジトリはキュー内に留まり、場合によっては何時間も待機することがありました。リポジトリの50%以上は毎日処理されていませんでした。つまり、当社のリポジトリの50%以上がスキャン間でを24時間以上待っていたということです。

大規模なリポジトリでは、コードベースのサイズが大きく、PRが複数オープンしているため、ボトルネックが大きくなります。GitHub Webhookイベントによりこのシーケンスが中断されました。スキャンのタイミングが予測できないため、Automergeの信頼性が低下しました。スキャンの頻度についてはユーザーと約束していましたが、それを果たすことができませんでした。

社内で構築するという決定：Elastic独自のスケールとセキュリティのニーズに対応

商用オプション、具体的にはMendのRenovate Self-Hosted Enterprise Self-Hosted版も検討しましたが、Elastic社内ではいくつかの主要な取り組みが進行中でした。

社内プラットフォームを構築するという当社の決定は、Elastic の特定の譲れない要件を満たすには、徹底的にカスタマイズされたソリューションしかないという認識に基づいていました。

1. 内部開発者プラットフォームへの投資：当時、私たちはすでに内部開発者プラットフォームに多額の投資を行っていました。それぞれのサービスをこれに適合させる方法について議論し、設計していました。つまり、依存関係管理プラットフォームの独自のルールと実践をテストドライブするというニーズがあり、それに加えて、新しいガイドラインが導入されることになり、イベントに先立ってプラットフォームを設計したいと考えていました。

2. ネイティブ統合とワークフローのカスタマイズ：社内ツールや社内プロセスとの簡単な統合が必要で、例えば、Service Catalog（Backstage）を使用して構成をコードとして一元管理したいと考えていました。Backstageの使用に関しては、特定のニーズがあり、当社のプラットフォームと互換性を持たせたいと考えていました。したがって、Renovate Self-Hosted APIをBackstageの自動化と併用することは可能ですが、これでは当社の内部プロセスを完全にカバーすることはできません。

3. Elastic特有の徹底したセキュリティ対策：当社の厳格なセキュリティコンプライアンスには、当社のエコシステムに合わせた特注のセキュリティメカニズムが必要でした。「非人間的アイデンティティ」の使用の強化に取り組んでいました。このアクセス強化の仕組みにより、GitHub への認証を行う非標準の手段は、この内部実装をサポートしていない市販のツールでは機能しなくなります。当社のワークフローには、親子ワークフローの秘密の暗号化パターンを実装し、一時的な使い捨てのGitHubトークンを使用することが含まれていました。社内で構築することが、これらの独自のセキュリティレイヤーを組み込み、複雑なマルチクラウド環境全体の攻撃対象領域を最小限に抑える唯一の実用的な方法でした。

解決策：依存関係管理のためのワークフローオーケストレーション

解決策の構築は、既に使用している依存関係管理ツールを基に構築し、それを置き換えたり他のソリューションを探したりするのではなく、その上に構築することから始まりました。その可能性の兆しはあり、その柔軟性は組織全体のさまざまなニーズにとって重要です。さまざまなソリューションを検討しましたが、最終的に決め手となったのは、カバーしなければならない大きくて時に特殊なニーズでした。私たちは、各リポジトリが独自に処理され、ボトルネックを解消して成長に備えられる、信頼性が高くスケーラブルな依存関係管理プラットフォームを構築することを決定しました。

プラットフォームは次の3つのコア原則に従って設計しました。

1. 並列処理

各リポジトリに独自の依存関係管理処理環境が与えられます。キューはなくなります。同時実行性は、消費するリソースの数によってのみ制限されます。また、GitHubでレート制限を受けないようにスマートな分散スケジューリングを適用しました。

2．セルフサービス可能

Service Catalog（Backstage）を使用して、新しいリポジトリを自動的にオンボードして管理します。独自のリソース定義を使用して、エンドユーザーにリポジトリの処理頻度を選択するオプション、スケジュールに割り当てるリソースの量、何らかの理由で処理をオンまたはオフにするオプションを提供します。ユーザーのニーズが進化し、新しいインストールに慣れてきたら、そのようにしてさらに多くのオプションを追加していく予定です。

3. シークレットのスコープと名前空間の分離の縮小

セキュリティを強化するために、各ワークフローの開始時に生成される一時的なGitHubトークンを依存関係管理ポッドに提供します。さらに、ワークロードを特定の名前空間に分離して、必要なシークレットのみが提供されるようにします。Kubernetes RBACを使用して、各依存関係管理ワークフローでアクセスできるシークレットを制御します。また、暗号化を使用して、親ワークフローから子ワークフローにGitHubトークンを伝播します。

Kubernetesを使用してプラットフォームを再構築し、Kubernetesのパワーを活用しました。Argo Workflowsはプロセスのロジックを強化し、Renovate CLIはリポジトリを一度に1つずつスキャンして処理するように設定されています。

ここで素晴らしい点は、実績のあるオープンソースプロジェクトを独自の方法で使用し、すべてのプロジェクトに新しい実用的な例を提供すると同時に、開発速度を増幅し、チームのCVE削減を強化していることです。

依存関係管理アーキテクチャー：4つのマイクロサービス

このプラットフォームは、次の4つのカスタムビルドコンポーネントで構成されています。

ワークフローオペレーター（Go/Kubebuilder）

3つのカスタムリソース定義（CRD）を通じてワークフローライフサイクルを管理するKubernetesオペレーター：

• RepoConfig CRD：リポジトリ設定のための信頼できる唯一の情報源。

RepoConfigはオペレーターで次のように定義されています。

RepoConfigのインスタンスは次のようになります。

• 親CRD：スケジュールされたスキャンのCronWorkflowを管理します。

親コントローラの調整ループ内では、ワークフロー設定が作成され、最新の状態に保たれ、必要に応じて削除されることを確認します。

まず、ワークフローのグローバル設定を取得します。

mutexのconfigmapが最新であることを確認し、類似したワークフローが同時に動作しないようにします:

そして、Cronワークフローとワークフローテンプレートを作成または更新する構造体であるワークフローマネージャーを作成します。

• 子CRD：リポジトリごとのリソースを使用してWorkflowTemplatesを管理します。

子コントローラにーは親と同様の調整義務がありますが、今回は親ワークフローによってトリガーされる子名前空間内のワークフローテンプレートを担当します。

マルチコントローラーパターンでは明確な分離が実現されます。RepoConfigコントローラーはオンボーディング／オフボーディングを処理し、親コントローラーはスケジュールを管理し、子コントローラーは実行テンプレートを処理します。

GitHuイベントゲートウェイ（Go）

GitHubのwebhookを受信し、署名を検証し、組織／リポジトリでフィルタリングし、Argo Eventsにルーティングするセキュアなwebhookプロキシです。依存関係ダッシュボードのインタラクション、PRイベント、パッケージの更新に対応する10個の異なるセンサーを構築しました。

このゲートウェイは、以下の方法でGitHub Appsとの統合を可能にします。

• セキュリティのため、受信したGitHub webhook署名を検証しています。

• 有効なイベントを、すべての関連ヘッダーと認証とともにArgo Events EventSourceに転送します。

• また、EventSourceにAuthSecretを設定し、これを転送されるリクエストのBearerヘッダーとして提供します。

• ログ、メトリクス、再試行ロジックを提供します。

各GitHubイベントリクエストに対して様々な検証を行います。

以下のHTTP属性が存在することを確認します。

また、各リクエストの署名とその構成も検証します。

最後に、イベントの種類に基づいてArgo Eventsにルーティングします。

Argo Events側では、10個のセンサーがArgo Events EventBusで新しいイベントを監視します。

次に、スクリプトは各センサーのロジックを適用します。

Backstage Syncer（Go）

このプロセスでは、Service Catalog（Backstage）に対してRepository Real Resource Entitiesのポーリングを行い、それらをRepoConfig CRDに変換し、プラットフォームを設定変更と同期させます。変更は3分以内に適用されます。

最後に、そのデータをRepoConfigインスタンスに書き込みます。

ワークフローベース（混合：JavaScript、Go、Helm）

基盤レイヤーには、Helmチャート、JavaScript設定、暗号化サポート付きのRenovate CLI用のGoラッパー、Alpineパッケージ用のカスタムAPKインデクサーが含まれています。

セルフサービス構成

チームはBackstageを通じてリポジトリを宣言的に設定します。

リソースグループはリポジトリサイズに基づいてCPUとメモリを割り当てます。

• SMALL: 500m CPU、1Giメモリ。

• MEDIUM: 1000m CPU、2Giメモリ。

• LARGE: 2000m CPU、4Giメモリ。

構成はバージョン管理され、監査可能で、自動的に適用されます。

親子パターン

実行モデルは親子ワークフローパターンを使用しています。

• 親ワークフロー：スケジュールに従って実行される軽量のCronワークフロー。シークレットを暗号化し、スキャンを実行するかどうかを決定し、子プロセスに構成を渡します。

• 子ワークフロー：Renovate CLIが実行される一時的なポッド。リソースを動的に割り当て、シークレットを単独で復号し、完了後に終了します。

この分離により、セキュリティ（親レベルで暗号化されたシークレット）、リソースの最適化（親は最小限のリソースを使用）、拡張性（子が並行して実行）が提供されます。

結果

パフォーマンスの変化

• 変更前：一度に1つのリポジトリで、一部のリポジトリは、おそらく1日以上、1日あたり1,000回未満のスキャンでも処理されませんでした。

• 変更後：100以上の同時スキャン、通常は8,000件のスキャンと1日あたり最大10,000件の記録スキャン。制限は、当社が費やすリソースの量とGitHubのレート制限の扱い方のみです。

費用対効果

奇妙に聞こえるかもしれませんが、1 日に8,000件のポッドを実行すると、同じ結果を達成するために 1 つの長時間実行ポッドを実行するよりもはるかに安価に同じ結果を得ることができます。

以前の設定では、単一のインスタンスを実行していて、調子が良い日には500～600回のスキャンを実行していました。同時に、異なる種類のリポジトリが同じポッドで実行されることから、最大のものに合わせてポッドのサイズを設定する必要がありました。そのサイズは、現在の8つのCPUと16GBのメモリを搭載する特大モデルよりもはるかに大きくなります。

現在の日次出力を満たすには、単一のポッドなら12日間実行する必要があります。それでは、12日間稼働する単一のポッドのコストを、毎日稼働する8,000個の「MEDIUM」サイズのポッドのコストと比較すると、新しい設計は同じスキャン出力に対してはるかに効率的です。

メトリック

シナリオ A（ワークフロー）

シナリオB（長時間実行される単一のポッド）

セットアップ

8,000ポッド（1 vCPU／2GB）

1 pod (8 vCPU / 16 GB)*

期間

それぞれ10分

12日間連続

総作業時間

1,333計算時間

288計算時間

総コスト

65.83ドル

$113.75

しかし、ワークロードのデフォルト設定が「SMALL」に設定されていることを考慮に入れましょう。大多数は0.5 CPUと1G RAMで正常に実行されており、規模を増やす変更する必要があるのはごく一部です。ワークロードの60％が「SMALL」で実行され、30％が「MEDIUM」で実行され、10％が「LARGE」で実行されている場合（これが実際に近い値です）に何が起こるかを見てみましょう。

メトリック

シナリオA（混合群）

シナリオB（長時間実行）

戦略

8,000ポッド（混合サイズ）

1 pod (8 vCPU / 16 GB)*

期間

それぞれ10分

12日間連続

総コスト

$52.66

$113.75

節約額

$61.09（54%安価）

—

同じ出力に対して、現在の設定ではるかに費用対効果に優れていることがわかります。

強化されたセキュリティ

• 一時的なGitHubトークン（数分間の公開と数日間の公開の比較）。

• ロールベースアクセス制御（RBAC）境界による名前空間の分離。

• 親ワークフロー内の保存時のシークレットの暗号化。

• 直接のVaultアクセスを削除。

予測可能なパフォーマンス

スキャン頻度が保証されれば、最終的にサービスレベル目標（SLO）を設定できます。Automergeは確実に動作します。チームは、プラットフォームが約束どおりの成果をもたらすと信頼しています。

重要なアーキテクチャ上の決定

ここでは、プラットフォームの外観を形作る重要な設計上の決定事項をいくつか紹介します。

• 親子ワークフローが必要な理由

多層防御戦略を実施するためにこのパターンを採用しました。価値の高い認証情報（GitHubアプリのシークレットなど）を専用のロックダウンされた名前空間に制限することで、RBACを使用して、一時的な実行ポッドが機密データに恣意的にアクセスできないようにします。最近のサプライチェーンの脆弱性（例えば、"Shai Hulud"継続的インテグレーション/継続的デリバリー[CI/CD]攻撃）は、動的スクリプトを実行するランタイム環境を認証情報ストアから分離することの重要性を実証しています。

同時に、この分離により、きめ細かなリソースの最適化が可能になります。「親」ワークフローは軽量のオーケストレーターとして機能し、最小限のフットプリントで動作します。一方、「子」ワークフローは計算集約型の依存関係スキャンを処理します。この分離により、各レイヤーに個別の調整ロジックを適用し、スケジューリングとセキュリティインフラ（親）の管理制御を維持しながら、実行パラメータ（子）の制御をユーザーに許可することで、ライフサイクル管理を簡素化できます。

• セルフサービス可能な理由

リポジトリ構成のボトルネックとなる当社のチームを排除することは重要な要件でした。私たちの使命は、多様なユースケースをサポートできるスケーラブルなセルフサービスプラットフォームを設計することでした。リポジトリの膨大な量を考慮すると、すべての構成変更のゲートキーパーとして機能することは持続不可能であると認識しました。代わりに、私たちは「レール」（インフラストラクチャとガードレール）を提供しながら、ユーザーが「列車」（実行とカスタマイズ）を運転できるようにするという支援の哲学を採用しました。こうしたチームの自律性へのシフトが、ユーザーがシステムをそれぞれの具体的な業務ニーズに合わせてカスタマイズできるようにすることで、生産性を大幅に向上させると信じています。

• Kubernetes Operatorパターンを選択した理由

上記で述べたように、基本的な設計原則は、プラットフォームが完全にセルフサービス可能であることを確保することでした。ユーザーの意図（スキャンの切り替え、スケジューリング頻度の調整、ランタイムリソース制限の調整など）を捉え、それらの変更を基盤となるワークフローに瞬時に反映する自動化されたメカニズムが必要でした。将来の要件を予測し、システムは簡単に拡張可能である必要もありました。

これを実現するために、カスタムの依存関係管理Kubernetes Operatorを開発しました。設定のインターフェースとしてCRDを使用することで、Kubernetesネイティブな調整ループを確立しました。このオペレーターは、ユーザーが定義した望ましい状態を継続的に監視し、ワークフローインフラに必要な更新を自動的に管理します。これにより、イベント駆動型のシームレスな操作が保証され、プラットフォームのロジックが裏側ですべての複雑さを処理します。

• GitHubイベントゲートウェイを設計する理由

プラットフォームの応答性を高めるために、イベントドリブンアーキテクチャー（EDA）の採用が不可欠でした。CronWorkflowsは信頼性の高いベースラインスケジュールを提供しましたが、ユーザーがダッシュボードから手動でスキャンをトリガーするなどアドホック実行を処理できる俊敏性が必要でした。これを達成するために、ペイロードの整合性を検証し、リクエストをインテリジェントにルーティングするための専用のインジェストゲートウェイが必要でした。

既存のソリューション、特にArgoのネイティブGitHub EventSourceを評価しましたが、 運用上のオーバーヘッドや厳格な GitHub APIクォータ（例：リポジトリごとのwebhook制限）に関する重大なリスクを特定しました。結果として、これらの制限からインフラを切り離すためにカスタムゲートウェイを構築しました。

重要なのは、このゲートウェイが移行中に戦略的なトラフィック制御ポイントとして機能したことです。これはスイッチとして機能し、レガシーシステムから新しいインフラストラクチャへの段階的かつ詳細なロールアウト（トラフィックの移行）を実行できるようになりました。これにより、数千のリポジトリのオンボーディングが「ビッグバン」的な切り替えではなく、制御されたリスクのないプロセスになることが保証されました。

教訓

私たちが学んだいくつかの教訓は Elasticソースコードと密接に関連しています。

1. 顧客第一：プラットフォームはユーザーのために構築されます。したがって、ユーザーのニーズを最優先にすることが重要です。これにより、プラットフォームは、ユーザーとの摩擦を減らし、プラットフォームの拡張を簡素化し、導入を容易にする、効率的に設計されたインフラストラクチャとアプリケーションに形作られます。

2. 空間と時間：時には、最も抵抗の少ない道が不安定な状況につながることがあります。当初、既存の順次処理モデルを最適化しようとしましたが、問題は解決されず、むしろ複雑さが増し、未解決の問題が増えただけでした。プラットフォームを並列処理で再構築するという大胆な決定には、多大な事前開発が必要でしたが、最終的には持続可能なプラットフォームの成長への道を切り開き、日々の面倒な管理業務を事実上排除しました。

3. ITと依存関係：プラットフォームは単独では動作できません。その成功は、より広範なエコシステムとどれだけうまく統合できるかによって決まります。当社の場合、シームレスなサービスオンボーディングのための信頼できる情報源となるため、Backstageとの統合は極めて重要でした。同様に、Artifactoryに接続することで、プライベートパッケージの更新を効率的に管理できるようになります。他にも重要な統合は多々あります。

4. 進歩、シンプルな完璧さ：実装全体を通じて、当初の想定を継続的にプレッシャーテストし、新たな障壁が出現するたびにそれに適応しました。完璧主義に陥るのではなく、反復的なアプローチを採用し、課題に一つずつ取り組み、実際の状況に合わせて移行戦略を調整しました。

次のステップ

このプラットフォームの提供により、プラットフォームのUXと効率性の向上に役立つ、より有意義な作業が可能になります。いくつかの例を以下に示します。

• 自動マージの採用を増やし、ガードレールを設定

自動マージ機能により、面倒な手動タスクが排除され、チームの速度が大幅に向上します。しかし、この速度の向上が安全性を犠牲にすることのないよう、厳格なガードレールを確実に設置する必要があります。

• エンドユーザーエクスペリエンスに関するオブザーバビリティの向上

私たちのロードマップにおける重要な優先事項は、プラットフォームレベルだけでなく、特にエンドユーザーの視点からオブザーバビリティを高めることです。インフラの指標を捉えるのは簡単ですが、実際のユーザー体験を理解するにはより深い洞察が必要です。コアユーザー中心の重要業績評価指標（KPI）を定義し、テレメトリがエスカレートする前の摩擦点やパフォーマンスの問題を検出できるように取り組んでいます。

• より広範な採用を促進するための障壁の除去

将来を見据えた当社の優先事項は、プラットフォームの採用を妨げている障壁を特定して取り除くことです。新しい統合の開発や特定の機能セットの展開が必要な場合でも、当社はデータ主導の計画に取り組んでいます。当社は拡張性を重視したプラットフォームの構築に成功しました。今後は、その潜在能力を最大限に引き出すことに注力していきます。

全体像

依存関係管理ワークフロープロジェクトは、より広範な原則を示しています。つまり、デフォルトの導入モデルを超えてオープンソースツールをスケールする必要がある場合、Kubernetesネイティブパターンが前進する道を提供するということです。

以下を取り入れることで、

• 構成用のCRD

• ライフサイクル管理のためのオペレーター

• 応答性を高めるイベント駆動型アーキテクチャ

• 導入用のGitOps

管理するリポジトリの数に関係なく拡張できるオーケストレーションを構築しました。1つのリポジトリをスキャンするパフォーマンスは、管理するリポジトリが100個でも1,000個でも同じです。

重要なCVEが発表されても、数時間ではなく数分で回答が得られます。それがボトルネックと競争優位の違いです。

謝辞

このプラットフォームは優れたオープンソースツールを基盤としています。

• Kubebuilder：ワークフローをブートストラップして管理するKubernetes Operatorを起動するために使用したオープンソースフレームワーク。[1][2]

• Backstage：Service Catalogを構築し、信頼できる情報源として使用するオープンソースフレームワーク。[1][2]

• Argo WorkflowsとArgo Events：複雑なプロセスを調整し、イベントに基づいて動的な処理を追加するために使用したオープンソーススイート。[1][2][3][4]

• Renovate CLI：リポジトリを処理するオープンソースの依存関係管理ツール。[1][2]

* AWS Fargateの料金モデルを単一ポッドのコストの基準として使用しました。ただし、当社のワークロードは必ずしもAWSで実行されているわけではなく、本格的なKubernetesクラスターで実行されています。

さらに、これらのユースケースは通常、時間に敏感であり、一般的な開発段階 (コード ブランチを作成してから新しいリリースを待つ) を実行するのは時間のかかるプロセスです。

では、このプロセス全体を API 呼び出しだけで、あるいは Kibana で数回クリックするだけで実行できたらどうなるでしょうか?

クエリルールUI

Elasticsearch 8.10 では、クエリ ルールとルール リトリーバーが導入されました。これらは、ルールに基づいてオーガニック検索結果のランキングに影響を与えずに、ピン留めされた結果をクエリに挿入するように設計されたツールです。宣言的かつシンプルな方法で、結果の上にビジネス ロジックを追加するだけです。

クエリ ルールの一般的な使用例は次のとおりです。

• プロモーション対象商品やセール品の強調表示: セール中の商品やスポンサー商品を上部に表示します。

• コンテキストまたは地理位置情報による除外: 地域の規制により表示が許可されていない場合は、特定のアイテムを非表示にします。

• 主要な結果を優先する: オーガニックランキングに関係なく、人気のある検索や固定検索が常に上位に表示されるようにします。

インターフェースにアクセスしてこれらのツールを操作するには、Kibana サイドメニューをクリックし、関連性の下にあるクエリルールに移動する必要があります。

クエリ ルール メニューが表示されたら、最初のルール セットの作成をクリックします。

次に、ルールセットに名前を付ける必要があります。

各ルールを定義するフォームには、次の 3 つの主要コンポーネントがあります。

• 基準: ルールを適用するために満たす必要がある条件。たとえば、「query_string フィールドに値Christmasが含まれている場合」や「country フィールドにCO の場合」などです。

• アクション: これは、条件が満たされたときに発生する動作です。ピン留め（ドキュメントを上位の結果に固定する）したり、除外（ドキュメントを非表示にする）したりできます。

• メタデータ: これらはクエリの実行時にクエリに付随するフィールドです。これらには、ユーザーの情報 (場所や言語など) や検索データ (query_string) を含めることができます。これらは、ルールを適用するかどうかを決定するための基準で使用される値です。

例: 人気商品

さまざまな商品を扱う電子商取引サイトがあると想像してみましょう。指標をチェックすると、コンソール カテゴリで最も売れているアイテムの 1 つが「DualShock 4 ワイヤレス コントローラー」であることがわかります。特に、ユーザーが「PS4」または「PlayStation 4」というキーワードを検索した場合に多く見られます。そこで、ユーザーがこれらのキーワードを検索するたびに、この製品を結果の最上位に表示することにしました。

まず、Bulk API リクエストを使用して各アイテムのドキュメントをインデックス化します。

クエリに介入しない場合、アイテムは通常 4 番目の場所に表示されます。クエリは次のとおりです。

そして結果はこちらです

これを変更するためのクエリ ルールを作成しましょう。まず、次のようにルールセットに追加しましょう。

または同等のAPI リクエスト:

クエリでルールセットを使用するには、クエリ ルール タイプを使用する必要があります。この種のクエリは、主に次の 2 つの部分で構成されます。

• match_criteria : ユーザーのクエリと比較するために使用されるメタデータです。この例では、query_string フィールドの値が「PlayStation 4」の場合にルールセットがアクティブになります。

• query : 検索してオーガニック検索結果を取得するために使用される実際のクエリ。

この方法では、最初にオーガニッククエリを実行し、次に Elasticsearch がルールセットのルールを適用します。

例: ユーザーベースのメタデータ

クエリ ルールのもう 1 つの興味深い応用は、メタデータを使用して、ユーザーまたは Web ページからのコンテキスト情報に基づいて特定のドキュメントを表示することです。

たとえば、数値として表されるユーザーのロイヤルティ レベルに基づいて、アイテムやカスタマイズされたセールを強調表示したいとします。

これを実現するには、このメタデータをクエリに直接取り込んで、その値が特定の基準を満たしたときにルールがアクティブになるようにします。

まず、ロイヤルティ レベルの高いユーザーだけが閲覧できるドキュメントをインデックスします。

ここで、同じルールセット内に新しいルールを作成し、loyalty_level が 80 以上の場合にアイテムが結果の上部に表示されるようにします。

ルールとルールセットを保存します。

同等の REST リクエストは次のとおりです。

ここで、クエリを実行するときに、メタデータに新しいパラメータroyality_levelを含める必要があります。ルールの条件が満たされると、新しいドキュメントが結果の上部に表示されます。

たとえば、loyalty_level が 80 のクエリを送信する場合:

結果の上部にロイヤルティ ドキュメントが表示されます。

以下の場合、ロイヤルティ レベルが 70 であるため、ルールは満たされず、アイテムは上部に表示されません。

結果は次のとおりです。

例: 即時除外

DualShock 4 ワイヤレス コントローラー (ID 2)が一時的に入手できず、販売できないとします。そのため、ビジネス チームは、ドキュメントを手動で削除したり、何らかのデータ処理が開始されるのを待ったりする代わりに、当面は検索結果からドキュメントを削除することにしました。

先ほど人気アイテムに適用したのと同様のプロセスを使用しますが、今回は[Pinned]ではなく[Exclude]を選択します。このルールは一種のブラックリストとして機能します。クエリが実行されるたびに除外が機能するように、条件を「常時」に変更します。

ルールは次のようになります。

変更を適用するには、ルールとルールセットを保存します。同等の REST リクエストは次のとおりです。

ここで、クエリを再度実行すると、以前のルールではアイテムをピン留めするはずだったにもかかわらず、アイテムが結果に表示されなくなっていることがわかります。これは、除外がピン留め結果よりも優先されるためです。

まとめ

クエリ ルールを使用すると、コードを変更することなく関連性を簡単に調整できます。新しいKibana UIでは、これらの変更を数秒で行うことができるため、お客様とビジネス チームは検索結果をより細かく制御できるようになります。

クエリ ルールは、電子商取引以外にも、サポート ポータルでトラブルシューティング ガイドを強調表示したり、ナレッジ ベースで重要な社内ドキュメントを表示したり、ニュース サイトで最新ニュースを宣伝したり、期限切れの求人やコンテンツの一覧を除外したりするなど、さまざまなシナリオで活用できます。ユーザーの役割や地域によって制限されたコンテンツを非表示にするなど、コンプライアンス ルールを適用することもできます。

このブログでは、 Mastraを使用して、Elasticsearch をメモリおよび検索バックエンドとして使用し、ユーザーの発言を記憶し、後で関連情報を思い出すことができるナレッジ エージェントを構築します。これと同じ概念を実際のユースケースに簡単に拡張できます。サポート エージェントが過去の会話や解決策を記憶し、特定のユーザーへの応答をカスタマイズしたり、以前のコンテキストに基づいてより迅速に解決策を提示したりできると考えてください。

ここから手順に従って、ステップごとに構築する方法を確認してください。迷ってしまったり、完成した例を実行したいだけの場合は、ここにあるリポジトリを確認してください。

マストラとは何ですか？

Mastra は、推論、メモリ、ツールの交換可能なパーツを備えた AI エージェントを構築するためのオープンソースの TypeScript フレームワークです。セマンティック リコール機能により、エージェントはメッセージをベクター データベースに埋め込みとして保存することで、過去のやり取りを記憶して取り出すことができます。これにより、エージェントは長期的な会話のコンテキストと継続性を維持できます。Elasticsearch は効率的な高密度ベクトル検索をサポートしているため、この機能を有効にするのに最適なベクトル ストアです。セマンティックリコールがトリガーされると、エージェントは関連する過去のメッセージをモデルのコンテキストウィンドウに引き出し、モデルが取得したコンテキストを推論と応答の基礎として使用できるようにします。

始めるために必要なもの

• ノード v18+

• Elasticsearch（バージョン8.15以降）

• Elasticsearch APIキー

• OpenAI APIキー

注: デモでは OpenAI プロバイダーを使用するため、これが必要になりますが、Mastra は他の AI SDK とコミュニティ モデル プロバイダーをサポートしているため、設定に応じて簡単に交換できます。

Mastraプロジェクトの構築

プロジェクトの足場を提供するために、Mastra の組み込み CLI を使用します。次のコマンドを実行します。

次のような一連のプロンプトが表示されます。

1. プロジェクトに名前を付けます。

2. このデフォルト設定を維持することもできますし、空白のままにしておくこともできます。

3. このプロジェクトでは、OpenAI が提供するモデルを使用します。

4. すべての環境変数を、後のステップで設定する `.env` ファイルに保存するため、「今はスキップ」オプションを選択します。

5. このオプションをスキップすることもできます。

初期化が完了したら、次のステップに進むことができます。

依存関係のインストール

次に、いくつかの依存関係をインストールする必要があります。

• ai - JavaScript/TypeScript で AI モデル、プロンプト、ワークフローを管理するためのツールを提供するコア AI SDK パッケージ。Mastra は Vercel のAI SDK上に構築されているため、エージェントとのモデルのインタラクションを有効にするにはこの依存関係が必要です。

• @ai-sdk/openai - AI SDK を OpenAI モデル (GPT-4、GPT-4o など) に接続し、OpenAI API キーを使用した API 呼び出しを可能にするプラグイン。

• @elastic/elasticsearch - Node.js 用の公式 Elasticsearch クライアント、インデックス作成、検索、ベクター操作のために Elastic Cloud またはローカル クラスターに接続するために使用されます。

• dotenv - .envから環境変数を読み込みますファイルをprocess.envにコピーし、API キーや Elasticsearch エンドポイントなどの資格情報を安全に挿入できるようになります。

環境変数の設定

プロジェクトのルート ディレクトリに.envファイルが存在しない場合は作成します。あるいは、リポジトリに提供されている例.envをコピーして名前を変更することもできます。このファイルでは、次の変数を追加できます。

これで基本的な設定は完了です。ここから、エージェントの構築とオーケストレーションを開始できます。さらに一歩進んで、Elasticsearch をストアおよびベクター検索レイヤーとして追加します。

ベクターストアとしてElasticsearchを追加する

storesという新しいフォルダーを作成し、その中にこのファイルを追加します。Mastra と Elastic が公式の Elasticsearch ベクター ストア統合を出荷する前に、 Abhi Aiyer (Mastra CTO) がElasticVectorと呼ばれるこの初期のプロトタイプ クラスを共有しました。簡単に言えば、Mastra のメモリ抽象化を Elasticsearch の高密度ベクトル機能に接続することで、開発者はエージェントのベクトル データベースとして Elasticsearch を導入できるようになります。

統合の重要な部分を詳しく見てみましょう。

Elasticsearchクライアントの取り込み

このセクションでは、 ElasticVectorクラスを定義し、標準デプロイメントとサーバーレスデプロイメントの両方をサポートする Elasticsearch クライアント接続を設定します。

• ElasticVectorConfig extends ClientOptions: これにより、すべての Elasticsearch クライアント オプション ( node 、 auth 、 requestTimeoutなど) を継承し、カスタム プロパティを追加する新しい構成インターフェースが作成されます。つまり、ユーザーは、サーバーレス固有のオプションとともに、有効な Elasticsearch 構成を渡すことができるということです。

• extends MastraVector: これにより、 ElasticVector 、すべてのベクター ストア統合が準拠する共通インターフェースである Mastra の基本MastraVectorクラスから継承できるようになります。これにより、エージェントの観点から見ると、Elasticsearch は他の Mastra ベクター バックエンドと同じように動作するようになります。

• private client: Client: これは、Elasticsearch JavaScript クライアントのインスタンスを保持するプライベート プロパティです。これにより、クラスはクラスターと直接通信できるようになります。

• isServerless およびdeploymentChecked : これらのプロパティは連携して、サーバーレスまたは標準の Elasticsearch デプロイメントに接続されているかどうかを検出し、キャッシュします。この検出は最初の使用時に自動的に行われますが、明示的に構成することもできます。

• constructor(config: ClientOptions): このコンストラクターは、構成オブジェクト (Elasticsearch の資格情報とオプションのサーバーレス設定を含む) を受け取り、それを使用してthis.client = new Client(config)行でクライアントを初期化します。

• super(): これは Mastra の基本コンストラクターを呼び出すため、ログ記録、検証ヘルパー、およびその他の内部フックを継承します。

この時点で、Mastraは新しいベクターストアがあることを知っています。 ElasticVector

展開タイプの検出

インデックスを作成する前に、アダプターは標準の Elasticsearch を使用しているか Elasticsearch Serverless を使用しているかを自動的に検出します。サーバーレス デプロイメントでは手動でのシャード構成が許可されないため、これは重要です。

何が起こっていますか：

• まず、構成で明示的にisServerlessが設定されているかどうかを確認します (自動検出をスキップします)

• Elasticsearch のinfo() API を呼び出してクラスター情報を取得します

• build_flavor fieldをチェックします (サーバーレス デプロイメントはserverlessを返します)

• ビルドフレーバーが利用できない場合はタグラインをチェックする

• 結果をキャッシュして、API 呼び出しの繰り返しを回避します。

• 検出に失敗した場合は標準展開をデフォルトとする

使用例:

Elasticsearchに「メモリ」ストアを作成する

以下の関数は、埋め込みを保存するための Elasticsearch インデックスを設定します。インデックスがすでに存在するかどうかを確認します。そうでない場合は、埋め込みとカスタム類似度メトリックを格納するためのdense_vectorフィールドを含む以下のマッピングを使用して作成します。

注意すべき点:

• dimensionパラメータは各埋め込みベクトルの長さであり、使用している埋め込みモデルによって異なります。私たちの場合、サイズ1536のベクトルを出力する OpenAI のtext-embedding-3-smallモデルを使用して埋め込みを生成します。これをデフォルト値として使用します。

• 以下のマッピングで使用されるsimilarity変数は、ヘルパー関数 c onst similarity = this.mapMetricToSimilarity(metric)から定義されます。この関数は、 metricパラメータの値を受け取り、選択された距離メトリックの Elasticsearch 互換キーワードに変換します。

  • たとえば、Mastra では、ベクトルの類似性を表すためにcosine 、 euclidean 、 dotproductなどの一般的な用語を使用します。メトリックeuclidean Elasticsearch マッピングに直接渡すと、Elasticsearch はキーワードl2_normがユークリッド距離を表すと想定するため、エラーが発生します。

• サーバーレス互換性: サーバーレスデプロイメントのシャードとレプリカの設定は Elasticsearch Serverless によって自動的に管理されるため、コードでは自動的に省略されます。

やりとりの後に新しい記憶やメモを保存する

この関数は、各インタラクションの後に生成された新しい埋め込みをメタデータとともに取得し、Elastic のbulk API を使用してそれらをインデックスに挿入または更新します。bulk API は複数の書き込み操作を 1 つのリクエストにグループ化します。このインデックス作成パフォーマンスの向上により、エージェントのメモリが増加し続けても更新の効率が維持されます。

意味的想起のための類似ベクトルのクエリ

この機能は、セマンティック リコール機能の中核です。エージェントはベクトル検索を使用して、インデックス内に保存されている類似の埋め込みを見つけます。

内部構造:

• Elasticsearch のknn API を使用してkNN (k 近傍法) クエリを実行します。

• 入力クエリ ベクトルに類似する上位 K 個のベクトルを取得します。

• オプションでメタデータ フィルターを適用して結果を絞り込む (例: 特定のカテゴリまたは時間範囲内のみを検索する)

• ドキュメント ID、類似度スコア、保存されたメタデータを含む構造化された結果を返します。

知識エージェントの作成

ElasticVector統合を通じて Mastra と Elasticsearch の接続を確認したので、次は Knowledge Agent 自体を作成しましょう。

フォルダーagents内に、 knowledge-agent.tsというファイルを作成します。まず、環境変数を接続し、Elasticsearch クライアントを初期化します。

ここでは、次の操作を行います。

• dotenvを使用して、 .envファイルから変数を読み込みます。

• Elasticsearch の資格情報が正しく挿入されているかどうかを確認し、クライアントへの接続を正常に確立できるかどうかを確認します。

• Elasticsearch エンドポイントと API キーをElasticVectorコンストラクターに渡して、先ほど定義したベクター ストアのインスタンスを作成します。

• Elasticsearch Serverless を使用している場合は、オプションでisServerless: trueを指定します。これにより、自動検出手順がスキップされ、起動時間が短縮されます。省略した場合、アダプタは最初の使用時にデプロイメント タイプを自動的に検出します。

次に、Mastra のAgentクラスを使用してエージェントを定義します。

定義できるフィールドは次のとおりです。

• name そしてinstructions : アイデンティティと主な機能を与えます。

• model: @ai-sdk/openaiパッケージを通じて OpenAI のgpt-4oを使用しています。

• memory:

  • vector: Elasticsearch ストアを指すので、埋め込みはそこから保存され、取得されます。

  • embedder: 埋め込みを生成するためにどのモデルを使用するか

  • semanticRecall オプションによってリコールの動作が決まります。

    • topK: 意味的に類似したメッセージを取得する数。

    • messageRange: 各マッチにどの程度の会話を含めるか。

    • scope: メモリの境界を定義します。

もうすぐ終わりです。新しく作成したエージェントを Mastra 構成に追加するだけです。index.tsというファイルで、ナレッジ エージェントをインポートし、 agentsフィールドに挿入します。

その他のフィールドには以下が含まれます。

• storage: これは、実行履歴、観測性メトリック、スコア、キャッシュのための Mastra の内部データ ストアです。Mastra ストレージの詳細については、こちらをご覧ください。

• logger: Mastra は、軽量の構造化 JSON ロガーであるPinoを使用します。エージェントの開始と停止、ツールの呼び出しと結果、エラー、LLM 応答時間などのイベントをキャプチャします。

• observability: エージェントの AI トレースおよび実行の可視性を制御します。追跡対象:

  • 各推論ステップの開始/終了。

  • 使用されたモデルまたはツール。

  • 入力と出力。

  • スコアと評価

Mastra Studioでエージェントをテストする

おめでとうございます！ここまで到達したら、このエージェントを実行し、そのセマンティックリコール能力をテストする準備が整いました。幸いなことに、Mastra には組み込みのチャット UI が用意されているため、独自に構築する必要はありません。

Mastra 開発サーバーを起動するには、ターミナルを開いて次のコマンドを実行します。

サーバーの初期バンドルと起動が完了すると、Playground のアドレスが提供されるはずです。

このアドレスをブラウザに貼り付けると、Mastra Studio が表示されます。

knowledgeAgentのオプションを選択してチャットを開始してください。

すべてが正しく接続されているかどうかを確認するための簡単なテストでは、次のような情報を入力します。「チームは、主にエンタープライズ契約の更新により、10 月の売上実績が 12% 増加したと発表しました。次のステップは、中規模市場の顧客へのリーチを拡大することです。」次に、新しいチャットを開始して、「次に重点を置く必要があると言った顧客セグメントはどれですか?」などの質問をします。ナレッジエージェントは、最初のチャットで提供した情報を思い出せるはずです。次のような応答が表示されます。

このような応答が表示された場合、エージェントが以前のメッセージを Elasticsearch に埋め込みとして正常に保存し、後でベクトル検索を使用して取得したことを意味します。

エージェントの長期記憶ストアの検査

Mastra Studio のエージェント構成のmemoryタブに移動します。これにより、エージェントが時間の経過とともに何を学習したかを確認できます。Elasticsearch に埋め込まれて保存されるすべてのメッセージ、応答、およびやり取りは、この長期メモリの一部になります。過去のやり取りを意味的に検索して、エージェントが以前に学習した思い出の情報やコンテキストをすぐに見つけることができます。これは本質的には、エージェントがセマンティックリコール中に使用するメカニズムと同じものですが、ここではそれを直接検査できます。以下の例では、「sales」という用語を検索し、sales に関連する内容を含むすべてのインタラクションを取得しています。

まとめ

Mastra と Elasticsearch を接続することで、コンテキスト エンジニアリングの重要なレイヤーであるメモリをエージェントに付与できます。セマンティックリコールを使用すると、エージェントは時間の経過とともにコンテキストを構築し、学習した内容に基づいて応答することができます。つまり、より正確で信頼性が高く、自然なやりとりが可能になります。

この早期の統合は単なる出発点にすぎません。ここで同じパターンを使用すると、過去のチケットを記憶しているサポートエージェント、関連ドキュメントを取得する内部ボット、会話の途中で顧客の詳細を思い出すことができる AI アシスタントなどが可能になります。当社は公式の Mastra 統合にも取り組んでおり、近い将来この組み合わせがさらにシームレスになる予定です。

次に何を構築するのか楽しみにしています。ぜひ試してみて、 Mastraとそのメモリ機能を調べ、発見したことをコミュニティと自由に共有してください。