Fluentd——日志聚合器,两个目标
本示例将一个 Fluentd 日志聚合器(日志管道的接收端)从一个由 Developer 编写的 Aggregate 编译为两种实现:
- 用于本地开发的 Docker Compose,以及
- 合成的 helm Recipe,直接在 Kubernetes 上运行官方上游
fluent/fluentd镜像(无外部 chart)。
合成的 helm Recipe 在构建时不获取任何内容;helm/fluentd-chart
则将 Fluent 项目自己的 chart 渲染为同一个聚合器,适用于能够
访问 chart 仓库的构建。
同一个 aggregate.yaml 驱动两者。每种实现之间只有
Manifest 所选的 Recipe 层不同。
聚合器角色
日志管道有两端。转发器(例如 Fluent Bit)收集日志
记录并将其发往下游。聚合器是另一端的汇点:它监听 forward 输入协议,接收上游
转发器发来的记录,并将其路由到自己的输出。此处 Fluentd 扮演
聚合器角色。
由于聚合器负责接收而非转发,它不声明下游
uses 套接字,而是通过 provides 导出其 forward 端点的主机和端口,使转发器可以在 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 | 两种实现的运维记录。 |
release-helm-synth-buffer.yaml | 启用了持久缓冲(设置了 infra.storage.size)的合成 helm 实现。 |
由于 Compose Recipe 和合成的 helm Recipe 都名为 fluentd,
Manifests 以 provider 限定的方式将它们引用为 compose/fluentd 和
helm/fluentd。
演示内容
- 一个编写界面,多个目标。 单个 Aggregate 是栈是什么的 唯一事实来源。每个 Manifest 说明如何实现它。
- String Pipe 的接收端。 聚合器通过
provides导出其 forward 端点:forward协议上的host(聚合器的服务)和port(24224)。绑定此组件的转发器会将这些字符串 传入自己的 forward 输出;编译器只路由它们,不加解释。 - Workload 合成(Kubernetes)。 合成的 helm Recipe 声明一个
Workload(一个 Deployment 加一个 ClusterIP Service,运行官方
fluent/fluentd镜像),由 helm provider 在无外部 chart 的情况下将其转换为 Kubernetes 清单。渲染出的资源集与 该 Workload 声明的完全一致。 - 由开发者控制的路由。 开发者的输出匹配决定哪些
接收到的记录被路由到聚合器的输出。默认值为
**, 即路由所有接收到的记录。 - 默认临时缓冲,按需持久化。 聚合器在
内存中缓冲,因此默认渲染不包含持久卷。设置
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 注册表 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` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `fluentd-aggregator`,且不设置 `dir`:它会把示例写入新的 `fluentd-aggregator` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具 — `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 上,聚合器写入一个 fluent.conf,其中包含绑定到 forward 端口的 forward 输入源,
并将匹配的记录路由到标准输出:
<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: 24224设置 infra.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 进行清理。