Fluentd — агрегатор логов, две целевые платформы
Этот пример компилирует агрегатор логов Fluentd — принимающую сторону конвейера логов — из одной сущности Aggregate, написанной разработчиком, в две реализации:
- Docker Compose для локальной разработки и
- синтезированный helm Recipe, запускающий официальный образ
fluent/fluentdнапрямую в Kubernetes (без внешнего чарта).
Синтезированный helm Recipe ничего не загружает во время сборки; helm/fluentd-chart
рендерит собственный чарт проекта Fluent как тот же агрегатор — для сборки, у которой
есть доступ к репозиторию чартов.
Один и тот же aggregate.yaml управляет обеими. От реализации к реализации меняется только слой Recipe, выбранный
сущностью Manifest.
Роль агрегатора
У конвейера логов два конца. Форвардер (например, Fluent Bit) собирает записи
логов и отправляет их дальше. Агрегатор — приёмник на другом конце: он слушает
входной протокол forward, принимает записи, которые ему отправляют вышестоящие
форвардеры, и направляет их в свой вывод. Здесь Fluentd играет роль агрегатора.
Поскольку агрегатор принимает, а не пересылает записи, он не объявляет нисходящий
сокет uses. Вместо этого он экспортирует хост и порт своей конечной точки forward
через provides, чтобы форвардер мог привязать её к сокету forward и отправлять
ей записи. Конечная точка forward слушает порт 24224 — общепринятый порт
forward в Fluentd.
Файлы
| Файл | Роль |
|---|---|
aggregate.yaml | Намерение разработчика: компонент aggregator (core/observability/fluentd), слушающий вход forward. |
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 | Синтезированная helm-реализация с включённой долговременной буферизацией (задан infra.storage.size). |
Поскольку и Compose Recipe, и синтезированный helm Recipe носят имя fluentd,
сущности Manifests ссылаются на них с указанием провайдера: compose/fluentd и
helm/fluentd.
Что демонстрирует пример
- Одна поверхность описания, много целевых платформ. Единственный Aggregate — источник истины о том, что представляет собой стек. Каждый Manifest описывает, как его реализовать.
- Принимающий конец String Pipe. Агрегатор экспортирует свою конечную точку forward
через
provides—host(сервис агрегатора) иport(24224) по протоколуforward. Форвардер, привязывающий этот компонент, передаёт эти строки в собственный вывод forward; компилятор маршрутизирует их, не интерпретируя. - Синтез рабочей нагрузки (Kubernetes). Синтезированный helm Recipe объявляет
Workload — Deployment и ClusterIP Service, запускающие официальный образ
fluent/fluentd, — который helm-провайдер транслирует в манифесты Kubernetes без внешнего чарта. Отрендеренный набор ресурсов в точности соответствует тому, что объявляет Workload. - Маршрутизация под контролем разработчика. Сопоставление вывода, заданное разработчиком,
определяет, какие принятые записи направляются в вывод агрегатора. По умолчанию оно равно
**, что направляет каждую принятую запись. - Временный буфер по умолчанию, долговременный по запросу. Агрегатор буферизует
в памяти, поэтому рендер по умолчанию не содержит постоянного тома. Задание
infra.storage.size(см.release-helm-synth-buffer.yaml) подкрепляет буфер долговременным томом, смонтированным в/fluentd/log; рабочая нагрузка остаётся Deployment с одной репликой. - Воспроизводимые образы.
infra.engine_versionфиксирует тег образа Fluentd, поэтому отрендеренная рабочая нагрузка ссылается на фиксированный образ, а синтезированный Recipe не рендерит плавающий тег.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example fluentd-aggregatorЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd fluentd-aggregatorСборка
В этом рабочем пространстве нет .aggrega-config.yaml, поэтому сущности стандартной библиотеки разрешаются из реестра hub, hub.aggrega.ai, и флаг каталога не нужен; --auto-pull во время сборки записывает lock-файл, которого нет в свежем клоне:
# 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/.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочей области ещё нет папки `fluentd-aggregator`, вызовите инструмент `scaffold` один раз, задав `example` равным `fluentd-aggregator` и не указывая `dir`: он запишет пример в новую папку `fluentd-aggregator`. Затем вызовите инструмент `build` один раз для каждой сущности Release в следующем порядке — `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.