Fluent Bit에서 Fluentd로 — 2계층 로그 파이프라인, 두 가지 대상
이 예제는 실제 로그 파이프라인 — forward 프로토콜로 Fluentd 집계기에 레코드를 전송하는 Fluent Bit 포워더 — 을 Developer가 작성한 하나의 Aggregate에서 두 가지 구현으로 컴파일합니다.
- 로컬 개발용 Docker Compose, 그리고
- 공식 업스트림
fluent/fluent-bit및fluent/fluentd이미지를 Kubernetes에서 직접 실행하는 합성된 helm Recipes(외부 차트 없음).
합성된 helm Recipes는 빌드 시점에 아무것도 가져오지 않습니다. 차트 저장소에 접근할 수 있는 빌드라면 helm/fluent-bit-chart
및 helm/fluentd-chart가 대신 Fluent 프로젝트 자체의 차트를 렌더링합니다.
동일한 aggregate.yaml이 두 구현을 모두 구동합니다. 구현마다 달라지는 것은
Manifest가 선택하는 Recipe 계층뿐입니다.
파이프라인
두 컴포넌트가 포워더-집계기 파이프라인을 구성합니다.
forwarder(core/observability/fluent-bit)는 로그 레코드를 수집하여forward출력으로 전송합니다. 상태 비저장 서버로 타입이 지정됩니다.aggregator(core/observability/fluentd)는forward입력 프로토콜로 수신 대기하며 레코드를 받아 출력으로 라우팅합니다. 상태 저장 서버로 타입이 지정됩니다. 합성된 helm Recipe는 기본적으로 메모리에 버퍼링하므로 단일 레플리카 Deployment로 렌더링됩니다.
포워더는 집계기에 대한 forward_target 사용을 선언합니다. 집계기의
provides.host와 provides.port — forward 엔드포인트의 호스트와 포트(관례적인 Fluentd forward 포트인 24224) — 는
포워더로 파이프되어 forward 출력의 Host와 Port로 렌더링됩니다. 따라서 포워더는
단일 엣지로부터 사전에 연결된 집계기의 forward 엔드포인트로 전송합니다.
파일
| 파일 | 역할 |
|---|---|
aggregate.yaml | Developer 의도: aggregator 싱크(core/observability/fluentd)와 집계기에 대한 forward_target 사용을 선언하는 forwarder(core/observability/fluent-bit). |
manifest-compose.yaml | Fluent Bit 타입을 Compose Recipe(compose/fluent-bit)에, Fluentd 타입을 Compose Recipe(compose/fluentd)에 매핑합니다. |
manifest-helm-synth.yaml | Fluent Bit 타입을 합성된 helm Recipe(helm/fluent-bit)에, Fluentd 타입을 합성된 helm Recipe(helm/fluentd)에 매핑합니다. |
release-compose.yaml / release-helm-synth.yaml | 두 구현에 대한 운영자 레코드입니다. |
Compose Recipe와 합성된 helm Recipe가 모두 fluent-bit와 fluentd라는
이름을 가지므로 Manifests는 이를 프로바이더 범위로(compose/… 및 helm/…)
참조합니다.
보여 주는 내용
- 하나의 작성 표면, 여러 대상. 하나의 Aggregate가 파이프라인이 무엇인지에 대한 단일 정보 원천입니다. 각 Manifest는 그것을 어떻게 구현할지를 기술합니다.
- String Pipe를 통한 forward 연결. 포워더는 집계기에 대한
forward_target사용을 선언하고, 집계기 Recipe의provides.host와provides.port는 포워더로 파이프되어forward출력의Host와Port로 렌더링됩니다. 컴파일러는 문자열을 해석하지 않고 라우팅합니다 — 따라서 같은 엣지에서 Compose 빌드는 compose 서비스 이름을, Kubernetes 빌드는 Service 이름을 연결합니다. - 상태 비저장 포워더의 소켓에 연결된 상태 저장 싱크. 포워더의
forward_target소켓은server또는stateful-server를 선택합니다. Fluentd는 상태 저장 서버로 타입이 지정되며 소켓에 문제없이 바인딩됩니다 — 소켓은 싱크가 상태를 보유하는지가 아니라 운영상의 서버 역할을 기준으로 선택합니다. 싱크가 사용하는 프로토콜은 이와 별도로 검사됩니다. forward 출력은 Fluentd forward 프로토콜을 사용하므로, 싱크가 Fluentd처럼protocol: forward를 게시하지 않으면 빌드가 중단됩니다. - Workload 합성(Kubernetes). 각 합성된 helm Recipe는 Workload — 공식 이미지를 실행하는 Deployment와 ClusterIP Service — 를 선언하며, helm 프로바이더가 이를 외부 차트 없이 Kubernetes 매니페스트로 변환합니다. 렌더링된 리소스 집합은 Workloads가 선언한 것과 정확히 일치합니다.
- 재현 가능한 이미지.
infra.engine_version이 각 이미지 태그를 고정하므로, 렌더링된 워크로드는 고정된 이미지를 참조하고 합성된 Recipes는 유동 태그를 렌더링하지 않습니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example fluent-bit-to-fluentd그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd fluent-bit-to-fluentd빌드
이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다. --auto-pull은 새 클론에 없는 lockfile을 빌드 중에 기록합니다.
# Local development (Docker Compose)aggrega build --release release-compose.yaml --auto-pull
# Kubernetes (synthesized helm Recipes, official images)aggrega build --release release-helm-synth.yaml --auto-pull렌더링된 아티팩트는 dist/ 아래에 생성됩니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고, 폴더는 직접 만들지 마십시오. 작업 영역 폴더에 아직 `fluent-bit-to-fluentd` 폴더가 없으면 `example`을 `fluent-bit-to-fluentd`로 설정하고 `dir`은 지정하지 않은 채 `scaffold` 도구를 한 번 호출하십시오. 이 도구는 예제를 새 `fluent-bit-to-fluentd` 폴더에 씁니다. 그런 다음 각 Release마다 `build` 도구를 `release-compose.yaml`, `release-helm-synth.yaml` 순서로 한 번씩 호출하십시오. 매번 `workspace_root`를 `fluent-bit-to-fluentd`로, `release`를 해당 파일로, `auto_pull`을 true로, `write`를 true로 설정합니다. 각 빌드가 쓴 파일을 알려 주십시오. 파일은 `fluent-bit-to-fluentd/dist/` 아래에 있습니다.주입된 forward 대상의 모습
Compose에서 포워더는 forward 출력이 집계기의 compose 서비스 이름과
forward 포트를 대상으로 하는 fluent-bit.conf를 작성합니다.
[OUTPUT] Name forward Match * Host aggregator Port 24224Kubernetes에서는 같은 출력이 집계기의 클러스터 내 Service 이름을 대상으로 합니다.
[OUTPUT] Name forward Match * Host aggregator-default Port 24224둘 다 같은 Aggregate 엣지에서 해석됩니다 — 집계기의 호스트와 포트는
forward_target 사용을 통해 전달되고, 각 대상은 이를 고유한 방식으로 렌더링합니다.
24224 포트는 집계기의 forward 엔드포인트로, provides를 통해 내보내져
사전에 포워더로 파이프됩니다.
실행하기(Compose)
aggrega build --release release-compose.yaml --auto-pulldocker compose -f dist/app/compose/docker-compose.yaml up -d포워더의 모니터링 엔드포인트는 호스트의 루프백 주소에만
http://localhost:2020으로 게시됩니다 — 이 엔드포인트의 /api/v1/metrics는 처리 및
전달된 레코드를 보고합니다. 이 엔드포인트는 호출자를 검사하지 않으므로, Release가
포워더에 infra.publish_on_all_interfaces: true를 설정하지 않는 한 호스트의 다른
인터페이스에는 게시되지 않습니다. 종료하려면
docker compose -f dist/app/compose/docker-compose.yaml down을 실행합니다.