コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

アノテーション駆動のモニタリング — 1 つのアノテーションで多数のコンポーネントに

この例では、コンポーネントごとの features: ブロックを 1 つも書かずに、モニタリング用の Feature をネストしたトポロジー全体の 6 つのサービスにアタッチします。最上位のバウンダリーに付けた 1 つのオペレーターアノテーションを 2 つのサブツリーのオーバーライドで調整すると、それが Manifest の features.annotations バインディングを介して、含まれるすべてのコンポーネントへの core/prometheus-exporter のアタッチメントに展開され、各コンポーネントがそれぞれ Prometheus の ServiceMonitor をレンダリングします。

これがアノテーション駆動の Feature 展開の仕組みです。コンポーネントごとに繰り返される Feature のアタッチメントを、バウンダリーツリーを下方向にカスケードする 1 つのアノテーションに集約するためのパターンです。

構成

  • **開発者の意図(aggregate.yaml)**では、6 つの example/compute/service コンポーネント(gateway と、api/worker/ledger/etl/reconcile)だけを宣言します。モニタリング用の features: ブロックを持つコンポーネントは 1 つもありません。
  • **Manifest(manifest.yaml)**は、アノテーションを Feature にバインドします。
    features:
    type:
    core/prometheus-exporter: helm/prometheus-exporter:1.0.0 # the FeatureRecipe version binding
    annotations:
    feature.aggrega.ai/monitoring:
    feature: core/prometheus-exporter
    maps:
    infra: [interval, port, path] # structured-value subkeys → the feature's infra
  • **Release(release.yaml)**は、platform バウンダリーにアノテーションを 1 度だけ設定し、サブツリーごとに調整します。
    platform:
    annotations:
    feature.aggrega.ai/monitoring: {interval: 30s, port: metrics, path: /metrics} # gateway inherits this
    boundaries:
    payments:
    annotations:
    feature.aggrega.ai/monitoring: {interval: 15s} # api/worker/ledger
    batch:
    annotations:
    feature.aggrega.ai/monitoring: {interval: 120s} # etl/reconcile

core/prometheus-exporter と、そのコンポーネントスコープの ServiceMonitor FeatureRecipe は標準カタログから利用します(この例ではローカルのコピーを宣言しません)。レシピのチャートは、アタッチされたコンポーネントごとに monitoring.coreos.com/v1 ServiceMonitor を 1 つ出力し、解決済みのアノテーションから interval/port/path をテンプレート化します。この 3 つはいずれも、フィーチャーの infra にあるオペレーター用のスクレイプ設定です。(これは FeatureRecipe によるリソース生成(helm プロバイダーがレンダリングする source: + valuesMapping:)であり、Wasm のミューテーターやパイプラインステップではありません。)

サンプルを生成する

このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。

例の名前を付けた新しいフォルダーに例を書き出します。

Terminal window
aggrega scaffold --example annotation-driven-monitoring

その後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。

Terminal window
cd annotation-driven-monitoring

ビルド

pull がロックファイルを解決し、ビルドがそれを読み込みます。

Terminal window
aggrega pull --release release.yaml
aggrega build --release release.yaml

AI アシスタントを使う

Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。

Aggrega のツールだけを使い、フォルダーを自分で作成しないでください。ワークスペースフォルダーにまだ `annotation-driven-monitoring` フォルダーがない場合は、`example` を `annotation-driven-monitoring` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、サンプルが新しい `annotation-driven-monitoring` フォルダーに書き出されます。次に、`workspace_root` を `annotation-driven-monitoring`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出してください。ビルドが書き出したファイルを教えてください。ファイルは `annotation-driven-monitoring/dist/` の下にあります。

レンダリング結果が示すこと

ロックファイルを解決してビルドし、dist/<boundary>/helm/<component>--feature-zdaggrega-zdai-zsmonitoring--<component>-servicemonitor-<component>-scrape.yaml を確認します。

Terminal window
aggrega pull --release release.yaml
aggrega build --release release.yaml

**このファイル名は誰も入力していないので、読み解いてみる価値があります。**このターゲットはディレクトリ直下のファイルしか読まないため、アタッチメントのファイルはコンポーネント自身のファイルの隣に置かれ、2 つの座標をディレクトリ階層ではなくファイル名に持ちます。1 つ目は Feature のアタッチ先のコンポーネント、2 つ目はアタッチ時の名前です。ここでの 2 つ目の座標は誰かが書いた名前ではなく、アノテーションが生成したもので、アノテーションキーそのもの feature.aggrega.ai/monitoring です。ドットとスラッシュはそのままではファイル名に入れられないため、それぞれ -z と 1 文字に置き換えられます。ドットは -zd、スラッシュは -zs です。payments バウンダリーの api コンポーネントについて、ビルドは次のファイルを書き出します

dist/payments/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-api-scrape.yaml

このエンコードにより、キー内のスラッシュが独自のディレクトリを作ることはありません。これが重要なのは、1 階層下にあるファイルは、バウンダリーディレクトリを読むスクレイプ設定のコンシューマーには拾われないからです。

この例では、core/prometheus-exporter とその ServiceMonitor FeatureRecipe(および helm プロバイダー)を標準ライブラリから利用します。デモ用の example/compute/service コンポーネントとそのレシピは、共有カタログ内の example/ パブリッシャーの下に、これらの標準ライブラリのエンティティと並んで置かれています。この例の .aggrega-config.yaml は hub.aggrega.ai をデフォルトのレジストリとして宣言しているため、エンティティはハブから解決されます。どちらのコマンドにも --catalog フラグは不要です。

Componentバウンダリーintervalportpath
gatewayplatform30s(platform のデフォルト)metrics/metrics
api / worker / ledgerpayments15s(オーバーライド)metrics/metrics
etl / reconcilebatch120s(オーバーライド)metrics/metrics

この表で具体的に示される 3 つの事実:

  1. 作成者の宣言ではなく、アノテーション駆動。 Aggregate にはモニタリング用の features: がどこにもないのに、6 つの ServiceMonitor がレンダリングされます。これらが存在するのは、アノテーションが core/prometheus-exporter を各コンポーネントに展開したからだけです(ビルドグラフにおけるアタッチメントの origin は explicit ではなく annotation です)。
  2. サブキー単位のディープマージ。 payments と batch は interval しか設定していませんが、 その ServiceMonitor は port: metrics と path: /metrics を持ちます。これらは platform アノテーションの構造化された値から継承され、サブキー単位でマージされたものです。サブツリーは 1 つのフィールドをオーバーライドしながら、兄弟フィールドを継承します。
  3. ファンアウト。 6 つのコンポーネントが、1 つの platform アノテーションと 2 つの 1 行のオーバーライドだけでモニタリングされます。コンポーネントごとに features: ブロックを繰り返す必要はありません。

ServiceMonitor は Service の名前付き metrics ポートをスクレイプします(合成された Service は metrics: 9090 を公開します)。そのため、バインディングの port: metrics は実在するエンドポイントに解決されます。

コンパイル時とランタイム

これは Kubernetes/Helm の例であり、その証拠は dist/ 内のレンダリングされたマニフェストです。ServiceMonitor の port は Service の名前付きポートを参照しているため、セレクターとエンドポイントは構造上一致し、配線の検証にクラスターは必要ありません。稼働中の Prometheus Operator であれば、デプロイ時にレンダリングされた ServiceMonitor を利用します。コンパイラの役割(アノテーション → カスケードで解決されたプロファイルを持つコンポーネントごとの ServiceMonitor)は、事前に完了しており、確認することができます。

ビルドは決定的です。再実行しても出力はバイト単位で同一です。