콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

Fluentd — 로그 애그리게이터, 두 가지 대상

이 예제는 로그 파이프라인의 수신 측인 Fluentd 로그 애그리게이터를, 개발자가 작성한 하나의 Aggregate에서 두 가지 구현으로 컴파일합니다.

  • 로컬 개발용 Docker Compose, 그리고
  • 공식 업스트림 fluent/fluentd 이미지를 Kubernetes에서 직접 실행하는 합성된 helm Recipe(외부 차트 없음).

합성된 helm Recipe는 빌드 시점에 아무것도 가져오지 않습니다. helm/fluentd-chart는 차트 저장소에 접근할 수 있는 빌드를 위해 Fluent 프로젝트의 자체 차트를 동일한 애그리게이터로 렌더링합니다.

동일한 aggregate.yaml이 두 구현을 모두 구동합니다. 구현마다 달라지는 것은 Manifest가 선택하는 Recipe 계층뿐입니다.

애그리게이터 역할

로그 파이프라인에는 두 끝이 있습니다. 포워더(예: Fluent Bit)는 로그 레코드를 수집하여 다운스트림으로 전송합니다. 애그리게이터는 반대편 끝의 싱크로, forward 입력 프로토콜에서 수신 대기하며 업스트림 포워더가 보내는 레코드를 받아 출력으로 라우팅합니다. 여기서 Fluentd는 애그리게이터 역할을 합니다.

애그리게이터는 전달하지 않고 수신하므로 다운스트림 uses 소켓을 선언하지 않습니다. 대신 provides를 통해 forward 엔드포인트의 호스트와 포트를 내보내므로, 포워더는 forward 소켓에서 이를 바인딩하여 레코드를 전송할 수 있습니다. forward 엔드포인트는 관례적인 Fluentd forward 포트인 포트 24224에서 수신 대기합니다.

파일

파일역할
aggregate.yaml개발자 의도: forward 입력에서 수신 대기하는 aggregator 컴포넌트(core/observability/fluentd).
manifest-compose.yamlFluentd 타입을 Compose Recipe(compose/fluentd)에 매핑합니다.
manifest-helm-synth.yamlFluentd 타입을 합성된 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는 이들을 프로바이더 범위로 compose/fluentd 및 helm/fluentd로 참조합니다.

보여 주는 내용

  • 하나의 작성 표면, 여러 대상. 하나의 Aggregate가 스택이 무엇인지에 대한 단일 진실 공급원입니다. 각 Manifest는 이를 어떻게 구현할지를 나타냅니다.
  • String Pipe의 수신 측. 애그리게이터는 provides를 통해 forward 엔드포인트를 내보냅니다. forward 프로토콜의 host(애그리게이터의 서비스)와 port (24224)입니다. 이 컴포넌트를 바인딩하는 포워더는 해당 문자열을 자신의 forward 출력으로 전달하며, 컴파일러는 이를 해석하지 않고 라우팅합니다.
  • Workload 합성(Kubernetes). 합성된 helm Recipe는 공식 fluent/fluentd 이미지를 실행하는 Deployment와 ClusterIP Service로 구성된 Workload를 선언하며, helm 프로바이더는 이를 외부 차트 없이 Kubernetes 매니페스트로 변환합니다. 렌더링된 리소스 집합은 Workload가 선언한 것과 정확히 같습니다.
  • 개발자가 제어하는 라우팅. 개발자의 출력 match는 수신된 레코드 중 어떤 것을 애그리게이터의 출력으로 라우팅할지 선택합니다. 기본값은 **이며, 수신된 모든 레코드를 라우팅합니다.
  • 기본은 임시 버퍼, 요청 시 영구 버퍼. 애그리게이터는 메모리에 버퍼링하므로 기본 렌더링에는 영구 볼륨이 없습니다. infra.storage.size를 설정하면 (release-helm-synth-buffer.yaml 참조) /fluentd/log에 마운트된 영구 볼륨이 버퍼를 뒷받침하며, 워크로드는 단일 레플리카 Deployment로 유지됩니다.
  • 재현 가능한 이미지. infra.engine_version은 Fluentd 이미지 태그를 고정하므로, 렌더링된 워크로드는 고정된 이미지를 참조하고 합성된 Recipe는 유동 태그를 렌더링하지 않습니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

Terminal window
aggrega scaffold --example fluentd-aggregator

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:

Terminal window
cd fluentd-aggregator

빌드

이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다. --auto-pull은 새 클론에 없는 lockfile을 빌드 중에 기록합니다.

Terminal window
# 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 volume
aggrega build --release release-helm-synth-buffer.yaml --auto-pull

렌더링된 아티팩트는 dist/ 아래에 생성됩니다.

AI 어시스턴트 사용

Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고, 폴더는 직접 만들지 마십시오. 작업 영역 폴더에 아직 `fluentd-aggregator` 폴더가 없으면 `example`을 `fluentd-aggregator`로 설정하고 `dir`은 지정하지 않은 채 `scaffold` 도구를 한 번 호출하십시오. 이 도구는 예제를 새 `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에서 애그리게이터는 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: forward

Deployment는 고정된 이미지를 참조하고 컨테이너에서 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)

Terminal window
aggrega build --release release-compose.yaml --auto-pull
docker 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을 실행합니다.