Thanos 스택 — 오브젝트 스토리지 위의 메트릭 읽기 계층을 모듈로 구성하기
이 예제는 작지만 실제적인 스택인 Thanos
메트릭 시스템의 읽기/쿼리 계층을, 개발자가 작성한 하나의
Aggregate로부터 합성된 Kubernetes 매니페스트로 컴파일합니다.
읽기 계층은 단일 컴포넌트가 아닙니다. 이는 모듈, 즉 단일 워크로드 컴포넌트 세 개를 구성하는 재사용 가능한 하위 aggregate입니다.
- 과거 메트릭 블록을 볼륨에 보관하고 S3 API로 제공하는 S3 호환 오브젝트 스토어,
- 오브젝트 스토어에서 해당 블록을 읽어 StoreAPI를 통해 쿼리어에 제공하며, 임시 로컬 캐시만 보유하는 Store Gateway, 그리고
- PromQL에 응답하고 Store Gateway의 StoreAPI로 요청을 분산하며, 자체 상태를 보유하지 않는 Query 프런트엔드.
모듈은 자체 내부 엣지, 즉 Store Gateway에서 오브젝트 스토어로,
Query에서 Store Gateway로 향하는 엣지를 연결하고, Query를 공개 엔드포인트
query로 내보냅니다. 최상위 Aggregate는 모듈을 이름으로 가져와 구성된
스택을 렌더링하며, 운영자는 Release에서 모듈의 내부 컴포넌트 크기를
지정합니다.
파일
| 파일 | 역할 |
|---|---|
aggregate.yaml | 개발자 의도: Thanos 읽기 계층 모듈(core/thanos)을 가져옵니다. |
manifest-helm-synth.yaml | 오브젝트 스토어, Store Gateway, Query 타입을 해당 synth helm Recipes에 매핑하고, 모듈이 연결하는 자격 증명 Feature를 모듈의 두 키 파라미터 각각으로부터 Secret을 생성하는 구현에 매핑합니다. |
release-helm-synth.yaml | Kubernetes 대상에 대한 운영자 레코드입니다. 모듈 범위 ID로 모듈의 내부 컴포넌트 크기를 지정하며, 스키마 기본값에 맡긴 항목은 자체 완결적으로 렌더링됩니다. |
런타임 전제 조건
이 모듈은 읽기/쿼리 계층 전용입니다. 오브젝트 스토어는 Store Gateway가 읽는 thanos 버킷을 서비스 시작 전에 생성하므로, 렌더링된 매니페스트 밖에서 런타임에 제공해야 하는 유일한 것은 메트릭 블록을 생성하는 writer입니다. 읽기 계층은 블록을 제공할 뿐 생성하지 않습니다. Thanos Receive 계층이나 Thanos 사이드카가 있는 Prometheus 인스턴스 같은 writer가 같은 버킷으로 메트릭 블록을 전송해야 합니다. writer가 블록을 업로드하기 전까지 Store Gateway는 빈 결과 집합을 제공합니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example thanos-stack그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd thanos-stack빌드
이 워크스페이스에는 .aggrega-config.yaml이 없으므로 표준 라이브러리 엔터티는 허브 레지스트리 hub.aggrega.ai에서 해석되며 카탈로그 플래그가 필요하지 않습니다. --auto-pull은 새 클론에 없는 lockfile을 빌드 중에 기록합니다.
aggrega build --release release-helm-synth.yaml --auto-pull렌더링된 아티팩트는 dist/ 아래에 생성됩니다. Kubernetes 대상은 오프라인으로
일반 매니페스트를 렌더링하므로 차트를 가져올 필요가 없습니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고, 폴더를 직접 만들지 마십시오. 작업 영역 폴더에 아직 `thanos-stack` 폴더가 없으면 `example`을 `thanos-stack` 값으로 설정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 새 `thanos-stack` 폴더에 예제가 작성됩니다. 그런 다음 `workspace_root`를 `thanos-stack` 값으로, `release`를 `release-helm-synth.yaml` 값으로, `auto_pull`을 true로, `write`를 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 작성한 파일을 알려 주십시오. 파일은 `thanos-stack/dist/` 아래에 있습니다.구성된 스택의 모습
Store Gateway는 상태 없는 Deployment와, StoreAPI gRPC 포트 및 HTTP 포트를 노출하는 ClusterIP Service로 렌더링됩니다. 컨테이너는 thanos store와 하나의 인라인 --objstore.config 플래그로 시작되며, 이 플래그의 값은 오브젝트 스토어가 게시하는 엔드포인트, 즉 클러스터 내 Service 이름과 포트로 구성한 S3 스탠자이고, 해당 엔드포인트가 일반 HTTP로 제공되므로 insecure: true를 포함합니다. 이 구성은 AWS SDK 자격 증명 체인을 선택하므로 시크릿을 담지 않습니다. 액세스 키의 두 부분은 모두 Secret에서 읽는 환경 변수로 전달됩니다.
args: - store - --grpc-address - 0.0.0.0:10901 - --http-address - 0.0.0.0:10902 - --data-dir - /var/thanos/store - |- --objstore.config=type: S3 config: bucket: thanos endpoint: metrics-zdobjstore-default:8333 insecure: true aws_sdk_auth: true[… omitted: the container ports for the two addresses named in the args]env: - name: AWS_ACCESS_KEY_ID valueFrom: secretKeyRef: name: metrics-zdstore-s3.credential-id key: s3-access-key - name: AWS_SECRET_ACCESS_KEY valueFrom: secretKeyRef: name: metrics-zdstore-s3.credential key: s3-secret-key[… omitted: the container's resources and its liveness and readiness probes]Query는 상태 없는 Deployment와 HTTP 포트의 ClusterIP Service로
렌더링됩니다. 컨테이너는 thanos query로 시작되며, store 엣지로부터 구성된
엔드포인트에서 Store Gateway의 StoreAPI에 연결합니다.
args: - query - --http-address - 0.0.0.0:10902 - --grpc-address - 0.0.0.0:10901 - --endpoint - metrics-zdstore-default:10901오브젝트 스토어는 /data에 볼륨 클레임이 마운트된 레플리카 하나짜리 SeaweedFS StatefulSet, S3 포트 8333의 ClusterIP Service, 그리고 StatefulSet이 지정하는 headless Service로 렌더링됩니다. init 컨테이너가 서버가 서비스를 시작하기 전에 thanos 버킷을 생성합니다. 서버의 계정은 같은 키 쌍이며, 자체 Secret 두 개인 metrics-zdobjstore-access-key-id와 metrics-zdobjstore-secret-access-key에서 읽습니다. 네 Secret은 워크로드와 함께 생성되며, 두 개는 오브젝트 스토어의 키 슬롯용이고 두 개는 Store Gateway의 s3 연결이 담는 키 쌍용으로, 각각 모듈의 개발용 기본값을 담습니다.
보여 주는 내용
- 모듈로서의 구성. 다중 워크로드 기능, 즉 실제로는 오브젝트 스토어와 Store Gateway와 쿼리 프런트엔드로 이루어진 메트릭 읽기 계층을 하나의 거대한 컴포넌트가 아니라 단일 워크로드 컴포넌트 세 개를 구성하는 하위 aggregate로 패키징합니다. 모듈은 이름으로 가져오며 Thanos 읽기 계층이 필요한 곳 어디서나 재사용됩니다.
- 제공된 백엔드의 재사용. 오브젝트 스토어는 표준 라이브러리의
core/storage/s3-object-store컴포넌트를 그대로 재사용하며, 읽기 계층은 자체 스토리지 로직을 추가하지 않습니다. Manifest가 SeaweedFS 구현을 선택하므로 스토어는 클러스터에서 읽기 계층과 나란히 실행됩니다. - 모듈 내부의 엣지. Store Gateway는 오브젝트 스토어 사용을 선언하고 Query는
Store Gateway 사용을 선언합니다. 오브젝트 스토어가 게시한
endpoint와 Store Gateway가 게시한 호스트 및 포트는 각 엣지에서 소비자로 전달되며, 각 소비자의 Recipe가 이를 바탕으로 주소를 만듭니다. 컴파일러는 문자열을 해석하지 않고 라우팅합니다. - 공개 엔드포인트. 모듈은 Query를
query로 내보내며, 이는 소비자가 연결하는 안정적인 공개 이름으로서 모듈의 내부 컴포넌트 이름과 분리되어 있습니다. - 시크릿 없는 구성. 오브젝트 스토어 구성은 AWS SDK 자격 증명 체인을 선택하므로 렌더링된 구성에는 시크릿이 담기지 않으며, 자격 증명은 환경 변수로만 전달됩니다.
- 참조로 받는 공유 키 쌍. Store Gateway는 스토어 자체의 계정으로 오브젝트 스토어에 인증하므로 둘은 하나의 키 쌍을 공유합니다. 모듈은 각 절반을 파라미터
s3_access_key와s3_secret_key로 받아, 각각으로core/referenced-secret자격 증명 Feature를 두 번 연결합니다. 한 번은 오브젝트 스토어의access_key_id와secret_access_key슬롯에, 또 한 번은 게이트웨이가 키를 제시하는 연결인, Store Gateway의 오브젝트 스토어 연결의credential_id와credential로 연결합니다. 각 워크로드는 이를 인라인으로 담지 않고 Secret에서 읽습니다. 모듈이 해당 Feature를 연결하므로 Manifest가 이를 매핑합니다. 이 예제는 파라미터를 모듈의 개발용 기본값으로 두고 Feature를k8s-secret-from-parameter에 매핑하며, 이는 각 값을 담은 Secret을 생성하므로 스택이 자체 완결적으로 실행됩니다. 실제 트래픽을 처리하는 Release의 경우 Aggregate가 자체 파라미터를 선언하고aggregates.metrics.parameters를 통해 하위로 전달하며, Release가 이를 충족하고, Manifest가 Feature를k8s-existing-secret에 매핑합니다. 이는 각 파라미터를 네임스페이스에 이미 존재하는 Secret의 이름으로 읽습니다. - 재현 가능한 이미지. 모든 컴포넌트가 명시적인 이미지 태그를 고정하므로 렌더링된 매니페스트는 안정적인 이미지를 참조합니다.