Loki — Kubernetes 로그 집계 서버
이 예제는 작지만 실제로 쓰이는 스택인 Grafana Loki 로그 집계
서버를 Developer가 작성한 하나의 Aggregate에서 Kubernetes로 컴파일하며,
단일 바이너리 형태의 공식 Grafana Loki Helm 차트를 기반으로 합니다.
Loki는 로그 백엔드입니다. HTTP 푸시 API로 로그 스트림을 수신하고, 전문(full-text) 내용이 아닌 레이블로 색인하며, 청크 객체 저장소에 저장하고, 같은 HTTP API로 로그 쿼리 및 범위 요청에 응답합니다. 단일 바이너리 형태에서는 distributor, ingester, querier, compactor 등 모든 Loki 하위 시스템이 로컬 청크 저장소를 기반으로 하나의 프로세스 안에서 실행되므로, 서버 전체가 하나의 상태 저장 워크로드가 됩니다. 로그 전송기는 스트림을 Loki로 푸시하고, 대시보드 서버는 쿼리 API로 이를 다시 읽어 옵니다.
파일
| 파일 | 역할 |
|---|---|
aggregate.yaml | Developer 의도: 로그를 7일간 보관하는 단일 logging 컴포넌트(core/observability/loki). |
manifest.yaml | 컴포넌트 유형을 Loki 소스 Recipe(loki)에 매핑합니다. |
release.yaml | Kubernetes 대상에 대한 운영자 레코드: 서버 컴퓨팅과 청크 저장소 볼륨 크기. |
보여 주는 내용
- 하나의 작성 표면. 단일 Aggregate가 Loki가 무엇인지에 대한 단일 진실 공급원이고, Manifest는 이를 어떻게 구현할지를 정합니다.
- 단일 바이너리 로그 백엔드. 소스 Recipe는 Loki를 데이터 볼륨을 갖춘 하나의
StatefulSet,ConfigMap에 담긴 구성, HTTP 푸시 및 쿼리 엔드포인트를 노출하는Service, 그리고ServiceAccount로 렌더링합니다. 분산 확장 경로와 번들된 보조 서비스는 제외된, 하나의 자체 완결형 워크로드입니다. - Developer가 설정하는 보존 기간. 개발자의
retention_period는 프로세스 내 compactor로 전달되며, compactor는 저장된 로그 스트림이 그 기간을 넘기면 삭제합니다. - 내보낸 수집 계약. 컴포넌트는
uses토폴로지를 통해 클러스터 내 서비스 호스트와 포트를 내보내므로, 로그 전송기가 여기에 연결되어 스트림을 푸시합니다. - 재현 가능한 이미지. Recipe는 Loki 서버 이미지와 구성 리로드 사이드카 이미지를 해석 가능한 태그로 고정하므로, 렌더링된 워크로드는 고정된 버전을 참조합니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example loki-logging그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd loki-logging빌드
이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다.
aggrega pull --release release.yamlaggrega build --release release.yaml렌더링된 아티팩트는 dist/ 아래에 생성됩니다. 빌드는 aggrega pull 시 OCI
참조로 업스트림 차트를 해석하고 이를 lockfile에 고정합니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 작업 공간 폴더에 아직 `loki-logging` 폴더가 없으면 `example`에 `loki-logging` 값을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `loki-logging` 폴더에 작성됩니다. 그런 다음 `workspace_root` 값은 `loki-logging`, `release` 값은 `release.yaml`, `auto_pull` 값은 true, `write` 값은 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 작성한 파일을 알려 주십시오. 파일은 `loki-logging/dist/` 아래에 있습니다.렌더링 결과
빌드는 Loki 서버를 하나의 자체 완결형 Kubernetes 객체 집합으로 생성합니다.
StatefulSet— 청크 저장소를 영구 볼륨에 둔 단일 바이너리 Loki 프로세스,ConfigMap— Loki 구성 및 런타임 구성,Service— 포트 3100에서 HTTP 푸시 및 쿼리 엔드포인트를 노출,- 워크로드용
ServiceAccount와 그 접근 바인딩.
분산 read/write/backend 워크로드, 객체 저장소 서브차트, 캐시, 오퍼레이터는 렌더링되지 않으며, 렌더링 결과는 단일 Loki 워크로드입니다. Loki 서버와 구성 리로드 사이드카 이미지는 릴리스 태그로 고정되므로, 워크로드는 고정된 이미지를 참조합니다.