Fluentd — ログアグリゲーター、2 つのターゲット
この例では、Fluentd ログアグリゲーター(ログパイプラインの受信側)を、Developer が作成した 1 つの Aggregate から 2 つの実現形態へコンパイルします:
- ローカル開発向けの Docker Compose、そして
- 公式のアップストリーム
fluent/fluentdイメージを Kubernetes 上で直接実行する 合成された helm Recipe(外部チャートなし)。
合成された helm Recipe はビルド時に何も取得しません。helm/fluentd-chart
は、チャートリポジトリに到達できるビルド向けに、Fluent プロジェクト自身のチャートを同じアグリゲーターとしてレンダリングします。
同じ aggregate.yaml が両方を駆動します。実現形態ごとに変わるのは、
Manifest が選択する Recipe 層だけです。
アグリゲーターの役割
ログパイプラインには 2 つの端があります。フォワーダー(Fluent Bit など)はログレコードを収集し、下流へ送ります。アグリゲーターはもう一方の端にあるシンクです。forward 入力プロトコルで待ち受け、上流のフォワーダーが送信するレコードを受信し、それを出力へルーティングします。ここでは Fluentd がアグリゲーターの役割を担います。
アグリゲーターは転送ではなく受信を行うため、下流の
uses ソケットを宣言しません。代わりに、forward エンドポイントのホストとポートを provides を通じてエクスポートし、フォワーダーがそれを forward ソケットにバインドしてレコードを送信できるようにします。forward エンドポイントはポート 24224(慣例的な Fluentd の forward ポート)で待ち受けます。
ファイル
| ファイル | 役割 |
|---|---|
aggregate.yaml | Developer の意図:forward 入力で待ち受ける aggregator コンポーネント(core/observability/fluentd)。 |
manifest-compose.yaml | Fluentd 型を Compose Recipe(compose/fluentd)にマッピングします。 |
manifest-helm-synth.yaml | Fluentd 型を合成された helm Recipe(helm/fluentd)にマッピングします。 |
release-compose.yaml / release-helm-synth.yaml | 2 つの実現形態のためのオペレーターレコード。 |
release-helm-synth-buffer.yaml | 永続バッファリングを有効にした合成 helm 実現形態(infra.storage.size を設定)。 |
Compose Recipe と合成された helm Recipe の両方が fluentd という名前を持つため、
Manifests はそれらをプロバイダースコープ付きで compose/fluentd および
helm/fluentd として参照します。
示す内容
- 1 つの作成インターフェース、多数のターゲット。 1 つの Aggregate が、スタックが 何 であるかの信頼できる唯一の情報源です。各 Manifest は、それを どのように 実現するかを記述します。
- String Pipe の受信側。 アグリゲーターは forward エンドポイントを
providesを通じてエクスポートします。forwardプロトコル上のhost(アグリゲーターのサービス)とport(24224)です。このコンポーネントをバインドするフォワーダーは、それらの文字列を自身の forward 出力へパイプします。コンパイラはそれらを解釈せずにルーティングします。 - Workload の合成(Kubernetes)。 合成された helm Recipe は Workload(公式の
fluent/fluentdイメージを実行する Deployment と ClusterIP Service)を宣言し、helm プロバイダーはそれを外部チャートなしで Kubernetes マニフェストに変換します。レンダリングされるリソースセットは、Workload が宣言するものと正確に一致します。 - Developer が制御するルーティング。 Developer の出力 match が、受信したどのレコードをアグリゲーターの出力へルーティングするかを選択します。デフォルトは
**で、受信したすべてのレコードをルーティングします。 - デフォルトでは一時的なバッファ、要求に応じて永続化。 アグリゲーターはメモリ上でバッファリングするため、デフォルトのレンダリングには永続ボリュームが含まれません。
infra.storage.sizeを設定すると(release-helm-synth-buffer.yamlを参照)、/fluentd/logにマウントされた永続ボリュームでバッファが裏付けられます。ワークロードは単一レプリカの Deployment のままです。 - 再現可能なイメージ。
infra.engine_versionが Fluentd イメージのタグを固定するため、レンダリングされたワークロードは固定されたイメージを参照し、合成された Recipe は浮動タグをレンダリングしません。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example fluentd-aggregatorその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd fluentd-aggregatorビルド
このワークスペースには .aggrega-config.yaml がないため、標準ライブラリのエンティティはハブレジストリ hub.aggrega.ai から解決され、カタログフラグは不要です。--auto-pull は、新しいクローンに欠けているロックファイルをビルド中に書き込みます。
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized helm Recipe, official image)aggrega build --release release-helm-synth.yaml --auto-pull
# Kubernetes with a durable buffer volumeaggrega build --release release-helm-synth-buffer.yaml --auto-pullレンダリングされた成果物は dist/ 配下に出力されます。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールだけを使い、フォルダーは自分で作成しないでください。ワークスペースフォルダーにまだ `fluentd-aggregator` フォルダーがない場合は、`example` を `fluentd-aggregator` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、例が新しい `fluentd-aggregator` フォルダーに書き込まれます。次に、各 Release について `build` ツールを 1 回ずつ、`release-compose.yaml`、`release-helm-synth.yaml`、`release-helm-synth-buffer.yaml` の順に呼び出してください。毎回、`workspace_root` を `fluentd-aggregator`、`release` をそのファイル、`auto_pull` を true、`write` を true に設定します。各ビルドが書き込んだファイルを教えてください。ファイルは `fluentd-aggregator/dist/` の下にあります。forward エンドポイントの内容
Compose では、アグリゲーターは forward ポートにバインドされた forward 入力ソースを持つ fluent.conf を書き出し、マッチしたレコードを標準出力へルーティングします:
<source> @type forward bind 0.0.0.0 port 24224</source><match **> @type stdout</match>Kubernetes では、合成された helm Recipe が起動時に同じ fluent.conf を書き出し、ClusterIP Service が forward ポートを公開します:
spec: type: ClusterIP [… omitted: the selector matching the aggregator's Pods] ports: - name: forward port: 24224 targetPort: forwardDeployment は固定されたイメージを参照し、コンテナ上で forward ポートを公開します:
image: fluent/fluentd:v1.19.3-debian-2.1[… omitted: the start-up command that writes the fluent.conf shown above]ports: - name: forward containerPort: 24224infra.storage.size が設定されている場合、Recipe はさらに
PersistentVolumeClaim をレンダリングして /fluentd/log にマウントし、ファイルバッファを裏付けることで、バッファされたレコードが再起動後も保持されるようにします。
実行する(Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -dアグリゲーターは localhost:24224 で転送されたレコードを待ち受けます。そのポートを指す任意の Fluentd または Fluent Bit フォワーダーでテストレコードを送信すると、受信したレコードがアグリゲーターの標準出力に表示されます。停止するには
docker compose -f dist/app/compose/docker-compose.yaml down を実行します。