환이의 개발일지

[Data Platform] KEDA 오토스케일링 가이드 (멀티 트리거 설계 feat. Airflow·Spark)

환이s — Mon, 13 Jul 2026 17:13:27 +0900

Intro

안녕하세요. 환이s입니다

지난 글에서는 KEDA를 Harbor + ArgoCD 기반으로 구축하고,

외부 모듈 연동을 위한 RBAC까지 구성하는 과정을 정리해 봤습니다.

이번 글에서는 그렇게 설치한 KEDA를 실제로 활용해서,

이벤트 기반 멀티 트리거 ScaledObject를 설계하는 방법을 정리해보려고 합니다.

실측으로 스케일 값을 계산하고,

성경이 다른 두 신호 (양·지연)를 조합하고,

스케일업·다운을 비대칭으로 설계하는 이 원칙들은 특정 워크로드에 국한되지 않습니다.

다만 개념만 나열하면 와닿지 않으니,

이번 편에서는 Airflow의 Celery Worker를 스케일 대상 예시로 삼아

설계 과정을 처음부터 끝까지 따라갑니다.

지금까지 구축한 파이프라인은 Airflow가 DAG를 돌리고

그 안에서 Spark Job을 K8s에 제출하는 구조라,

Worker(KEDA)와 Spark Executor(DynamicAllocation)를

어떻게 같은 기준으로 움직이게 할지가 핵심 과제였고,

이 사례가 멀티 트리거 설계의 필요성을 잘 보여주기 때문입니다.

이번 글에서는

Spark를 KEDA로 직접 스케일할 수 없는 이유와 우회 설계
statsd extraMappings로 Airflow 메트릭을 표준화하는 방법
ServiceMonitor로 statsd 메트릭을 Prometheus에 수집시키는 방법
worker_concurrency 실측으로 스케일 값을 정확히 계산하는 방법
Redis + Prometheus 멀티 트리거 ScaledObject 설계 (v1 → v2)
task_id 명명규칙으로 정규식 쿼리의 전제를 강제하는 방법
실제 스케일 테스트에서 마주친 "너무 빨리 줄어드는" 현상의 정체

까지 순서대로 확인해 보겠습니다.

1. 오토스케일링 설계 방향 - "왜 Spark는 KEDA로 직접 못 하나"

구축 편에서 KEDA 설치를 마쳤으니, 이번 편은 본론인 오토스케일링입니다.

지금까지 구축한 파이프라인은 Airflow가 DAG을 돌리고,

그 안에서 Spark Job을 K8s에 제출하는 구조입니다.

(궁금하신 분들은 아래 링크 참고해 보시면 도움이 될 거 같습니다.)

[Data Platform] KEDA 구축 가이드(Operator 설치부터 API 연동용 RBAC까지)

Intro 안녕하세요. 환이s입니다 지난 글에서는 데이터 레이크하우스 플랫폼을 GitOps 방식으로 관리하기 위해ArgoCD를 Kubernetes 위에 구축하고 App of Apps 패턴으로 전체 스택을 운영하는 과정을 정

drg2524.tistory.com

[Data Platform] Airflow 구축 가이드 (feat. Spark on Kubernetes)

Intro 안녕하세요. 환이s입니다 지난 글에서는 데이터 레이크하우스 플랫폼의 네 번째 스택으로 Trino + Hive Metastore + PostgreSQL 3계층 구조로 Delta Lake SQL 조회 환경을 구축하는 과정을 정리해 봤습

drg2524.tistory.com

이상적으로는 KEDA 하나로 Worker와 Spark Executor를 모두 제어하고 싶었습니다.

이 방향을 KEDA 단일 제어로 검토했지만,

SparkApplication 리소스가 /scale 서브리소스를 지원하지 않아

KEDA가 직접 스케일하는 것은 기술적으로 불가능했습니다.

그래서 채택한 것이 메트릭 표준화입니다.

즉, Worker와 Executor가 서로 다른 메커니즘으로 움직이더라도,

같은 메트릭 기준에 맞춰 동작하도록 통일하는 절충안입니다.

참고
공식 Airflow Helm chart에는 workers.celery.keda.enabled=true 한 줄로
Airflow metadata DB(task_instance 테이블)를 직접 쿼리하는
KEDA 통합 기능이 내장돼 있습니다.
다만 지금까지 구축한 파이프라인이 그동안 직접 구축한
ScaledObject의 검증·버그 수정 이력을 보존하기 위해 기존 방식을 유지하고,
공식 기능은 참고만 했습니다.

⚠️ 주의
공식 내장 기능과 직접 만든 ScaledObject를 동시에 켜면 절대 안 됩니다.
HPA 두 개가 같은 StatefulSet을 두고 경쟁하게 됩니다.

즉, 여기서 확인할 수 있는 핵심은

모든 것을 KEDA로 단일 제어하려 하지 말고,

기술적 제약(Spark /scale 미지원)을 인정한 뒤,

"메트릭 기준을 통일"하는 방향으로 우회했다는 점입니다.

2. 파일 구조 - "오토스케일링 설정은 어디에 있나"

본격적인 설정에 들어가기 전에,

파일이 어디에 있는지 부터 짚고 가겠습니다.

오토스케일링 관련 설정은 KEDA 디렉토리가 아니라

스케일 대상인 Airflow 쪽 manifests에 모여 있습니다.

services/airflow/manifests/
├── 00_rbac
├── 10_pvc
├── 20_ingress
├── 30_filebrowser
├── 40_monitoring
│   └── 10_servicemonitor-airflow-statsd.yaml   # Prometheus 수집 (섹션 4)
└── 50_autoscaling
    └── 10_scaledobject-airflow-worker.yaml      # ScaledObject 본체 (섹션 6)

구축편에서 본 KEDA 엔진(services/keda/)과 대비하면 역할이 이렇게 나뉩니다.

KEDA 엔진 (services/keda/) — Operator·CRD·RBAC 등 "스케일을 수행하는 주체"
스케일 규칙 (services/airflow/manifests/50_autoscaling/) — ScaledObject 등 "무엇을 어떻게 스케일 할지"
메트릭 수집 (services/airflow/manifests/40_monitoring/) — ServiceMonitor 등 "판단 근거가 될 메트릭 파이프라인"

즉, 여기서 확인할 수 있는 핵심은 "스케일 하는 주체(KEDA)"와 "스케일 당하는 대상의 규칙(Airflow ScaledObject)"을 경로상으로 분리해서, 각각 독립적으로 관리했다는 점입니다.

3. 메트릭 표준화 - statsd extraMappings

멀티 트리거를 만들려면 Prometheus 쿼리가 필요한데,

기존 Airflow 메트릭은 DAG 이름별로 메트릭명 자체가 갈라져 있는 게 문제였습니다.

airflow_dag_<dag_name_a>_submit_spark_job_queued_duration_sum
airflow_dag_<dag_name_b>_submit_spark_job_queued_duration_sum

이러면 신규 DAG를 추가할 때마다 쿼리를 고쳐야 합니다.

services/airflow/helm/values.yaml에 statsd.extraMappings를 추가해 메트릭명을 통일했습니다.

statsd:
  extraMappings:
    - match: airflow.dag.*.*.queued_duration
      name: "airflow_task_queued_duration"
      labels:
        dag_id: "$1"
        task_id: "$2"

적용 결과, 메트릭명이 하나로 통일되고 dag_id/task_id가 레이블로 분리됐습니다.

airflow_task_queued_duration_sum{dag_id="<dag_name_a>", task_id="submit_spark_job"}
airflow_task_queued_duration_sum{dag_id="<dag_name_b>", task_id="submit_spark_job"}

이제 sum() 합산 쿼리 하나로 전체 DAG를 커버할 수 있습니다.

참고
match 패턴(airflow.dag.*.*.queued_duration)의
와일드카드 두 개가 각각 dag_id($1)·task_id($2)로 매핑됩니다.

적용 전에 실제 statsd 메트릭 경로가
airflow.dag.<dag>.<task>.queued_duration 형태가
맞는지(중간에 다른 세그먼트가 끼지 않는지) 한 번 확인하세요.
세그먼트 수가 어긋나면 레이블이 엉뚱한 값으로 잡힙니다.

⚠️ 주의
이 ConfigMap을 kubectl edit으로 직접 고치면 안 됩니다.
Helm이 관리하는 리소스라 ArgoCD sync 시 원복됩니다.

즉, 여기서 확인할 수 있는 핵심은 메트릭명을 값(레이블)으로 빼내면,

신규 DAG가 추가돼도 쿼리를 고칠 필요가 없어진다는 점입니다.

4. Prometheus 수집 연결 - ServiceMonitor

statsd로 메트릭명을 표준화했어도,

그 메트릭이 Prometheus에 실제로 수집되어야 KEDA 트리거가 값을 읽을 수 있습니다.

Airflow의 statsd exporter가 노출하는 /metrics를 Prometheus가 긁어가도록

ServiceMonitor를 구성했습니다.

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: airflow-statsd
  namespace: monitoring
  labels:
    release: prometheus-helm      # prometheus의 serviceMonitorSelector와 일치해야 함
spec:
  namespaceSelector:
    matchNames:
      - airflow
  selector:
    matchLabels:
      component: statsd
      release: airflow-helm
  endpoints:
    - port: statsd-scrape          # 9102/TCP — Prometheus metrics 포트
      interval: 15s
      path: /metrics

참고
metadata.labels.release: prometheus-helm이 가장 자주 실수하는 부분입니다.
Prometheus Operator는 serviceMonitorSelector에
매칭되는 레이블을 가진 ServiceMonitor만 인식합니다.

이 값이 안 맞으면 ServiceMonitor를 만들어도
Prometheus가 무시해서 메트릭이 안 들어옵니다.

kubectl get prometheus -n monitoring -o yaml | grep -A5 serviceMonitorSelector로 실제 셀렉터를 먼저 확인하세요.

⚠️ 주의
statsd exporter는 포트가 두 개입니다.
수집(scrape)은 9102/TCP statsd-scrape 이고,
Airflow가 메트릭을 보내는 ingest는 9125/UDP입니다.

ServiceMonitor의 port는 반드시 TCP metrics 포트를 가리켜야 합니다.

즉, 여기서 확인할 수 있는 핵심은

statsd 표준화(생산) → ServiceMonitor 수집(Prometheus) → KEDA 트리거(소비)로 이어지는 파이프라인이 전부 연결돼야 비로소 Prometheus 트리거가 동작한다는 점입니다.

5. worker_concurrency 실측 - "추정치를 실측값으로"

스케일 파라미터를 정하려면

Worker 하나가 동시에 처리하는 task 수(worker_concurrency)을 알아야 합니다.

추정하지 않고 직접 조회했습니다.

kubectl exec -n airflow airflow-helm-worker-0 -c worker -- \
  airflow config get-value celery worker_concurrency
# → 16

운영 예상 동시 트리거 규모(상한 300 기준)로 재계산했습니다.

300 / 16 ≈ 18.75  →  maxReplicaCount: 19
listLength: 16     (worker_concurrency와 동일하게 맞춤)

즉, 여기서 확인할 수 있는 핵심은

maxReplicaCount나 listLength 같은 값은 감이 아니라 실측된 worker_concurrency를 기준으로 계산해야 한다는 점입니다.

6. ScaledObject v1 → v2 변경 요약

초기 버전(v1)에서 운영 규모(v2)로 재설계한 내용입니다.

항목	v1	v2
minReplicaCount	1	2
maxReplicaCount	5	19 (실측 기반)
listLength	2	16 (실측 기반)
scaleUp stabilization	30s	15s
scaleUp policy	+2/30s	+4 또는 +100%/30s (Max)
restoreToOriginalReplicaCount	true	false
trigger	Redis 단일	Redis + Prometheus 멀티 트리거

restoreToOriginalReplicaCount는 ScaledObject가 삭제될 때,

대상 워크로드를 원래 replica 수로 되돌릴지를 정하는 옵션입니다.

v1은 true(원래값 복귀)였지만,

v2에서는 false로 두어 삭제 시점에 강제 복귀시키지 않고

HPA의 자율 판단에 맡기도록 변경했습니다.

멀티 트리거를 포함한 ScaledObject 실물 전체는 다음과 같습니다.

TriggerAuthentication과 Redis 비밀번호 Secret도 같은 파일에 함께 정의했습니다.

# ── Redis 접근 비밀번호 Secret ──
apiVersion: v1
kind: Secret
metadata:
  name: airflow-redis-secret
  namespace: airflow
type: Opaque
stringData:
  redis-password: "<REDIS_PASSWORD>"   # 실제 비밀번호로 교체
---
# ── KEDA가 Secret을 참조하기 위한 TriggerAuthentication ──
apiVersion: keda.sh/v1alpha1
kind: TriggerAuthentication
metadata:
  name: airflow-redis-auth
  namespace: airflow
spec:
  secretTargetRef:
    - parameter: password
      name: airflow-redis-secret
      key: redis-password
---
# ── 본체: ScaledObject ──
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: airflow-worker-scaler
  namespace: airflow
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: StatefulSet
    name: airflow-helm-worker

  minReplicaCount: 2        # 기본 가용성 확보 (단일 장애점 방지)
  maxReplicaCount: 19       # worker_concurrency=16 기준 실측 재계산 (300/16≈19)
  cooldownPeriod: 60

  advanced:
    restoreToOriginalReplicaCount: false   # 운영에선 원래값 강제 복귀 X, HPA 자율 판단
    horizontalPodAutoscalerConfig:
      behavior:
        scaleUp:
          stabilizationWindowSeconds: 15    # 폭주 대응 위해 빠르게 반응
          policies:
            - type: Pods
              value: 4                      # 한 번에 4개씩 확장
              periodSeconds: 30
            - type: Percent
              value: 100                    # 또는 현재 replica의 100%
              periodSeconds: 30
          selectPolicy: Max                 # 둘 중 큰 값 적용
        scaleDown:
          stabilizationWindowSeconds: 600   # 축소는 신중하게 (10분)
          policies:
            - type: Pods
              value: 2
              periodSeconds: 120

  triggers:
    # Trigger 1: Redis Celery 큐 길이 — 즉각적인 폭주 감지
    - type: redis
      authenticationRef:
        name: airflow-redis-auth
      metadata:
        address: airflow-helm-redis.airflow.svc.cluster.local:6379
        listName: celery
        listLength: "16"           # worker_concurrency(16)와 동일 (실측값)
        databaseIndex: "0"
        enableTLS: "false"

    # Trigger 2: Prometheus 큐 대기시간 — 후행 추세 감지
    #   순간적으로 큐가 비어도 누적 지연이 길었다면 스케일 유지
    - type: prometheus
      metadata:
        serverAddress: http://prometheus-helm-kube-prome-prometheus.monitoring:80
        query: |
          sum(rate(airflow_task_queued_duration_sum{task_id=~"submit_spark.*"}[5m]))
          /
          sum(rate(airflow_task_queued_duration_count{task_id=~"submit_spark.*"}[5m]))
        threshold: "3"             # 평균 큐 대기시간 3초 이상이면 스케일업 신호
        activationThreshold: "1"   # 이 값(1초)을 넘어야 트리거가 '활성'으로 잡힘

설계 의도를 정리하면 다음과 같습니다.

두 트리거의 역할 분담
- Redis(큐 길이)는 "지금 당장 쌓인 양"을 보는 선행 지표, Prometheus(대기시간)는 "누적된 지연 추세"를 보는 후행 지표입니다.
- 큐가 순간적으로 비어도 대기시간이 길었다면 스케일을 유지합니다.
비대칭 스케일 정책
- scaleUp은 15초 창 + 4개/100%로 공격적, scaleDown은 600초 창 + 2개로 보수적입니다.
- 폭주엔 빠르게 대응하되, 축소는 천천히 해서 플래핑(flapping)을 막습니다.
인증 분리
- Redis 비밀번호를 ScaledObject에 직접 넣지 않고 Secret + TriggerAuthentication으로 분리해, 여러 트리거가 같은 인증을 재사용할 수 있게 했습니다.

참고
threshold와 activationThreshold의 차이: threshold(3초)는
"몇 개로 스케일 할지" 계산에 쓰는 목표값이고, activationThreshold(1초)는
"이 트리거를 활성으로 볼지 말지"를 가르는 경계입니다.

지표가 1초 이하이면 이 Prometheus 트리거는 비활성으로 간주됩니다.
다만 minReplicaCount: 2라서 실제로 0까지 내려가진 않고, 최소 2개는 유지됩니다.

Prometheus 트리거의 쿼리는 "submit_spark로 시작하는

태스크들의 평균 큐 대기시간(대기시간 합 ÷ 건수)"을 계산합니다.

결과적으로 Redis 큐 길이(양)와 Prometheus 대기시간(지연)을 함께 보게 되므로,

큐가 짧아도 처리가 밀리면 스케일 업되는 구조입니다.

즉, 여기서 확인할 수 있는 핵심은

"양(Redis)"과 "지연(Prometheus)"이라는 성격이 다른 두 신호를 조합하고, 스케일업·다운을 비대칭으로 설계해 폭주 대응력과 안정성을 동시에 잡았다는 점입니다.

7. 명명규칙 수립 - task_id 표준화

위 쿼리의 task_id=~"submit_spark.*" 정규식이 동작하려면 운영 규칙이 전제되어야 합니다.

SparkKubernetesOperator를 사용하는 모든 태스크는

task_id를 submit_spark_로 시작해야 KEDA가 누락 없이 감지합니다.

✅ submit_spark_job → 감지됨
✅ submit_spark_daily → 감지됨
⬜ 모니터링/PythonOperator 등 비-Spark 태스크 → 패턴 밖 (정상, 규칙 대상 아님)

⚠️ 주의
쿼리에서 task_id="submit_spark.*"처럼 =(등호)를 쓰면 안 됩니다.
=는 리터럴 매칭이라 정규식으로 동작하지 않아 데이터가 영구 누락될 수 있습니다. 정규식 연산자 =~를 사용해야 합니다.

즉, 여기서 확인할 수 있는 핵심은

KEDA 쿼리가 정규식에 의존한다면, 그 정규식이 성립하도록 하는 "명명규칙"이 반드시 팀 차원에서 강제되어야 한다는 점입니다.

8. 스케일 테스트 - Worker 5개 규모 검증

v2 적용 후 실제 동작을 검증했습니다.

전체 19개를 한 번에 돌리기 전에, 1단계로 5개 규모부터 확인했습니다.

listLength=16 기준으로 Worker 5개를 목표로 큐 길이 80(= 16 x 5)을 밀어 넣었습니다.

kubectl exec -n airflow airflow-helm-redis-0 -- \
  redis-cli -a '<REDIS_PASSWORD>' -n 0 rpush celery $(seq 1 80 | sed 's/^/dummy/')

위 이미지를 확인해 보시면 정상적으로 스케일업에 성공했습니다.

⚠️ 주의
Airflow values.yaml에서 worker의 podAntiAffinity는
requiredDuringSchedulingIgnoredDuringExecution, 즉 "같은 노드에 worker Pod 두 개 금지"를 강제하는 설정입니다. 이 때문에 worker replica 수는 사실상 노드 수를 넘을 수 없습니다. maxReplicaCount: 19를 채우려면 그만큼의 노드가 필요하다는 뜻이고, 이 제약이 "풀스케일 테스트를 못 한 이유"와도 직결됩니다.

9. 예상치 못한 현상 - 5에서 곧바로 줄어듦

진행하면서 겪은 문제를 발견했습니다.

그건 바로 5/5에 도달하자마자 곧바로 줄어든 사례입니다.

5/5 → 5/1 → 4/1 → 3/1 ...

스케일다운 안정화 기간(stabilizationWindowSeconds: 600, 10분)을 설정했는데도

너무 빨리 줄어드는 것처럼 보여 원인을 조사했습니다.

1차 의심 — KEDA operator 에러 로그

ERROR scale_handler error getting metric spec for the scaler
error: "scaler with id 0 not found. Len = 0"

처음엔 멀티 트리거 구조 결함으로 의심했지만,

전체 로그를 다시 보니 이 에러는 단 1회만 발생하고 재발이 없었습니다.

같은 grep 결과에 섞여 있던 다른 에러들은 과거 날짜의 무관한 기존 리소스 에러였고,

grep 결과를 잘못 해석한 것이었습니다.

2차 확인 — HPA current 값

"s0-redis-celery" (target average value): 0 / 16

스케일다운 시점의 current 값이 0이었습니다.

KEDA가 잘못 읽은 게 아니라 실제로 큐가 비어 있었던 겁니다.

3차 확인 — Redis 직접 조회

kubectl exec -n airflow airflow-helm-redis-0 -- redis-cli -a '<REDIS_PASSWORD>' -n 0 llen celery
# → 0

더미 데이터 80개가 실제로 큐에서 사라진 것을 직접 확인했습니다.
KEDA 설정(주소, DB index)과 Celery 실제 broker_url도 정확히 일치했습니다.

즉, 여기서 확인할 수 있는 핵심은 "stabilizationWindow가 안 먹은 것"이 아니라, 더미 데이터가 Worker에 의해 소비되어 큐가 예상보다 빨리 비워졌고, KEDA는 그 변화를 정확히 감지해 최솟값(2)으로 정상 축소한 것이라는 점입니다.

현상은 정상이었습니다.

참고
더미 문자열은 Celery Worker가 처리 시도 후 실패/폐기하면서 곧바로 큐에서 사라집니다. 그래서 실제 부하와 달리 큐가 순식간에 비워진 것입니다. 더 정밀한 검증이 필요하다면 더미 문자열이 아닌 실제 Celery 태스크로 재테스트하는 것을 권장합니다.

10. 검증 완료 항목

1~5개 규모 기준으로 검증이 끝난 항목입니다.

항목	결과
스케일업 (2→5)	정상
podAntiAffinity 노드 분산	정상
스케일다운 (5→2)	정상 (큐 소진에 따른 정당한 반응)
KEDA 멀티 트리거(Redis+Prometheus) 구조 안정성	결함 없음 확인
Spark DynamicAllocation 동시 다중 실행	3개 SparkApplication 동시 RUNNING → 충돌 없이 COMPLETED
statsd extraMappings 메트릭 표준화	단일 메트릭 통합 완료
Prometheus 멀티 트리거 쿼리 실측	평균 큐 대기시간 0.66초 확인

최종 검증 결과 요약입니다.

Max Replica Count: 19
Min Replica Count: 2
List Length: 16
External Metric Names: s0-redis-celery, s1-prometheus
Triggers Types: redis, prometheus
Triggers Activity: 둘 다 Is Active: false (현재 부하 낮아 정상, 에러 없음)

메트릭 표준화 목표를 달성했고,
Worker(KEDA, Redis+Prometheus 멀티 트리거)와 Executor(Spark DynamicAllocation)가
동일 기준 메트릭(airflow_task_queued_duration)에 정렬되어 동작합니다.

11. 오토스케일링 트러블슈팅 정리

지금까지 오토스케일링 작업 진행하면서 트러블슈팅 내용을 공유하고자 합니다.

증상	원인	해결
rate() 쿼리만 빈 응답, sum()은 정상	curl URL의 {, [ 특수문자가 셸에서 깨짐	--data-urlencode 사용
Prometheus 쿼리 결과 NaN	5분 윈도우 내 활동 없어 0/0 (정상 idle)	DAG 재트리거 후 정상값(0.6초대) 확인
*task_id="submit_spark." (등호) 사용**	=는 리터럴 매칭, 정규식 아님 — 데이터 영구 누락 위험	=~(정규식 연산자)로 수정
describe 결과가 v1 값(max=5) 그대로	sync 완료 직전 타이밍에 조회	1~2분 후 재확인 시 v2 값(max=19) 정상
KEDAScalerFailed: scaler with id 0 not found	트리거 재구성 시 1회성 과도기 메시지	이후 미반복, 무해 판정

마무리

이번 글에서는 1편에서 구축한 KEDA 위에,
Redis + Prometheus 멀티 트리거 ScaledObject를 설계하는 과정을 정리해 봤습니다.

스케일 대상으로는 Airflow Celery Worker를 예시로 삼았고,
Spark Executor는 /scale 미지원 제약 때문에 DynamicAllocation으로 우회하되,
statsd → ServiceMonitor → KEDA로 이어지는 파이프라인을 통해

Worker와 같은 메트릭 기준에 정렬시키는 "메트릭 표준화" 전략을 택했습니다.

특히 여기서 정리한 세 가지 설계 원칙은 Airflow가 아닌 다른 워크로드에도 그대로 적용됩니다.

maxReplicaCount·listLength 같은 값은 감이 아니라 실측(worker_concurrency=16)을 기준으로 계산한다
Redis(선행: 큐 길이) + Prometheus(후행: 대기시간) 멀티 트리거로, 스케일업은 공격적·다운은 보수적으로 비대칭 설계한다
정규식 쿼리(=~"submit_spark.*")에 의존한다면, 그 전제가 되는 명명규칙을 팀 차원에서 강제한다

정도가 되겠습니다.

참고로 이번에 남은 과제였던 maxReplicaCount=19 풀스케일 테스트는,
노드 자원 포화와 podAntiAffinity(required) 제약 때문에 자원 여유를 확보한 뒤로 미뤄둔 상태입니다.
이 부분은 자원 확보 후 별도로 정리하겠습니다.

다음 글에서는 플랫폼의 다음 스택으로,
시크릿(Secret)을 안전하게 관리하기 위한 Sealed Secrets와 Infisical 구축 과정을 다뤄보려고 합니다.

이번 글에서 Redis 비밀번호를 매니페스트에 평문으로 넣었던 부분(마스킹 처리한 그 값)을,
다음 편에서 제대로 된 시크릿 관리 체계로 옮기는 이야기를 이어가겠습니다.

궁금한 점이나 추가로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요!

[Data Platform] KEDA 구축 가이드(Operator 설치부터 API 연동용 RBAC까지)

환이s — Fri, 10 Jul 2026 16:38:40 +0900

Intro

안녕하세요. 환이s입니다

지난 글에서는 데이터 레이크하우스 플랫폼을 GitOps 방식으로 관리하기 위해

ArgoCD를 Kubernetes 위에 구축하고 App of Apps 패턴으로 전체 스택을 운영하는 과정을 정리해 봤습니다.

이번 글에서는 그 위에 얹을 오토스케일링 스택,

KEDA(Kubernetes Event-driven Autoscaling) 를 Harbor 레지스트리와 ArgoCD 기반으로 구축하는 과정을 정리해보려고 합니다.

단순히 CPU/Memory 기반으로 동작하는 HPA와 달리,

KEDA는 Redis 큐 길이나 Prometheus 메트릭 같은 실제 이벤트를 기준으로 Pod를 0~N개까지 스케일 할 수 있습니다.

Airflow처럼 "작업이 몰릴 때만 Worker가 필요한" 워크로드에 딱 맞는 도구죠.

이번 글에서는

KEDA 이미지·차트를 공식 소스(또는 사내 Harbor)로 준비하는 방법
Helm OCI 방식으로 KEDA 본체를 설치하는 방법
CRD를 클러스터에서 추출해 Git + ArgoCD로 별도 관리하는 방법
662KB짜리 CRD가 ArgoCD 적용에 실패할 때 대응하는 방법
ArgoCD sync-wave로 CRD·Operator·RBAC 기동 순서를 제어하는 방법
외부 모듈에서 K8s API로 KEDA 리소스를 조회하기 위한 RBAC·Secret 구성

까지 순서대로 확인해 보겠습니다.

이번 포스팅의 전제: KEDA를 완전히 백지에서 올린다기보다,
최초엔 Helm으로 한 번 설치해 클러스터에 띄운 KEDA를, CRD만 떼어내 Git + ArgoCD로 편입(흡수)하는 관점으로 정리했습니다. 즉 "이미 클러스터에 떠 있는 CRD를 GitOps 소스로 역이관하는" 흐름이 섹션 4의 핵심 맥락입니다.

이번 편은 "설치"에 집중하고, 실제로 Worker를 오토스케일링하는 방법은 다음 포스팅에서 다뤄보겠습니다.

1. KEDA 아키텍처 개요

본격적인 설치에 앞서, 이번 구성의 전체 그림을 먼저 이해하는 것이 중요합니다.

KEDA는 크게 세 가지 컴포넌트로 구성됩니다.

keda-operator : ScaledObject를 감시하고 HPA를 생성/조정하는 핵심 컨트롤러
keda-operator-metrics-apiserver : 외부 메트릭(Redis, Prometheus)을 K8s 메트릭 API로 노출
keda-admission-webhooks : ScaledObject 리소스 유효성 검증

즉, 여기서 확인할 수 있는 핵심은

KEDA 자체가 스케일을 직접 수행하는 게 아니라,

이벤트를 읽어서 표준 HPA를 만들어주는 "브릿지" 역할을 한다는 점입니다.

실제 저장소의 KEDA 디렉토리 구조는 다음과 같습니다.

services/keda/
├── crds/
│   ├── keda-crds-only.yaml         # CRD 5개 (클러스터에서 추출)
│   └── keda-crds-scaledjobs.yaml   # scaledjobs CRD 1개 (662KB, 별도 분리)
├── helm/
│   ├── install.sh                  # OCI 방식 Helm 설치 스크립트
│   └── values.yaml                 # Harbor 이미지 + nodeSelector 설정
└── manifests/
    └── rbac/
        ├── 10_keda_api_rbac.yaml   # ClusterRole + Binding (API 연동 권한)
        └── 20_keda_api_secret.yaml # keda-operator SA 토큰 Secret

정리하면 KEDA는 크게 세 갈래로 구성했습니다.

crds/ — CRD는 Helm에서 빼내 클러스터에서 추출한 yaml로 별도 관리 (섹션 4)
helm/ — KEDA 본체는 Helm OCI 방식으로 설치 (섹션 3)
manifests/rbac/ — 외부 모듈에서 K8s API로 KEDA 리소스를 조회하기 위한 RBAC + Secret 구성 (섹션 7)

참고: maxReplicaCount:4 같은 스케일 값은 KEDA 설치 디렉토리(services/keda/)가 아니라, Airflow Worker를 대상으로 하는 ScaledObject 리소스에 들어갑니다.

ScaledObject는 스케일 대상(Airflow)과 함께 두는 것이 관리상 자연스러워, services/airflow/쪽에 위치합니다. 즉 "KEDA 엔진"과 "스케일 규칙(ScaledObject)"의 경로가 분리되어 있는 구조입니다.

2. 환경 준비 - 이미지·차트 소스 정하기

KEDA는 공식 Helm 저장소와 컨테이너 이미지를 제공하므로,
기본적으로는 공식 소스에서 바로 받아 설치하는 것이 가장 간단합니다.

따라 하시는 분들은 별도 레지스트리 없이 아래 공식 소스만으로 충분합니다.

# 공식 Helm 저장소 (KEDA)
helm repo add kedacore https://kedacore.github.io/charts
helm repo update

# 공식 이미지 (ghcr.io)
ghcr.io/kedacore/keda:2.19.0
ghcr.io/kedacore/keda-metrics-apiserver:2.19.0
ghcr.io/kedacore/keda-admission-webhooks:2.19.0

다만 글쓴이는 이미지를 사내 Harbor로 미러링해 관리하고 있어,
이 글의 이후 예시는 Harbor 기준으로 작성돼 있습니다.

버전 고정·보안 스캔·내부 배포 일관성 측면에서 유리해서 택한 방식이고,
공식 소스를 쓰신다면 뒤에 나오는 harbor.local/... 경로만 위 공식 경로로 바꿔 읽으시면 됩니다.

먼저 K8s 버전과 KEDA 호환성부터 확인했습니다.

K8s 버전: v1.30.14 → KEDA 2.19.0 호환 확인
특정 worker 노드에 keda.role=keda 레이블 추가 (KEDA Pod 전용 배치)

글쓴이 환경 기준으로는, 공식 이미지·차트를 사내 Harbor로 옮겨(mirror) 아래처럼 두고 사용합니다.

# Helm Chart (OCI 형식으로 push)
harbor.local/helm-chart/keda:2.19.0

# 이미지 3종 (ghcr.io → Harbor)
harbor.local/library/keda/keda:2.19.0
harbor.local/library/keda/keda-metrics-apiserver:2.19.0
harbor.local/library/keda/keda-admission-webhooks:2.19.0

즉, 여기서 확인할 수 있는 핵심은

KEDA 이미지·차트는 공식 소스에서 바로 받아도 되고, 레지스트리를 사내에서 운영한다면 Harbor 등으로 미러링해 내부 경로만 바라보게 통일할 수도 있다는 점입니다.

3. Helm 설정 - values.yaml

Harbor 이미지를 바라보도록 하고,

keda.role=keda 노드에만 배치되도록 nodeSelector를 지정한 yaml입니다.

operator:
  nodeSelector:
    keda.role: keda
  image:
    registry: harbor.local
    repository: library/keda/keda
    tag: "2.19.0"

metricsServer:
  nodeSelector:
    keda.role: keda
  image:
    registry: harbor.local
    repository: library/keda/keda-metrics-apiserver
    tag: "2.19.0"

webhooks:
  nodeSelector:
    keda.role: keda
  image:
    registry: harbor.local
    repository: library/keda/keda-admission-webhooks
    tag: "2.19.0"

logging:
  operator:
    level: info
  metricServer:
    level: 0
  webhooks:
    level: info

crds:
  install: false

참고: crds.install: false가 핵심 포인트입니다.
KEDA Helm Chart는 기본적으로 CRD를 함께 설치하지만, 포스팅 작성할 때는 CRD를 ArgoCD로 별도 관리하기 위해 여기서 비활성화했습니다. 이유는 4·5번 섹션에서 이어집니다.

설치 스크립트는 OCI 레지스트리에서 차트를 가져오도록 구성했습니다.

#!/bin/bash

NAMESPACE=keda
RELEASE_NAME=keda
REGISTRY=harbor.local
CHART_VERSION=2.19.0

helm registry login $REGISTRY

helm upgrade --install $RELEASE_NAME \
  oci://$REGISTRY/helm-chart/keda \
  --version $CHART_VERSION \
  --namespace $NAMESPACE \
  --create-namespace \
  -f values.yaml

4. CRD 설치 - 클러스터에서 추출해 GitOps로 이관하기

앞서 values.yaml에서 crds.install: false로 CRD를 Helm 설치 대상에서 뺐습니다.
목적은 CRD를 Operator 라이프사이클과 분리해 Git + ArgoCD로 독립 관리하기 위함입니다.

Helm이 CRD까지 함께 관리하면

차트를 업그레이드·삭제할 때 CRD가 영향을 받을 수 있고,
sync-wave로 기동 순서를 제어하기도 어렵기 때문입니다.

방식은 이렇습니다.

글쓴이 환경은 KEDA가 이미 Helm으로 한 번 설치돼 CRD가 클러스터에 등록된 상태였습니다.

그래서 신규로 CRD yaml을 어디선가 받아오는 대신,
클러스터에 이미 떠 있는 CRD를 kubectl로 그대로 추출해 Git 저장소에 올리고,
이후부터는 Helm이 아닌 ArgoCD가 이 CRD를 관리하도록 소유권을 넘겼습니다.

"이미 잘 돌던 리소스를 그대로 Git으로 역이관"하니,

외부에서 새로 받아온 매니페스트와의 버전·필드 불일치 걱정 없이 깔끔했습니다.

참고(순서 정리):
① 최초 1회 Helm으로 CRD 포함 설치(crds.install: true 또는 --include-crds)
② 클러스터에서 CRD 추출·정제 후 Git 커밋
③ crds.install: false로 전환해 Helm에서 CRD를 떼어냄
④ 이후 CRD 소유권은 ArgoCD가 전담. 이 글의 values.yaml(섹션 3)은 ③ 이후 상태 기준입니다. 완전 신규(그린필드) 구축이라면, 클러스터 추출 대신 helm template --include-crds로 순수 yaml을 렌더링해 Git에 올리는 방법도 동일하게 가능합니다.

Step 1. 클러스터에서 KEDA CRD 목록 확인

kubectl get crd | grep keda.sh

cloudeventsources.eventing.keda.sh
clustercloudeventsources.eventing.keda.sh
clustertriggerauthentications.keda.sh
scaledjobs.keda.sh
scaledobjects.keda.sh
triggerauthentications.keda.sh

Step 2. scaledjobs를 제외한 CRD 5개 추출

for crd in \
  cloudeventsources.eventing.keda.sh \
  clustercloudeventsources.eventing.keda.sh \
  clustertriggerauthentications.keda.sh \
  scaledobjects.keda.sh \
  triggerauthentications.keda.sh; do
    kubectl get crd $crd -o yaml >> keda-crds-only.yaml
    echo "---" >> keda-crds-only.yaml
done

Step 3. scaledjobs CRD 단독 추출

# scaledjobs는 662KB로 용량이 커서 ArgoCD 적용 실패 → 별도 파일로 분리
kubectl get crd scaledjobs.keda.sh -o yaml > keda-crds-scaledjobs.yaml

Step 4. 런타임 필드 정제 (중요)

kubectl get -o yaml로 뽑은 CRD에는 클러스터가 실행 중에 붙인 런타임 메타데이터가 섞여 있습니다.
이걸 그대로 Git에 올리면 ArgoCD가 계속 OutOfSync로 감지하거나 적용에 실패하므로,
아래 필드들을 제거해 "선언적 스펙"만 남겨야 합니다.

metadata.annotations의 kubectl.kubernetes.io/last-applied-configuration
metadata.managedFields
metadata.resourceVersion, metadata.uid, metadata.generation, metadata.creationTimestamp
status 블록 전체

가장 간편한 건 kubectl-neat(krew 플러그인)로, 추출과 동시에 런타임 필드를 알아서 걷어내 줍니다.

# 방법 A) kubectl-neat 사용 (권장) — 추출과 동시에 정제
kubectl get crd scaledjobs.keda.sh -o yaml | kubectl neat > keda-crds-scaledjobs.yaml

# krew/neat 설치가 어려운 환경이라면, --show-managed-fields=false로 managedFields만이라도 제외
kubectl get crd scaledjobs.keda.sh -o yaml --show-managed-fields=false > keda-crds-scaledjobs.yaml

kubectl-neat 없이 yq로 직접 정제한다면, keda-crds-only.yaml은 ---로 이어진
멀티도큐먼트(5개 문서)라는 점에 주의해야 합니다.

일반 yq eval ... -i는 첫 문서만 처리될 수 있어
eval-all로 모든 문서를 순회해야 합니다.

# 방법 B) yq로 정제 — eval-all로 멀티도큐먼트 전체 순회
yq eval-all '
  del(.metadata.annotations."kubectl.kubernetes.io/last-applied-configuration") |
  del(.metadata.managedFields) |
  del(.metadata.resourceVersion) |
  del(.metadata.uid) |
  del(.metadata.generation) |
  del(.metadata.creationTimestamp) |
  del(.status)
' -i keda-crds-only.yaml

# scaledjobs 단일 파일도 동일하게 정제
yq eval-all '
  del(.metadata.annotations."kubectl.kubernetes.io/last-applied-configuration") |
  del(.metadata.managedFields) |
  del(.metadata.resourceVersion) |
  del(.metadata.uid) |
  del(.metadata.generation) |
  del(.metadata.creationTimestamp) |
  del(.status)
' -i keda-crds-scaledjobs.yaml

참고: 정제와 ServerSideApply는 역할이 다릅니다.
정제(Step 4)는 Git에 올라가는 소스 파일을 깨끗하게 만드는 작업이고(OutOfSync 방지),
뒤 섹션 5의 ServerSideApply=true는 ArgoCD가 apply 하는 시점에 last-applied-configuration 어노테이션으로 스펙 전체를 다시 써넣지 않게 하는 장치입니다.

하나는 소스 정리, 하나는 적용 방식이므로, 둘 다 있어야 662KB scaledjobs가 안정적으로 처리됩니다.

결과적으로 CRD 파일은 두 개로 나뉘었습니다.

keda-crds-only.yaml — CRD 5개 (cloudeventsources, clustercloudeventsources, clustertriggerauthentications, scaledobjects, triggerauthentications)
keda-crds-scaledjobs.yaml — scaledjobs CRD 1개 (용량 이슈로 별도 분리)

⚠️ 주의: scaledjobs CRD는 파일 크기가 662KB에 달합니다.
특히 last-applied-configuration 어노테이션은 CRD 스펙 전체를 문자열로 담기 때문에, 이걸 정제하지 않으면 이 어노테이션만으로도 Kubernetes의 어노테이션 크기 제한(262144 B)을 넘겨 적용에 실패합니다.

Step 4의 정제와, 뒤에서 다룰 ServerSideApply=true를 함께 써야 662KB CRD가 안정적으로 적용됩니다.

즉, 여기서 확인할 수 있는 핵심은

CRD는 Helm 관리에서 떼어내 클러스터에서 추출한 순수 선언 yaml로 Git에 두되,

last-applied-configuration 같은 런타임 필드는 반드시 정제하고, 용량이 큰 CRD는 쪼개야 한다는 점입니다.

설치 후 CRD 6개가 정상 등록됐는지 확인했습니다.

cloudeventsources.eventing.keda.sh
clustercloudeventsources.eventing.keda.sh
clustertriggerauthentications.keda.sh
scaledjobs.keda.sh
scaledobjects.keda.sh
triggerauthentications.keda.sh

5. ArogCD App 등록 - sync-wave로 기동 순서 제어

이제 앞서 준비한 KEDA를 이전 포스팅에서 구축한 ArgoCD에서 App으로 관리할 수 있게 설정합니다.

지난 글에서 ArgoCD를 App of Apps 패턴으로 올려뒀으니,

KEDA도 그 아래에 Application으로 등록해 GitOps 흐름에 편입시키는 것이죠.

여기가 이번 설치에서 가장 중요한 부분입니다.
KEDA Operator는 기동 시점에 CRD가 이미 존재해야 정상 동작합니다.
CRD보다 Operator가 먼저 뜨면 CrashLoopBackOff에 빠집니다.

그래서 KEDA를 3개의 ArgoCD Application으로 쪼개고, sync-wave로 순서를 명시적으로 갈랐습니다.

gitops/apps/keda/
├── keda_crds.yaml   (sync-wave: 130)  → CRD 먼저
├── keda_helm.yaml   (sync-wave: 131)  → Operator 나중
└── keda_rbac.yaml   (sync-wave: 132)  → RBAC 마지막 (namespace 생성 후)

참고: sync-wave 숫자가 낮을수록 먼저 적용됩니다.
CRD(130) → Helm(131) → RBAC(132) 순서로 배치해서 "CRD가 완전히 준비된 뒤 Operator가 기동 되고, namespace/SA가 생긴 뒤 RBAC이 붙도록" 보장한 것입니다.

① keda_crds — CRD 먼저 (wave 130)

CRD는 services/keda/crds 디렉토리를 통째로(recurse: true) 적용합니다.
662KB짜리 scaledjobs 대응을 위해 ServerSideApply=true가 핵심입니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: keda-crds
  namespace: argocd
  annotations:
    argocd.argoproj.io/sync-wave: "130"
spec:
  project: default
  sources:
    - repoURL: 'http://://data-platform.git'
      targetRevision: main
      path: services/keda/crds
      directory:
        recurse: true
  destination:
    server: '<https://kubernetes.default.svc>'
    namespace: keda
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true      # 662KB scaledjobs 어노테이션 제한 회피

⚠️ 주의: ServerSideApply=true는 섹션 4 정제와 짝을 이루는 적용 시점의 안전장치입니다.

정제(Step 4)로 소스 파일에서 어노테이션을 걷어내도,
ArgoCD가 client-side apply로 붙이면 apply 과정에서 last-applied-configuration에 스펙 전체를 다시 써넣습니다.

ServerSideApply를 켜면 이 어노테이션을 아예 만들지 않고 서버 측에서 필드를 병합하므로,
662KB scaledjobs처럼 큰 CRD도 어노테이션 크기 제한에 걸리지 않고 안정적으로 적용됩니다.

즉 "파일 분리(섹션 4) + 소스 정제(Step 4) + ServerSideApply(적용)" 세 겹이 함께 작동합니다.

② keda_helm — Operator (wave 131, multi-source)

KEDA 본체는

Harbor OCI 차트 + Git values.yaml을 분리 참조하는 multi-source 패턴으로 설치합니다.
차트는 Harbor에서, 설정값은 Git 저장소에서 각각 가져와 조합하는 방식입니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: keda-helm
  namespace: argocd
  annotations:
    argocd.argoproj.io/sync-wave: "131"
spec:
  project: default
  sources:
    - repoURL: 'harbor.local/helm-chart'   # Harbor OCI 레지스트리의 차트
      chart: keda
      targetRevision: 2.19.0
      helm:
        valueFiles:
          - $values/services/keda/helm/values.yaml   # ↓ Git values 참조
    - repoURL: 'http://://data-platform.git'
      targetRevision: main
      ref: values                          # $values 로 위에서 참조됨
  destination:
    server: '<https://kubernetes.default.svc>'
    namespace: keda
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      - ServerSideApply=true

참고: multi-source의 ref: values + $values/... 조합이 포인트입니다.
"차트는 Harbor에, values.yaml은 Git에" 두면서도 하나의 Application으로 묶을 수 있어, 차트 버전과 설정을 각자의 저장소에서 독립적으로 관리할 수 있습니다.

③ keda_rbac — API 연동용 RBAC (wave 132)

앞서 만든 services/keda/manifests/rbac를 마지막 wave로 적용합니다.

namespace와 keda-operator ServiceAccount가

생성된 뒤에 붙어야 하므로 132로 뒤에 뒀고, 타이밍 이슈에 대비해 retry를 넣었습니다.

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: keda-rbac
  namespace: argocd
  annotations:
    argocd.argoproj.io/sync-wave: "132"   # namespace 생성 후 rbac
spec:
  project: default
  source:
    repoURL: http://://data-platform.git
    targetRevision: main
    path: services/keda/manifests/rbac
  destination:
    server: <https://kubernetes.default.svc>
    namespace: keda
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    retry:
      limit: 5
      backoff:
        duration: 15s
        factor: 2
        maxDuration: 2m
    syncOptions:
      - CreateNamespace=true

3개 App이 모두 Healthy + Synced 상태가 되고,
Pod 3개(keda-operator, keda-admission-webhooks, keda-operator-metrics-apiserver)가 Running이면 설치 완료입니다.

즉, 여기서 확인할 수 있는 핵심은

CRD·Operator·RBAC를 한 App에 묶지 말고 3개로 쪼갠 뒤

sync-wave(130→131→132)로 순서를 강제해야,

CrashLoop과 SA 미존재 같은 순서 의존 문제를 피할 수 있다는 점입니다.

6. 설치 트러블슈팅 정리

글쓴이도 여러 착오 끝에 구축할 수 있었는데, 오는 과정에서 마주친 이슈들을 표로 정리했습니다.

문제	원인	해결
keda-operator CrashLoopBackOff	CRD보다 Operator가 먼저 기동	CRD App(wave 130) → Helm App(wave 131) 순서 분리
scaledjobs CRD 미설치	파일 크기 662KB로 ArgoCD 적용 실패	별도 파일로 분리 + ServerSideApply=true 적용
CRD 적용 후 계속 OutOfSync	kubectl get -o yaml 추출물에 런타임 필드(managedFields, resourceVersion 등) 잔존	Step 4 정제로 런타임 필드 제거 후 커밋
scaledjobs 어노테이션 제한 초과	last-applied-configuration에 CRD 스펙 전체가 문자열로 포함	해당 어노테이션 제거 + ServerSideApply=true
RBAC 적용 시 SA 미존재 에러	keda-operator SA 생성 전 RBAC 먼저 적용	RBAC을 wave 132로 뒤에 두고 retry 설정

7. 외부 모듈에서 KEDA 리소스를 조회하기 위한 RBAC·Secret 구성

앞선 섹션들에서 KEDA 리소스는 전부 kubectl이나 ArgoCD를 통해 다뤘습니다.

그런데 플랫폼을 운영하다 보면,

kubectl이 아니라 별도 모듈(백오피스·대시보드·운영 자동화 등)에서 KEDA 리소스 상태를 직접 조회하고 싶은 상황이 생깁니다.

예를 들면,

사내 백오피스/대시보드에서 현재 ScaledObject 목록과 스케일 상태를 보여주고 싶을 때
운영 자동화 모듈이 특정 조건에서 ScaledObject 상태를 확인하고 싶을 때
CI 파이프라인에서 KEDA 리소스 상태를 점검하고 싶을 때

Kubernetes API 서버는 모든 리소스를 API 엔드포인트로 노출하므로,

모듈이 kubectl 없이 HTTP 요청 + 토큰만으로 KEDA 리소스(scaledobjects 등)를 조회할 수 있습니다.

문제는 인증/인가입니다.

아무 토큰이나 API 서버에 보낸다고 되는 게 아니라,

"이 토큰이 keda.sh 리소스에 접근할 권한이 있는가"를 RBAC으로 열어주고,

그 권한을 담은 토큰(Secret)을 발급해줘야 합니다.

그래서 이번에는

그 연동에 앞서 필요한 전용 RBAC + SA 토큰(Secret)을 추가로 구성해봤습니다.

아직 실제 모듈 연동까지 붙인 단계는 아니고,

"모듈이 붙으면 쓸 권한·토큰을 미리 열어두고,

그게 의도대로 동작하는지 검증"하는 데까지가 이번 범위입니다.

OSS 데이터 플랫폼 리소스를

API로 연동하려는 분들도 아래 패턴을 그대로 적용하면 됩니다.

파일은 services/keda/manifests/rbac/ 아래 두 개, ArgoCD keda-rbac App(wave 132)으로 배포됩니다.

① ClusterRole + Binding — 권한 열기

keda.sh API 그룹의 리소스에 대한 권한을 정의하고,

keda-operator ServiceAccount에 바인딩합니다.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: keda-api-reader
rules:
  - apiGroups: ["keda.sh"]
    resources: ["scaledobjects", "scaledjobs", "triggerauthentications", "clustertriggerauthentications"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: keda-api-reader-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: keda-api-reader
subjects:
  - kind: ServiceAccount
    name: keda-operator
    namespace: keda

⚠️ 주의: 예시는 create/update/patch/delete까지 전부 열려 있어 KEDA 리소스를 변경할 수 있는 강한 권한입니다.

조회만 필요하다면 verbs를 ["get", "list", "watch"]로 최소화하세요.
최소 권한 원칙(least privilege)이 보안의 기본입니다.

② SA 토큰 Secret — 인증 수단 발급

keda-operator ServiceAccount에 대한 장기 토큰(long-lived token) 을 발급받기 위한 Secret입니다.

apiVersion: v1
kind: Secret
metadata:
  name: keda-operator-token
  namespace: keda
  annotations:
    kubernetes.io/service-account.name: keda-operator
type: kubernetes.io/service-account-token

③ 토큰 꺼내기

발급된 토큰과 API 서버 주소를 확인합니다.

# SA 토큰 추출
TOKEN=$(kubectl get secret keda-operator-token -n keda \
  -o jsonpath='{.data.token}' | base64 -d)

# API 서버 주소 확인
APISERVER=$(kubectl config view --minify \
  -o jsonpath='{.clusters[0].cluster.server}')

echo $APISERVER   # 예: https://<APISERVER_HOST>:6443

④ 권한이 제대로 열렸는지 검증 (Postman)

모듈을 붙이기 전에,

발급한 RBAC·토큰으로 실제 조회가 되는지부터 확인해 봅니다.

모듈 코드를 짜기 전에 권한 설정만 먼저 검증해 두면,

나중에 연동할 때 "권한 문제인지 코드 문제인지" 헷갈릴 일이 줄어듭니다.

Postman으로 확인한 설정은 다음과 같습니다.

Method / URL

GET https://<APISERVER_HOST>:6443/apis/keda.sh/v1alpha1/namespaces/airflow/scaledobjects

Authorization 탭 → Type: Bearer Token → Token 칸에 위에서 꺼낸 $TOKEN 붙여 넣기
Settings → 사내 클러스터가 자체 서명 인증서를 쓰면 SSL certificate verification을 끄거나, CA 인증서를 등록

정상이라면 airflow 네임스페이스의 ScaledObject 목록이 JSON으로 돌아옵니다.

{
  "apiVersion": "keda.sh/v1alpha1",
  "kind": "ScaledObjectList",
  "items": [
    {
      "metadata": { "name": "airflow-worker-scaler", "namespace": "airflow" },
      "spec": { "minReplicaCount": 2, "maxReplicaCount": 19 }
    }
  ]
}

curl로도 동일하게 확인할 수 있습니다.

실제 모듈에서 호출할 때도 결국 이 형태(엔드포인트 + Bearer 토큰)를 그대로 쓰게 됩니다.

curl -sk -H "Authorization: Bearer $TOKEN" \
  "$APISERVER/apis/keda.sh/v1alpha1/namespaces/airflow/scaledobjects" | jq .

즉, 여기서 확인할 수 있는 핵심은

K8s API 서버가 모든 리소스를 API로 노출하므로, 외부 모듈이 KEDA 리소스를 조회하려면 전용 RBAC + SA 토큰(Secret)만 미리 열어두면 되고, 연동 전에 Postman/curl로 그 권한이 제대로 동작하는지 검증해 둘 수 있다는 점입니다.

그리고 그 편리함만큼 권한 최소화와 토큰 관리가 보안의 핵심이 됩니다.

마무리

이번 글에서는 KEDA를 Harbor + ArgoCD 기반으로 구축하는 과정을 정리해 봤습니다.

정리하면,

CRD는 Helm 관리에서 떼어내 클러스터에서 추출한 뒤 런타임 필드를 정제해 Git에 두고, 용량 큰 CRD(scaledjobs 662KB)는 쪼갠 뒤 ServerSideApply로 적용한다
CRD·Operator·RBAC를 3개 App으로 나누고 sync-wave(130→131→132)로 순서를 강제해야 CrashLoop·SA 미존재를 피한다
외부 모듈에서 KEDA 리소스를 조회하려면 전용 RBAC + SA 토큰(Secret)을 미리 열어두면 되고, 연동 전 Postman/curl로 권한이 제대로 동작하는지 검증해 둘 수 있다

정도가 되겠습니다.

다음 글에서는 이렇게 설치한 KEDA를 실제로 활용해서,
Airflow Celery Worker를 Redis + Prometheus 멀티 트리거로 오토스케일링하는 과정을 다뤄보려고 합니다.

궁금한 점이나 추가로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요

『생각이 너무 많은 어른들을 위한 심리학』 리뷰 | 생각을 멈출 순 없어도 바라볼 순 있다

환이s — Tue, 7 Jul 2026 16:13:40 +0900

시작하기 전에

그날은 읽던 책을 다 끝내서

새 책을 한 권 사러 교보문고에 갔다.

목적이 있는 걸음이었다.

사려던 책은 따로 있었고,

그 앞으로 곧장 가던 길이었다.

그런데 매대를 지나치다

제목 하나가 눈에 걸렸다.

『생각이 너무 많은 어른들을 위한 심리학』

생각이 너무 많은 어른.

그 한 줄이

괜히 발이 멈췄다.

그 자리에 선 채로

몇 장을 넘겨봤다.

몇 문장 읽지 않았는데

이상하게 계속 읽고 싶어져서,

원래 사려던 책과 함께

이 책도 집어 들고 나왔다.

생각이 많은 게 나쁜 거냐고?

집에 돌아와

의자에 앉아 책을 펼쳤다.

읽다 보니

문득 스무 살의 내가 스쳐 지나갔다.

고향을 떠나

낯선 도시에서 혼자 살기 시작했던 그때.

전공은 진작에 접어두고

해보고 싶은 건 다 해봐야 직성이 풀렸다.

이것도 궁금하고

저것도 해보고 싶어서

한자리에 오래 머무는 법이 없었다.

그때마다 나는

머릿속으로 수십 번을 굴렸다.

이게 맞을까,

지금 이걸 시작해도 될까,

남들은 벌써 자리를 잡았는데

나만 늦은 건 아닐까.

책은 조용히 짚어준다.

문제는 생각의 양이 아니라

그 생각이 흘러가는 방향이라고.

생각이 많아질수록

긍정적인 생각보다

부정적인 생각을 더 많이 하게 되고,

한번 시작하면

좀처럼 멈출 줄을 모른다는 것.

가장 오래 마음에 남았던 이야기

페이지를 넘기다

'슬플 때는 굳이 강한 척하지 말 것'에서 손이 멈췄다.

저자는 말한다.

우리는 어릴 때부터

울면 나약한 사람이라고 배우며 자라서,

어른이 되면

아파도 괜찮은 척,

잘 견디는 척하게 된다고.

그럴수록

마음의 상처만 깊어질 뿐이라고.

그 문장을 읽는데

문득 영등포가 떠올랐다.

대전으로 내려오기 직전까지

마지막으로 자취하던 동네였다.

그 시절 나는

혼자 참 많이도 돌아다녔다.

특별한 목적도 없이

거리를 걷고,

지나가는 사람들을 이유 없이 구경하고,

가끔은 한강에 나가

혼자 맥주 한 캔을 들고

아무 생각 없이 멍하니 앉아 있곤 했다.

그때는 그게

자유로운 거라고 생각했다.

그런데 지금 와서 보면

나는 그냥

혼자 견디고 있었던 것 같다.

힘들다는 말을

어떻게 꺼내는지 몰라서,

그저 혼자 걷고

혼자 마시며

괜찮은 척을 했다.

저자는 슬픔은

관계 속에서 태어난다고 말한다.

그러니 혼자 삼키지 말고

곁에 있는 사람과 나누라고.

그 대목에서

한강에 혼자 앉아 있던 서른 살 전의 내가,

조금 안쓰러워졌다.

읽고 나서 드는 솔직한 생각

마지막 장을 덮었을 때는

이미 창밖이 어둑해져 있었다.

서점에는 잠깐 훑고 나왔을 뿐인데

어느새 한 권을 다 읽어버린 셈이었다.

물론 오래된 습관이

곧바로 바뀌진 않는다.

스무 살부터 십 년을

혼자 견디는 데 익숙해진 사람이

책 한 권으로 달라질 리 없다는 걸 안다.

다만 하나는 달라졌다.

이제는 힘들 때

'괜찮은 척'을 하려는 나를

한 번쯤 멈춰 세우게 됐다는 것.

멈추진 못해도

그런 나를 바라볼 수는 있게 됐다.

늘 새로운 곳을 향해 달리던 내가

서른이 되어서야

한자리에 정착한 것처럼,

마음을 꺼내는 법도

이제는 조금씩

배워가는 중이다.

이런 분께 권하고 싶다

생각이 너무 많아서

매번 시작 앞에서 머뭇거리는 사람,

힘들어도 괜찮은 척

혼자 삼키는 데 익숙해진 사람,

머릿속이 늘

쉬지 못하고 돌아가는 것 같은 사람.

그런 분들껜

서점에서 잠깐이라도

이 책을 펼쳐보라고 권하고 싶다.

나처럼

그 자리에서 발이 멈출지도 모르니까.

마무리하며

원래 사려던 책은

아직도 책장에 그대로 꽂혀 있다.

정작 그날 나를 붙잡은 건

계획에도 없던 이 책이었다.

생각을 없애주는 책은 아니다.

대신 이렇게 묻는다.

그 많은 생각을

혼자 끌어안고 있을 필요가 있냐고.

여전히 나는 생각이 많은 사람이지만,

새로운 곳에 정착한 지금,

이제는 그 생각을

조금씩 꺼내놓으며

살아보려 한다.

[Data Platform] ArgoCD GitOps 운영 가이드(App of Apps 패턴으로 플랫폼 관리)

환이s — Tue, 7 Jul 2026 10:43:18 +0900

Intro

안녕하세요. 환이s입니다

지난 글에서는 데이터 레이크하우스 플랫폼의

여덟 번째 스택으로 ArgoCD를 Kubernetes 위에 구축하고

Harbor private registry와 연동하는 과정을 정리해 봤습니다.

이번 글에서는

ArgoCD의 App of Apps 패턴을 활용해서

Kafka, Airflow, Spark 등 플랫폼 전체 스택을 GitOps로 관리하는 방법을 정리해보려고 합니다.

ArgoCD를 설치했다고 해서 GitOps가 완성된 것은 아닙니다.

어떤 패턴으로 앱을 관리할지 설계하는 것이 핵심입니다.

이번 글에서는

App of Apps 패턴의 개념과 왜 사용하는지
Git 저장소의 디렉토리 구조 설계 방법
Root Application 설정 방법
실제 앱 추가/삭제 워크플로우
Web UI에서 배포 상태를 확인하는 방법

까지 순서대로 확인해 보겠습니다.

1. App of Apps 패턴이란?

일반적인 ArgoCD 사용 방식은

앱마다 Application 리소스를 하나씩 직접 만드는 것입니다.

App of Apps는 "Application들을 관리하는 Application"을 두는 패턴입니다.

platform-root (Root Application)
  └── gitops/apps/platform/ 디렉토리를 감시
        ├── airflow.yaml    → platform-airflow (Application)
        ├── kafka.yaml      → platform-kafka (Application)
        ├── spark.yaml      → platform-spark (Application)
        ├── prometheus.yaml → platform-prometheus (Application)
        └── ...

앱을 추가하려면 gitops/apps/platform/ 에 yaml 파일 하나만 추가하면 됩니다.

ArgoCD가 자동으로 감지하고 배포합니다.

즉, 여기서 확인할 수 있는 핵심은

App of Apps 패턴에서는 Root Application 하나만 수동으로 배포하면,

이후 모든 앱은 Git에 파일을 추가하는 것만으로 자동 배포된다는 점입니다.

2. 디렉토리 구조

이번 구축에서 사용하는 디렉토리 구조는 아래와 같습니다.

data-platform/
├── bootstrap/                              # 수동으로 한 번만 배포하는 리소스
│   └── 03_argocd/
│       └── manifests/
│           ├── 30_root_app.yaml            # platform-root Application
│           └── 35_webapps_root.yaml        # webapps-root Application
│
└── gitops/                                 # ArgoCD가 지속적으로 감시하는 영역
    └── apps/
        ├── platform/                       # platform-root가 감시하는 디렉토리
        │   ├── airflow.yaml
        │   ├── prometheus.yaml
        │   ├── spark.yaml
        │   ├── kafka.yaml
        │   ├── ...
        │
        ├── airflow/                        # 각 앱의 실제 배포 리소스
        ├── prometheus/
        ├── spark/
        ├── kafka/
        └── ...

Root Application은 bootstrap/ 에서 한 번만 배포합니다.

이후 앱 추가/수정은 gitops/apps/platform/ 을 Git으로 관리합니다.

즉, 여기서 확인할 수 있는 핵심은

bootstrap/ 은 사람이 직접 한 번 실행하는 영역이고,

gitops/ 는 ArgoCD가 자동으로 감시하고 동기화하는 영역이라는 점입니다.

3. Root Application 설정

✔️ platform-root

# bootstrap/03_argocd/manifests/30_root_app.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: platform-root
  namespace: argocd
spec:
  project: default

  source:
    repoURL: http://<GIT_SERVER>/<ORG>/<REPO>.git
    targetRevision: main
    path: gitops/apps/platform
    directory:
      recurse: true   # 하위 디렉토리까지 재귀 탐색

  destination:
    server: https://kubernetes.default.svc
    namespace: argocd

  syncPolicy:
    automated:
      prune: true       # Git에서 삭제된 리소스를 클러스터에서도 삭제
      selfHeal: true    # 클러스터 상태가 Git과 달라지면 자동 복원

    syncOptions:
      - CreateNamespace=true

핵심 설정 설명은 아래와 같습니다.

설정	설명
directory.recurse: true	디렉토리 내 모든 yaml을 재귀적으로 읽음
automated.prune: true	Git에서 yaml 삭제 시 클러스터 리소스도 삭제
automated.selfHeal: true	누군가 kubectl로 직접 수정해도 Git 상태로 자동 복원
CreateNamespace=true	네임스페이스가 없으면 자동 생성

⚠️ prune: true와 selfHeal: true는 강력한 설정입니다.
Git이 항상 올바른 상태여야 하며, 실수로 파일을 삭제하면 클러스터에서도 리소스가 삭제됩니다.

4. 각 앱 Application 설정

gitops/apps/platform/ 아래의 각 yaml은 개별 앱의 ArgoCD Application을 정의합니다.

✔️ kafka.yaml 예시

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: platform-kafka
  namespace: argocd
spec:
  project: default
  source:
    repoURL: http://<GIT_SERVER>/<ORG>/<REPO>.git
    targetRevision: main
    path: gitops/apps/kafka        # 실제 kafka 배포 yaml이 있는 경로
    directory:
      recurse: true
  destination:
    server: https://kubernetes.default.svc
    namespace: argocd
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

모든 앱 yaml이 동일한 구조를 가집니다.

name과 path만 앱마다 다릅니다.

참고 : destination.namespace: argocd는 Applino 리소스 자체가 생성되는 네임스페이스입니다.

실제 앱(Kafka, Airflow 등)이 배포되는 네임스페이스는 각 앱의 배포 yaml 내부에서 별도로 정의됩니다.

CreateNamespace=true 옵션으로 해당 네임스페이스가 없으면 자동 생성됩니다.

5. 실제 배포 흐름

✔️ 새 앱 추가하기

gitops/apps/platform/ 에 새 yaml 파일 작성
Git commit & push
ArgoCD가 변경 감지(기본 polling 3분)
자동으로 새 Application 생성 및 배포

# 예시: OpenSearch 추가
vim gitops/apps/platform/opensearch.yaml
git add .
git commit -m "feat: add opensearch application"
git push origin main

✔️ 앱 삭제하기

# yaml 파일 삭제
git rm gitops/apps/platform/opensearch.yaml
git commit -m "chore: remove opensearch application"
git push origin main
# prune: true 설정으로 ArgoCD가 자동으로 클러스터에서도 삭제

✔️ 롤백하기

# 이전 커밋으로 되돌리기
git revert HEAD
git push origin main
# ArgoCD가 자동으로 이전 상태로 복원

즉, 여기서 확인할 수 있는 핵심은

모든 배포/삭제/롤백이 git push 하나로 완결된다는 점입니다.

kubectl로 직접 수정하더라도 ArgoCD가 Git 상태로 자동 복원합니다.

6. Web UI에서 확인하기

Ingress 설정 URL로 접속 후 Applications 화면에서 상태를 확인합니다.

platform-root를 클릭하면 하위 Application 목록이 트리 형태로 표시됩니다.

✔️ Sync Status

상태	의미
Synced	Git과 클러스터 상태 일치
OutOfSync	Git과 클러스터 상태 불일치

✔️ Health Status

상태	의미
Healthy	모든 리소스 정상
Progressing	배포 진행 중
Degraded	이상 상태(Pod CrashLoop 등)
Missing	리소스가 클러스터에 없음

참고: OutOfSync 상태가 지속된다면 Git에 변경이 있는지, 또는 클러스터에 수동 변경이 있었는지 확인해 보세요. selfHeal: true 설정이 있다면 수 분 내로 자동 복원됩니다.

마무리

이번 글에서는 App of Apps 패턴으로 데이터 플랫폼 전체를 GitOps 방식으로 관리하는 과정을 정리해 봤습니다.

정리하면,

App of Apps 패턴 → Root Application 하나가 나머지 모든 앱을 자동 관리
디렉토리 구조 → bootstrap/(수동 1회) vs gitops/(ArgoCD 자동 감시) 영역 분리
prune + selfHeal → Git 삭제 시 클러스터 자동 삭제, kubectl 수정 시 자동 복원
앱 추가 → yaml 파일 하나를 Git에 push 하는 것으로 완료
롤백 → git revert 하나로 이전 상태로 복원

라고 볼 수 있습니다.

특히 이번 구축에서 주의해야 할 포인트는

prune: true는 Git에서 파일을 실수로 삭제하면 클러스터 리소스도 삭제되므로 주의
Root Application은 bootstrap/에서 수동으로 한 번만 배포하고, 이후는 Git으로만 관리
앱별 yaml의 path는 실제 배포 리소스가 있는 경로를 정확히 지정해야 함

이 3가지였습니다.

이것으로 데이터 레이크하우스 플랫폼의 핵심 스택 구축 시리즈를 마무리합니다.

다음 포스팅부터는 플랫폼의 완성도를 높여주는 OSS들을 다뤄보려고 합니다.

Kafka, Spark, Trino 같은 핵심 스택을 더 안정적이고

효율적으로 운영하기 위한 오토스케일링, 시크릿 관리, 모니터링 고도화 등
플랫폼 운영 디테일을 잡아주는 도구들을 하나씩 정리해 나갈 예정입니다.

궁금한 점이나 추가로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요!

[Data Platform] ArgoCD 구축 가이드 (Helm + Private Registry + Ingress 구성)

환이s — Mon, 6 Jul 2026 10:55:56 +0900

Intro

안녕하세요. 환이s입니다

지난 글에서는 데이터 레이크하우스 플랫폼의

일곱 번째 스택으로 Superset을 Kubernetes 위에 구축하고

Trino와 연동해서 Delta Lake 데이터를 시각화하는 과정을 정리해 봤습니다.

이번 글에서는 여덟 번째 스택,

ArgoCD를 Kubernetes 환경에 구축하고

플랫폼 전체를 GitOps 방식으로 관리하기 위한 기반을 구성하는 과정을 정리해보려고 합니다.

지금까지

Kafka → Spark → Delta Lake → Trino → Superset 까지 구축했다면,

이제 이 모든 스택을 코드로 관리하고 자동으로 배포하는 도구가 필요합니다.

그 역할을 담당하는 것이 바로 ArgoCD입니다.

이번 글에서는

Harbor private registry에서 이미지와 Helm Chart를 가져오는 방법
Helm으로 ArgoCD를 설치하는 방법
MetalLB + ingress-nginx + sslip.io로 Web UI에 접근하는 방법
Secret과 ConfigMap으로 저장소 인증, 계정, CRD health check를 구성하는 방법
설치 후 검증하는 방법

까지 순서대로 확인해 보겠습니다.

1. ArgoCD 아키텍처 개요

본격적인 설치에 앞서,

이번 구성의 전체 아키텍처를 먼저 이해하는 것이 중요합니다.

[웹 접근 경로]

브라우저
  ↓
argocd.192.168.2.240.sslip.io
  ↓ (MetalLB → ingress-nginx)
argocd-server:80

[GitOps 동기화 경로]

ArgoCD (application-controller)
  ↓ polling (3분 간격)
Git 저장소 (Gitea)
  ↓ 변경 감지 시
클러스터 자동 동기화

각 컴포넌트의 역할은 아래와 같습니다.

컴포넌트	역할
MetalLB	ingress-nginx에 External IP(192.168.2.240) 할당
ingress-nginx	sslip.io 도메인을 ArgoCD 서버로 라우팅
Harbor	Private 이미지 및 Helm Chart 레지스트리
ArgoCD	Git 저장소를 기반으로 클러스터 상태를 자동 동기화

즉, 여기서 확인할 수 있는 핵심은

ArgoCD는 Git 저장소를 단일 진실의 원천(Single Source of Truth)으로 삼아 클러스터 상태를 코드와 항상 일치시킨다는 점입니다.

2. 설치 순서

이번 구축에서 사용하는 디렉토리 구조는 아래와 같습니다.

bootstrap/
└── 03_argocd/
    ├── helm/
    │   ├── install.sh                      # 설치 스크립트
    │   └── values.yaml                     # Helm values
    └── manifests/
        ├── 10_ingress_argocd.yaml          # Ingress 설정
        ├── 20_repo_secret.yaml             # Git 저장소 인증 Secret
        ├── 30_root_app.yaml                # platform-root Application
        ├── 35_webapps_root.yaml            # webapps-root Application
        ├── 40_argocd_cm.yaml               # ConfigMap (계정, CephCluster health check)
        ├── 50_argocd_tls_certs_cm.yaml     # Harbor TLS 인증서 신뢰 설정
        ├── 60_harbor_repo_secret.yaml      # Harbor OCI 레지스트리 인증 Secret
        └── 70_argocd_secret.yaml           # RBAC 권한 설정

설치 순서는 아래와 같습니다.

values.yaml 작성 → Helm 설치 → manifests 적용 (Ingress, Secret, ConfigMap) → 설치 후 검증

3. values.yaml 설정

먼저 공식 이미지를 기준으로 기본 설정을 살펴보겠습니다.

global:
  image:
    repository: quay.io/argoproj/argocd
    tag: v3.3.4

redis:
  image:
    repository: redis
    tag: 7

dex:
  enabled: false   # SSO 인증관련 서비스 사용여부

server:
  service:
    type: NodePort
    nodePortHttp: 30010

configs:
  params:
    server.insecure: true       # ArgoCD 서버를 HTTP 모드로 실행

주요 설정 포인트는 아래와 같습니다.

설정	설명
dex.enabled: false	- LDAP/OAuth SSO를 쓰지 않는 경우 비활성화
server.insecure: true	- ArgoCD 서버가 HTTP로 동작. - TLS 없이 Ingress에서 직접 80 포트로 수신

글쓴이는 외부 인터넷이 차단된 온프레미스 환경에서
Harbor private registry를 운영하는 목적 기반으로 하고 있어,
아래와 같이 이미지 경로와 Helm Chart 레지스트리를 Harbor 기준으로 변경해서 사용하고 있습니다.

global:
  image:
    repository: harbor.local/library/argocd/argocd
    tag: v3.3.4

redis:
  image:
    repository: harbor.local/library/redis/redis
    tag: 7

dex:
  enabled: false   # SSO 인증관련 서비스 사용여부

server:
  service:
    type: NodePort
    nodePortHttp: 30010

configs:
  params:
    helm.oci.enabled: true      # OCI 형식 Helm 차트 사용
    server.insecure: true       # ArgoCD 서버를 HTTP 모드로 실행

repoServer:
  env:
    - name: HELM_EXPERIMENTAL_OCI
      value: "1"

  cm:
    url: http://argocd.192.168.2.240.sslip.io

  repositories:
    harbor-helm:
      url: harbor.local/helm-chart
      type: helm
      name: harbor

  tls:
    certificates:
      harbor.local: |
        -----BEGIN CERTIFICATE-----
        # Harbor CA 인증서 내용
        -----END CERTIFICATE-----

즉, 여기서 확인할 수 있는 핵심은

Git 저장소 인증과 Harbor OCI 레지스트리 인증은 values.yaml 외에 별도 Secret으로도 등록한다는 점입니다.

이 부분은 이후 섹션에서 하나씩 확인해 보겠습니다.

4. Helm 설치 스크립트

#!/bin/bash

set -e

NAMESPACE=argocd
CHART=oci://harbor.local/helm-chart/argo-cd
VERSION=9.4.14

echo "== namespace 생성 =="
kubectl create namespace $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -

echo "== harbor login =="
helm registry login harbor.local

echo "== argocd 설치 =="
helm upgrade --install argocd $CHART \
  --version $VERSION \
  -n $NAMESPACE \
  -f values.yaml

echo "== manifests 적용 =="
kubectl apply -f ../manifests/

echo "== 완료 =="

스크립트 구조 설명은 아래와 같습니다.

명령어	설명
--dry-run=client -o yaml \| kubectl apply -f -	namespace가 이미 존재해도 에러 없이 처리
helm registry login	Harbor OCI 레지스트리 인증
helm upgrade --install	없으면 설치, 있으면 업그레이드(idempotent)
kubectl apply -f ../manifests/	Secret, ConfigMap, Ingress 등 추가 리소스 일괄 적용

참고: set -e 옵션으로 중간에 에러가 발생하면 스크립트가 즉시 종료됩니다. 설치 실패 시 어느 단계에서 멈췄는지 확인하세요.

5. Ingress 설정

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: argocd
  namespace: argocd
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
    nginx.ingress.kubernetes.io/cors-allow-origin: "*"
    nginx.ingress.kubernetes.io/cors-allow-methods: "GET, POST, PUT, DELETE, OPTIONS"
    nginx.ingress.kubernetes.io/cors-allow-headers: "Authorization, Content-Type"
spec:
  ingressClassName: nginx
  rules:
  - host: argocd.192.168.2.240.sslip.io
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: argocd-server
            port:
              number: 80

sslip.io는

별도 DNS 설정 없이 IP가 포함된 도메인을 자동으로 해당 IP로 해석해주는 서비스 입니다.

참고: TLS 설정이 없기 때문에 브라우저에서 주의 요함이 표시될 수 있습니다. 내부망 구성에서는 HTTP로 운영하고, 운영 환경에서는 cert-manager로 인증서를 발급하는 것을 권장합니다.

6. Git 저장도 인증 Secret 설정

ArgoCD가 Gitea 저장소에 접근하기 위한 인증 정보를 Secret으로 등록합니다.

# 20_repo_secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: repo-data-platform
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
type: Opaque
stringData:
  url: http://192.168.2.8:37000/eluna/data-platform.git
  username: argocd
  password: <GITEA_ACCESS_TOKEN>

즉, 여기서 확인할 수 있는 핵심은

argocd.argoproj.io/secret-type: repository 라벨을 붙이면

ArgoCD가 이 Secret을 저장소 인증 정보로 자동 인식한다는 점입니다.

7. Helm Chart 레지스트리 인증 Secret 설정

공식 Helm 레지스트리(ArtifactHub 등 공인 레지스트리)를 사용하는 경우,

별도 Secret 없이 values.yaml의 configs.repositories에 직접 등록하면 됩니다.

# values.yaml - 공식 Helm 레지스트리 사용 시
configs:
  repositories:
    argo-helm:
      url: https://argoproj.github.io/argo-helm
      type: helm
      name: argo

인증이 필요한 private 레지스트리라면 Secret으로 등록합니다.

apiVersion: v1
kind: Secret
metadata:
  name: repo-private-helm
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: helm
  name: private-helm
  url: https://your-private-helm-repo
  username: <USERNAME>
  password: <PASSWORD>

글쓴이는 온프레미스 환경에서 Harbor를 OCI 레지스트리로 사용하고 있어, 아래와 같이 OCI 전용 Secret으로 등록합니다.

# 60_harbor_repo_secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: repo-harbor-oci
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: repository
stringData:
  type: helm
  name: harbor-oci
  url: harbor.local
  enableOCI: "true"
  username: admin
  password: <HARBOR_PASSWORD>

필드	설명
type: helm	Helm 레지스트리 타입으로 등록
enableOCI: "true"	OCI 프로토콜 사용 활성화
url : harbor.local	Harbor 도메인 (포트 없이 도메인만)

즉, 여기서 확인할 수 있는 핵심은

argocd.argoproj.io/secret-type: repository 라벨을 붙이면

ArgoCD가 이 Secret을 Helm 레지스트리 인증 정보로 자동 인식한다는 점입니다.

8. TLS 인증서 신뢰 설정

Let`s Encrypt나 공인 CA에서 발급한 인증서를 사용하는 경우,

ArgoCD가 기본적으로 신뢰하므로 별도 설정이 필요하지 않습니다,.

글쓴이는 사내 self-signed CA 인증서를 사용하고 있어, ArgoCD repo-server가 Harbor에 접근할 때 인증서를 신뢰하도록 아래와 같이 등록합니다.

# 50_argocd_tls_certs_cm.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-tls-certs-cm
  namespace: argocd
data:
  harbor.local: |
    -----BEGIN CERTIFICATE-----
    # Harbor CA 인증서 내용
    -----END CERTIFICATE-----

⚠️ 이 설정이 없으면 repo-server가 Harbor에서 Helm 차트를 pull할 때 아래와 같은 TLS 인증서 검증 오류가 발생합니다.

x509: certificate signed by unknown authority

즉, 여기서 확인할 수 있는 핵심은

공인 인증서 환경에서는 이 설정이 불필요하지만,

self-signed 인증서를 사용하는 경우 반드시 argocd-tls-certs-cm에 CA 인증서를 등록해야 한다는 점입니다.

9.ConfigMap 설정

# 40_argocd_cm.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-cm
  namespace: argocd
data:
  # API 토큰 발급용 계정 생성
  accounts.monitoring: apiKey

  # Rook-Ceph CephCluster 커스텀 Health Check
  resource.customizations.health.ceph.rook.io_CephCluster: |
    hs = {}
    if obj.status ~= nil then
      local state = obj.status.state or ""
      local health = ""
      if obj.status.ceph ~= nil then
        health = obj.status.ceph.health or ""
      end
      if state == "Created" and health == "HEALTH_OK" then
        hs.status = "Healthy"
        hs.message = "Ceph cluster is healthy"
        return hs
      end
      hs.status = "Progressing"
      hs.message = "State=" .. state .. " Health=" .. health
      return hs
    end
    hs.status = "Progressing"
    hs.message = "Waiting for CephCluster status"
    return hs

주요 설정 포인트는 아래와 같습니다.

accounts.monitoring: apiKey
- CI/CD 파이프라인 등에서 API 토큰으로 ArgoCD를 호출할 계정
CephCluster health check
- ArgoCD는 기본적으로 CRD 리소스의 Health를 판단할 수 없습니다.
- Lua 스크립트를 통해 Rook-Ceph의 상태를 직접 파악하도록 커스터마이징 합니다.

즉, 여기서 확인할 수 있는 핵심은

ArgoCD는 기본 리소스(Deployment,Pod 등)의 Health는 자동으로 판단하지만, CephCluster 같은 CRD는 Lua 스크립트로 직접 Health 로직을 정의해줘야 한다는 점입니다.

10. RBAC 권한 설정

# 70_argocd_secret.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-rbac-cm
  namespace: argocd
data:
  policy.csv: |
    g, monitoring, role:readonly

monitoring 계정에 읽기 전용 권한을 부여합니다.

API 토큰을 발급받아 외부 시스템에서 ArgoCD 상태를 조회할 때 사용합니다.

11. 설치 후 검증

[Pod 상태 확인]

kubectl get pods -n argocd

NAME                                                READY   STATUS    RESTARTS
argocd-application-controller-0                     1/1     Running   0
argocd-applicationset-controller-xxx                1/1     Running   0
argocd-notifications-controller-xxx                 1/1     Running   0
argocd-redis-xxx                                    1/1     Running   0
argocd-repo-server-xxx                              1/1     Running   0
argocd-server-xxx                                   1/1     Running   0

[Service 확인]

kubectl get svc -n argocd

argocd-server가 NodePort(30010)로 노출되어 있는지 확인합니다.

[초기 admin 비밀번호 확인]

kubectl get secret argocd-initial-admin-secret -n argocd \
  -o jsonpath="{.data.password}" | base64 -d

[Web UI 접속]

Ingress 설정 URL로 접속 후 로그인합니다.

Username: admin
Password: 위 명령어로 확인한 값

⚠️ 초기 비밀번호는 로그인 후 반드시 변경하세요.

Pod가 정상 상태가 되지 않는 경우 아래 명령어로 원인을 확인합니다.

# Pod 상태 상세 확인
kubectl describe pod <pod-name> -n argocd

# Pod 로그 확인
kubectl logs <pod-name> -n argocd

자주 발생하는 원인은 아래와 같습니다.

증상	원인	조치
Pending 상태 지속	이미지 pull 실패	Harbor 로그인 상태 및 이미지 경로 확인
CrashLoopBackOff	values.yaml 설정 오류	kubectl logs로 argocd-server 로그 확인
repo-server TLS 오류	Harbor 인증서 미등록	argocd-tls-certs-cm ConfigMap 적용 여부 확인
Harbor Helm Chart pull 실패	OCI Secret 미등록	repo-harbor-oci Secret 적용 여부 확인

마무리

이번 글에서는 온프레미스 Kubernetes 환경에서 ArgoCD를 구축하는 과정을 정리해 봤습니다.

정리하면,

Helm 설치 → helm upgrade --install로 idempotent 하게 설치
Ingress → MetalLB + ingress-nginx + sslip.io로 도메인 접근
Git 저장소 인증 → argocd.argoproj.io/secret-type: repository 라벨을 붙인 Secret으로 등록
Harbor OCI 인증 → enableOCI: "true" Secret으로 별도 등록
TLS 신뢰 → Harbor self-signed CA 인증서를 argocd-tls-certs-cm으로 등록
ConfigMap → API 계정 생성 및 CRD health check Lua 스크립트 커스터마이징
RBAC → argocd-rbac-cm으로 계정별 권한 설정

라고 볼 수 있습니다.

특히 이번 구축에서 주의해야 할 포인트는

Git 저장소 인증과 Harbor OCI 인증은 values.yaml이 아닌 별도 Secret으로 관리해야 함
Harbor self-signed 인증서는 반드시 argocd-tls-certs-cm에 등록해야 repo-server가 정상 동작
server.insecure: true는 TLS 없이 HTTP로 운영할 때 사용하는 설정

이 3가지였습니다.

다음 편에서는 App of Apps 패턴을 활용해 플랫폼 전체 앱을 GitOps로 관리하는 방법을 다뤄보겠습니다.

궁금한 점이나 추가로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요!

[Data Platform] Superset 구축 가이드 (feat. Trino 연동)

환이s — Wed, 10 Jun 2026 15:29:15 +0900

Intro

안녕하세요. 환이s입니다

지난 글에서는 데이터 레이크하우스 플랫폼의

여섯 번째 스택으로 Prometheus + Grafana를 Kubernetes 위에 구축하고

클러스터 모니터링 환경을 구성하는 과정을 정리해 봤습니다.

이번 글에서는 일곱 번째 스택,

Superset을 Kubernetes 환경에 구축하고

Trino와 연동해서 Delta Lake 데이터를 시각화하는 과정을 정리해보려고 합니다.

지금까지 구축한 파이프라인에서

Kafka → Spark → Delta Lake → Trino까지 데이터가 흘러왔다면,

이제 이 데이터를 비즈니스 관점으로 시각화할 도구가 필요합니다.

그 역할을 담당하는 것이 바로 Superset입니다.

이번 글에서는

Trino 드라이버가 포함된 커스텀 이미지를 빌드하고 Harbor에 푸시하는 방법
OCI 방식으로 Superset Helm Chart를 설치하는 방법
Superset에서 Trino DB 연결을 등록하고 Delta Lake 데이터를 조회하는 방법

까지 순서대로 확인해 보겠습니다.

1. Superset 아키텍처 개요

본격적인 설치에 앞서,

이번 구성의 전체 아키텍처를 먼저 이해하는 것이 중요합니다.

Superset (시각화)
      │  SQLAlchemy URI로 연결
      ▼
Trino (쿼리 엔진)
      │  메타데이터 조회
      ▼
Hive Metastore
      │  실제 데이터 읽기
      ▼
Ceph S3 (Delta Lake)

각 컴포넌트의 역할은 아래와 같습니다.

컴포넌트	역할
Superset	Trino를 통해 Delta Lake 데이터를 SQL로 조회하고 차트/대시보드로 시각화
Trino	Superset의 쿼리를 받아 Ceph S3의 실제 데이터를 조회하고 결과 반환
PostgreSQL	Superset의 메타데이터 (대시보드, 차트, 유저 등) 영구 저장
Redis	Superset Celery Worker의 캐시 및 비동기 작업 큐

즉, 여기서 확인할 수 있는 핵심은

Superset은 데이터를 직접 저장하지 않고,

Trino를 통해 Delta Lake 데이터를 SQL로 조회한 뒤 시각화한다는 점입니다.

2. 설치 순서

이번 구축에서 사용하는 디렉토리 구조는 아래와 같습니다.

superset/
├── helm/
│   └── 10_superset_values.yaml   # Helm 커스텀 값
└── yaml/
    ├── 10_superset_namespace.yaml  # Namespace 생성
    └── 20_superset_ingress.yaml    # Ingress 설정

설치 순서는 아래와 같습니다.

커스텀 이미지 빌드 및 푸시 → Namespace 생성 → Helm 설치 → Ingress 설정 → Trino 연동

3. 커스텀 이미지 빌드

Superset 공식 이미지에는 Trino 드라이버가 포함되어 있지 않습니다.

Trino 연동을 위해 trino 패키지를 추가한 커스텀 이미지를 빌드합니다.

# Dockerfile
FROM apache/superset:5.0.0
USER root
RUN /app/.venv/bin/python -m pip install --no-cache-dir psycopg2-binary trino
USER superset

빌드 후 이미지 레지스트리에 푸시합니다.

Harbor를 사용하는 경우

docker build -t harbor.local/library/superset-custom:5.0.1 .
docker push harbor.local/library/superset-custom:5.0.1

Harbor가 없는 경우

Docker Hub 또는 다른 레지스트리를 사용할 수 있습니다.

# Docker Hub
docker build -t <your-dockerhub-id>/superset-custom:5.0.1 .
docker push <your-dockerhub-id>/superset-custom:5.0.1

# 또는 직접 클러스터 노드에 이미지를 로드하는 방법 (폐쇄망 환경)
docker save <your-dockerhub-id>/superset-custom:5.0.1 -o superset-custom.tar
scp superset-custom.tar <node-ip>:/tmp/
ssh <node-ip> docker load -i /tmp/superset-custom.tar

참고: 클러스터가 외부 레지스트리에 접근할 수 없는 폐쇄망 환경이라면 docker save → docker load 방식으로 각 노드에 직접 이미지를 로드할 수 있습니다.

즉, 여기서 확인할 수 있는 핵심은

/app/.venv/bin/python으로 pip install을 실행해야 한다는 점입니다.

Superset 이미지는 /app/.venv 가상환경 안에 패키지가 설치되어 있기 때문에

일반 pip install로는 반영이 되지 않습니다.

4. Namespace 생성

Superset 전용 Namespace를 먼저 생성합니다.

# yaml/10_superset_namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: superset

kubectl apply -f yaml/10_superset_namespace.yaml

5. Helm으로 Superset 설치

OCI 방식으로 Harbor에서 Superset Helm Chart를 가져옵니다.

(Harbor가 없는 환경이라면 공식 Chart를 사용할 수 있습니다.)

superset/helm/superset at master · apache/superset

Apache Superset is a Data Visualization and Data Exploration Platform - apache/superset

github.com

helm upgrade --install superset-helm \\
  oci://harbor.local/helm-chart/superset \\
  --version 0.15.2 \\
  --namespace superset \\
  -f helm/10_superset_values.yaml

참고: 이전에는 로컬 .tgz 파일로 설치했다가 현재는 OCI 방식으로 변경했습니다. 로컬 tgz 방식으로 설치할 경우 아래와 같이 실행하면 됩니다.

helm upgrade --install superset-helm helm/superset-0.15.2.tgz \\
  --namespace superset \\
  -f helm/10_superset_values.yaml

values.yaml의 핵심 설정은 아래와 같습니다.

이미지 설정

image:
  repository: harbor.local/library/superset-custom
  tag: "5.0.1"
  pullPolicy: IfNotPresent
initImage:
  repository: harbor.local/library/superset-dockerize
  tag: "dockerize"
  pullPolicy: IfNotPresent

3번에서 빌드한 커스텀 이미지를 사용합니다.

리소스 설정

resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: 1000m
    memory: 1Gi

Superset 설정

configOverrides:
  secret: |
    SECRET_KEY = 'UEp10tAn2qzHK2wzng2f4Q6EKv26aBsDYKfrg5le9qWhihn3aPDMb+1i'
    SQLALCHEMY_DATABASE_URI = "postgresql+psycopg2://admin:admin123@superset-helm-postgresql:5432/superset"

⚠️ 운영 환경에서는 SECRET_KEY와 DB 접속 정보를 Kubernetes Secret으로 분리해서 관리하는 것을 권장합니다.

PostgreSQL 설정

postgresql:
  enabled: true
  image:
    registry: harbor.local
    repository: library/postgresql
    tag: "16"
  auth:
    username: admin
    password: admin123
    database: superset
  primary:
    persistence:
      enabled: true
      storageClass: rook-ceph-block
      size: 8Gi

Superset 메타데이터를 Ceph 블록 스토리지에 영구 저장합니다.

Redis 설정

redis:
  enabled: true
  image:
    registry: harbor.local
    repository: library/redis
    tag: "7.2"

Pod가 Running 상태인지 확인합니다.

kubectl get pods -n superset

정상적인 경우 아래처럼 보입니다.

NAME                                        READY   STATUS    RESTARTS   AGE
superset-helm-xxxxxxxxxx-xxxxx              1/1     Running   0          ...
superset-helm-celerybeat-xxxxxxxxxx-xxxxx   1/1     Running   0          ...
superset-helm-postgresql-0                  1/1     Running   0          ...
superset-helm-redis-master-0                1/1     Running   0          ...
superset-helm-worker-xxxxxxxxxx-xxxxx       1/1     Running   0          ...

Pod가 Running 상태가 되지 않는 경우 아래 명령어로 원인을 확인합니다.

# Pod 상태 상세 확인
kubectl describe pod <pod-name> -n superset

# Pod 로그 확인
kubectl logs <pod-name> -n superset

자주 발생하는 원인은 아래와 같습니다.

증상	원인	조치
Pending 상태 지속	PVC 바인딩 실패	kubectl get pvc -n superset으로 PVC 상태 확인
CrashLoopBackOff	SECRET_KEY 또는 DB URI 오류	kubectl logs로 Superset 컨테이너 로그 확인
ImagePullBackOff	이미지 pull 실패	Harbor 로그인 상태 또는 커스텀 이미지 빌드 여부 확인

6. Ingress 설정

# yaml/20_superset_ingress.yaml
spec:
  ingressClassName: nginx
  rules:
  - host: superset.<your-ip>.sslip.io
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: superset-helm
            port:
              number: 8088

kubectl apply -f yaml/20_superset_ingress.yaml

Superset UI는 아래 주소로 접근할 수 있습니다.

http://superset.<your-ip>.sslip.io
ID: admin
PW: (values.yaml에서 설정한 패스워드)

7. Trino 연동

1.Trino 연결 테스트

Superset Pod에서 Trino로 연결이 되는지 먼저 확인합니다.

kubectl exec -n superset deploy/superset-helm -c superset -- \\
  python3 -c "
import trino
conn = trino.dbapi.connect(
  host='trino-service.trino.svc',
  port=8080,
  user='admin'
)
cur = conn.cursor()
cur.execute('SHOW CATALOGS')
print(cur.fetchall())
"

정상적인 경우 아래처럼 보입니다.

[['delta'], ['hive'], ['jmx'], ['memory'], ['system'], ['tpcds'], ['tpch']]

즉, 여기서 확인할 수 있는 핵심은

Superset과 Trino가 서로 다른 Namespace(superset vs trino)에 있기 때문에 클러스터 내부 DNS 형식인 trino-service.trino.svc로 접근해야 한다는 점입니다.

2.Superset UI에서 DB 연결 등록

Superset 접속 → 상단 메뉴 Settings → Database Connections 클릭
우측 상단 + Database 클릭
Trino 선택
SQLAlchemy URI 입력

trino://admin@trino-service.trino.svc:8080/delta

URI 구조는 아래와 같습니다.

부분	의미
trino://	SQLAlchemy Trino 드라이버
admin	Trino 접속 유저명
trino-service.trino.svc	서비스명.네임스페이스.svc (클러스터 내부 DNS)
8080	Trino 서비스 내부 포트
/delta	카탈로그명

⚠️ 포트를 NodePort로 넣으면 안 됩니다.
NodePort는 클러스터 외부에서 접근할 때 사용하는 포트입니다.
Superset은 클러스터 내부에 있기 때문에 반드시 서비스 내부 포트인 8080을 사용해야 합니다.
클러스터 외부 (브라우저 등) → NodePort 사용
클러스터 내부 (Superset Pod) → 서비스 포트 8080 사용

5.Test Connection 클릭 → 연결 성공 확인

6.Connect 클릭

즉, 여기서 확인할 수 있는 핵심은

URI에서 마지막 /delta가 카탈로그명을 의미한다는 점입니다.

delta 카탈로그를 통해 Delta Lake 테이블을 조회할 수 있습니다.

8. 차트 구현

DB 연결이 완료되면 Delta Lake 데이터를 기반으로 차트를 만들 수 있습니다.

Dataset 등록

상단 메뉴 Datasets 클릭
+ Dataset 클릭
Database: Trino, Schema: default, Table 선택
Add Dataset 클릭

차트 생성

상단 메뉴 Charts 클릭
+ Chart 클릭
Dataset 선택 → 차트 유형 선택 (Bar Chart, Line Chart 등)
쿼리 조건 설정 후 Run 클릭

즉, 여기서 확인할 수 있는 핵심은

Dataset을 한 번 등록해 두면 이후 여러 차트와 대시보드에서 동일한 Dataset을 재사용할 수 있다는 점입니다.

마무리

이번 글에서는

Kubernetes 위에서 Superset을 구축하고 Trino와 연동해서 Delta Lake 데이터를 시각화하는 과정을 정리해 봤습니다.

정리하면,

커스텀 이미지 → 공식 Superset 이미지에 trino 드라이버 추가 후 Harbor에 푸시
Helm OCI 방식 → Harbor에서 Chart를 가져와서 설치
PostgreSQL + Redis → Superset 메타데이터 영구 저장 + Celery 작업 큐
Trino 연동 → trino-service.trino.svc 클러스터 내부 DNS로 연결
Delta Lake 시각화 → Dataset 등록 → 차트 생성 → 대시보드 구성

라고 볼 수 있습니다.

특히 이번 구축에서 주의해야 할 포인트는

pip install 시 /app/.venv/bin/python -m pip 경로로 실행해야 가상환경에 반영
Superset과 Trino가 다른 Namespace에 있으므로 trino-service.trino.svc 형식으로 접근
SECRET_KEY와 DB 접속 정보는 운영 환경에서 반드시 Kubernetes Secret으로 분리 권장

이 3가지였습니다.

다음 편에서는 지금까지 구축한 전체 스택을 GitOps 방식으로 관리하는 ArgoCD 구축 과정을 다뤄보겠습니다.

궁금한 점이나 추가로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요!

[Data Platform] Prometheus + Grafana 구축 가이드 (feat. kube-prometheus-stack)

환이s — Tue, 9 Jun 2026 11:45:58 +0900

Intro

안녕하세요. 환이s입니다

지난 글에서는 데이터 레이크하우스 플랫폼의

다섯 번째 스택으로 Airflow를 Kubernetes 위에 구축하고

Spark Job을 스케줄링하는 전체 파이프라인을 정리해 봤습니다.

이번 글에서는 여섯 번째 스택,

Prometheus + Grafana를 Kubernetes 환경에 구축하는 과정을 정리해보려고 합니다.

지금까지 구축한 Kafka, Spark, Ceph, Trino, Airflow가 실제로 잘 동작하고 있는지

한눈에 확인하려면 모니터링 환경이 필요합니다.

그 역할을 담당하는 것이 Prometheus와 Grafana입니다.

이번 글에서는

kube-prometheus-stack으로 Prometheus + Grafana + Alertmanager + NodeExporter를 한 번에 설치하는 방법
Prometheus와 Grafana 각각 Ingress로 외부 접근하는 방법
Grafana 대시보드를 JSON 파일로 Import하는 방법

까지 순서대로 확인해 보겠습니다.

1. kube-prometheus-stack 아키텍처 개요

본격적인 설치에 앞서,

이번 구성의 전체 아키텍처를 먼저 이해하는 것이 중요합니다.

Kubernetes 클러스터
        │
        ▼
  NodeExporter (각 노드 메트릭 수집)
        │
        ▼
   Prometheus (메트릭 수집 및 저장)
        │
        ▼
    Grafana (메트릭 시각화 대시보드)
        │
  Alertmanager (알림 관리)

각 컴포넌트의 역할은 아래와 같습니다.

컴포넌트	역할
Prometheus	클러스터 및 애플리케이션 메트릭 수집 및 저장
Grafana	Prometheus 데이터를 시각화하는 대시보드
Alertmanager	알림 규칙 기반으로 알림 발송 관리
NodeExporter	각 노드의 CPU, 메모리, 디스크 등 시스템 메트릭 수집

즉, 여기서 확인할 수 있는 핵심은

kube-prometheus-stack 하나로 이 4가지 컴포넌트를 한 번에 설치하고

ServiceMonitor까지 자동으로 연결된다는 점입니다.

개별 설치 방식과 비교하면 아래와 같습니다.

방식	특징
개별 설치	버전 호환성 직접 관리, ServiceMonitor 별도 설정 필요
kube-prometheus-stack	버전 호환성 자동 관리, ServiceMonitor 자동 연결

2. 설치 순서

이번 구축에서 사용하는 디렉토리 구조는 아래와 같습니다.

prometheus/
├── helm/
│   ├── install.sh              # Helm 설치 스크립트
│   └── values.yaml             # Helm 커스텀 값
├── manifests/
│   ├── 10_ingress_prometheus.yaml
│   └── 20_ingress_grafana.yaml
└── grafana_dashboards/
    ├── clusterOverview.json    # 클러스터 전체 현황 대시보드
    └── nodeOverview.json       # 노드별 리소스 현황 대시보드

설치 순서는 아래와 같습니다.

Helm 설치 → Ingress 설정 → Grafana 대시보드 Import

3. Helm으로 kube-prometheus-stack 설치

Harbor 내부 레지스트리에서 OCI 방식으로 Helm Chart를 가져옵니다.

(Harbor가 없는 환경이라면 아래 공식 이미지를 확인해서 대체하시면 됩니다.)

prom/alertmanager - Docker Image

⁠Alertmanager The Alertmanager handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct receiver integrations⁠ such as email, PagerDuty, OpsGenie, or many other

hub.docker.com

prom/node-exporter - Docker Image

...

hub.docker.com

grafana/grafana - Docker Image

Security Internet of things Monitoring & observability

hub.docker.com

prom/prometheus - Docker Image

⁠ Prometheus Visit prometheus.io⁠ for the full documentation, examples and guides. Prometheus, a Cloud Native Computing Foundation⁠ project, is a systems and service monitoring system. It collects metrics from configured targets at given intervals, e

hub.docker.com

# helm/install.sh
NAMESPACE=monitoring
RELEASE_NAME=prometheus
REGISTRY=harbor.local
CHART_VERSION=82.10.5

helm registry login $REGISTRY

helm upgrade --install $RELEASE_NAME \
  oci://$REGISTRY/helm-chart/kube-prometheus-stack \
  --version $CHART_VERSION \
  --namespace $NAMESPACE \
  --create-namespace \
  -f values.yaml

values.yaml의 핵심 설정은 아래와 같습니다.

NodeExporter 설정

nodeExporter:
  enabled: true
  image:
    registry: harbor.local
    repository: library/monitoring/node-exporter
    tag: v1.8.1

각 노드에 DaemonSet으로 배포되어 CPU, 메모리, 디스크 등 시스템 메트릭을 수집합니다.

Prometheus 설정

prometheus:
  service:
    type: NodePort
    port: 80
    targetPort: 9090
    nodePort: 31010
  prometheusSpec:
    storageSpec:
      volumeClaimTemplate:
        spec:
          storageClassName: rook-ceph-block
          accessModes: ["ReadWriteOnce"]
          resources:
            requests:
              storage: 20Gi
    image:
      registry: harbor.local
      repository: library/monitoring/prometheus
      tag: v2.50.0

수집된 메트릭을 Ceph 블록 스토리지에 영구 저장합니다.

rook-ceph-block StorageClass를 사용해서 RWO 방식의 PVC를 생성합니다.

Grafana 설정

grafana:
  adminPassword: "secure123!"
  service:
    type: NodePort
    port: 80
    targetPort: 3000
    nodePort: 31020
  image:
    registry: harbor.local
    repository: library/monitoring/grafana
    tag: 12.4.0

⚠️ adminPassword를 values.yaml에 고정값으로 설정한 이유는 ArgoCD GitOps 배포 환경에서 OutOfSync 방지를 위해서입니다.

운영 환경에서는 Kubernetes Secret으로 분리해서 관리하는 것을 권장합니다.

Alertmanager 설정

alertmanager:
  alertmanagerSpec:
    storage:
      volumeClaimTemplate:
        spec:
          storageClassName: rook-ceph-block
          accessModes: ["ReadWriteOnce"]
          resources:
            requests:
              storage: 5Gi

Alertmanager는 이번 구성에서 설치만 되어 있는 상태입니다.

실제 알림 receiver 설정(Slack, Email 등)은 추후 별도 가이드에서 다루겠습니다.

Pod가 Running 상태인지 확인합니다.

kubectl get pods -n monitoring

정상적인 경우 아래처럼 보입니다.

NAME                                                      READY   STATUS    RESTARTS   AGE
prometheus-helm-kube-prome-prometheus-0                   2/2     Running   0          ...
prometheus-helm-grafana-xxxxxxxxxx-xxxxx                  3/3     Running   0          ...
prometheus-helm-kube-prome-alertmanager-0                 2/2     Running   0          ...
prometheus-helm-prometheus-node-exporter-xxxxx            1/1     Running   0          ...

Pod가 Running 상태가 되지 않는 경우 아래 명령어로 원인을 확인합니다.

# Pod 상태 상세 확인
kubectl describe pod <pod-name> -n monitoring

# Pod 로그 확인
kubectl logs <pod-name> -n monitoring

자주 발생하는 원인은 아래와 같습니다.

증상	원인	조치
Pending 상태 지속	PVC 바인딩 실패	kubectl get pvc -n monitoring으로 PVC 상태 확인
CrashLoopBackOff	Grafana 설정 오류	kubectl logs로 Grafana 컨테이너 로그 확인
ImagePullBackOff	이미지 pull 실패	Harbor 로그인 상태 또는 공식 이미지 URL 확인

4. Ingress 설정

Prometheus와 Grafana 각각 Ingress를 설정합니다.

Prometheus Ingress

# manifests/10_ingress_prometheus.yaml
spec:
  ingressClassName: nginx
  rules:
  - host: prometheus.<your-ip>.sslip.io
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: prometheus-helm-kube-prome-prometheus
            port:
              number: 80

Grafana Ingress

# manifests/20_ingress_grafana.yaml
spec:
  ingressClassName: nginx
  rules:
  - host: grafana.<your-ip>.sslip.io
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: prometheus-helm-grafana
            port:
              number: 80

kubectl apply -f manifests/

접근 주소는 아래와 같습니다.

Prometheus : http://prometheus.<your-ip>.sslip.io
Grafana    : http://grafana.<your-ip>.sslip.io
             ID: admin
             PW: (values.yaml에서 설정한 adminPassword)

즉, 여기서 확인할 수 있는 핵심은

Prometheus 서비스명이 prometheus-helm-kube-prome-prometheus처럼

길게 자동 생성되기 때문에 kubectl get svc -n monitoring으로

실제 서비스명을 먼저 확인하고 Ingress에 적용해야 한다는 점입니다.

kubectl get svc -n monitoring

5. Grafana Dashboard Import

Grafana에 대시보드를 등록하는 방법은 두 가지가 있습니다.

방법	특징
UI Import	JSON 파일을 Grafana에서 직접 업로드, 즉시 반영
ConfigMap 프로비저닝	values.yaml에 설정해서 배포 시 자동 등록

이번 구성에서는 UI Import 방식을 사용합니다.

이번 구성에서 사용하는 JSON 파일은 Grafana 공식 대시보드를 기반으로 직접 커스텀한 파일입니다.
공식 대시보드는 Grafana Dashboard에서 찾을 수 있으며, 다운로드한 JSON을 환경에 맞게 수정한 뒤 아래 방법으로 Import 하면 됩니다.

Grafana dashboards | Grafana Labs

No results found. Please clear one or more filters.

grafana.com

Import 순서

Grafana 접속 → 좌측 메뉴 Dashboards 클릭
우측 상단 New → Import 클릭
JSON 파일 업로드
Import 버튼 클릭

등록하면 아래 두 개의 대시보드를 확인할 수 있습니다.

대시보드	내용
00_Cluster Overview	클러스터 전체 CPU, 메모리, 네트워크 현황
00_Node Overview	노드별 리소스 사용량 상세 현황

즉, 여기서 확인할 수 있는 핵심은

JSON 파일을 그대로 Import하면 Prometheus에서 수집한 메트릭이 Grafana 대시보드에 즉시 연동된다는 점입니다.

마무리

이번 글에서는

Kubernetes 위에서 kube-prometheus-stack으로 Prometheus + Grafana + Alertmanager + NodeExporter를 한 번에 구축하는 과정을 정리해 봤습니다.

정리하면,

kube-prometheus-stack → 4가지 컴포넌트를 한 번에 설치, 버전 호환성 자동 관리
Ceph 블록 스토리지 → Prometheus / Alertmanager 메트릭 영구 저장
Ingress → Prometheus / Grafana 각각 외부 접근
JSON Import → 대시보드를 파일로 관리하고 UI에서 바로 등록

라고 볼 수 있습니다.

특히 이번 구축에서 주의해야 할 포인트는

Ingress 서비스명은 반드시 kubectl get svc -n monitoring으로 확인 후 적용
adminPassword 고정값 설정은 ArgoCD OutOfSync 방지 목적 — 운영 환경에서는 Secret으로 분리 권장
Alertmanager는 설치만 된 상태 — 실제 알림 receiver 설정은 추후 별도 가이드에서 다룰 예정

이 3가지였습니다.

다음 편에서는 데이터를 비즈니스 관점으로 시각화하는 Superset 구축 과정을 다뤄보겠습니다.

궁금한 점이나 추가로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요!

[Data Platform] Airflow 구축 가이드 (feat. Spark on Kubernetes)

환이s — Mon, 8 Jun 2026 10:52:48 +0900

Intro

안녕하세요. 환이s입니다

지난 글에서는 데이터 레이크하우스 플랫폼의

네 번째 스택으로 Trino + Hive Metastore + PostgreSQL 3계층 구조로

Delta Lake SQL 조회 환경을 구축하는 과정을 정리해 봤습니다.

이번 글에서는 다섯 번째 스택,

Airflow를 Kubernetes 환경에 구축하는 과정을 정리해보려고 합니다.

Spark Streaming으로 처리된 데이터는

Delta Lake 포맷으로 Ceph S3에 쌓이게 됩니다.

이 흐름을 주기적으로 실행하고 스케줄링하려면

워크플로우 오케스트레이터가 필요한데,

그 역할을 담당하는 것이 바로 Airflow입니다.

이번 글에서는

Helm으로 Airflow를 Kubernetes 위에 설치하는 방법
CeleryExecutor + Redis 기반 분산 실행 구조
FileBrowser로 DAG 파일을 Web UI에서 직접 관리하는 방법
SparkKubernetesOperator로 Spark Job을 K8s에 제출하는 방법
PythonOperator로 S3 이벤트 로그를 파티셔닝하고 Trino와 동기화하는 방법

까지 순서대로 확인해 보겠습니다.

1. Airflow 아키텍처 개요

본격적인 설치에 앞서,

이번 구성의 전체 아키텍처를 먼저 이해하는 것이 중요합니다.

FileBrowser (Web UI)
      │  DAG 파일 업로드/편집
      ▼
CephFS PVC (airflow-helm-dags)
      │  공유 볼륨 마운트
      ▼
Airflow Scheduler ──► Airflow Worker (CeleryExecutor)
                              │
                    SparkKubernetesOperator
                              │
                    SparkApplication YAML 제출
                              ▼
                    Spark Driver / Executor Pod
                              │
                    Ceph S3 (Delta Lake) 적재
                              │
                    Trino 파티션 동기화

각 컴포넌트의 역할은 아래와 같습니다.

컴포넌트	역할
Airflow Scheduler	DAG 스케줄 감지 및 Task 실행 지시
Airflow Worker	CeleryExecutor 기반으로 Task를 실제 실행
Redis	Celery 브로커 역할 — Scheduler와 Worker 간 Task 큐
CephFS PVC	Scheduler, Worker, Spark Pod가 공유하는 DAG 파일 저장소
FileBrowser	Web UI에서 DAG 파일을 직접 업로드/편집

즉, 여기서 확인할 수 있는 핵심은

DAG 파일이 저장된 CephFS PVC를 Scheduler, Worker, Spark Pod 모두가 동시에 마운트하기 때문에 ReadWriteMany 모드가 반드시 필요하다는 점입니다.

2. 설치 순서

이번 구축에서 사용하는 디렉토리 구조는 아래와 같습니다.

airflow/
├── helm/
│   ├── install.sh        # Helm 설치 스크립트
│   └── values.yaml       # Helm 커스텀 값
└── manifests/
    ├── 00_rbac/
    │   ├── 10_airflow-spark-role.yaml      # Spark 제어 권한 정의
    │   └── 20_airflow-spark-binding.yaml   # Worker SA에 권한 바인딩
    ├── 10_pvc/
    │   └── 10_airflow-pvc.yaml             # 로그 PVC (수동 생성)
    ├── 20_ingress/
    │   └── 10_airflow-ingress-webserver.yaml
    └── 30_filebrowser/
        ├── 10_airflow_file_browser.yaml    # FileBrowser Deployment
        └── 20_airflow-ingress-filebrowser.yaml

설치 순서는 반드시 아래 순서를 지켜야 합니다.

PVC 수동 생성 → RBAC 설정 → Helm 설치 → Ingress → FileBrowser

반드시 지켜야 하는 포인트가 1곳 있습니다.

로그 PVC(airflow-logs-manual-pvc)는 Helm 설치 전에 수동으로 먼저 생성해야 합니다.

values.yaml에서 existingClaim으로 참조하기 때문에,

Helm이 먼저 실행되면 PVC를 찾지 못해 오류가 발생합니다.

3. PVC 사전 생성

Airflow 로그 PVC를 먼저 생성합니다.

# manifests/10_pvc/10_airflow-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: airflow-logs-manual-pvc
  namespace: airflow
spec:
  accessModes:
    - ReadWriteMany
  storageClassName: rook-cephfs
  resources:
    requests:
      storage: 5Gi

kubectl apply -f manifests/10_pvc/10_airflow-pvc.yaml

즉, 여기서 확인할 수 있는 핵심은

DAG 파일용 PVC는 Helm이 자동으로 생성하지만,

로그용 PVC는 반드시 Helm 설치 전에 수동으로 먼저 만들어야 한다는 점입니다.

4. RBAC 설정 (Spark 연동 권한)

Airflow Worker가 Kubernetes에 SparkApplication을 제출하려면

airflow-helm-worker ServiceAccount에 권한이 필요합니다.

# manifests/00_rbac/10_airflow-spark-role.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: airflow-spark-manager-role
  namespace: airflow
rules:
- apiGroups: ["sparkoperator.k8s.io"]
  resources: ["sparkapplications", "sparkapplications/status"]
  verbs: ["create", "get", "watch", "list", "update", "patch", "delete"]
- apiGroups: [""]
  resources: ["pods", "pods/log", "pods/status", "services",
              "configmaps", "persistentvolumeclaims"]
  verbs: ["create", "get", "watch", "list", "update", "patch",
          "delete", "deletecollection"]

# manifests/00_rbac/20_airflow-spark-binding.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: airflow-worker-spark-binding
  namespace: airflow
subjects:
- kind: ServiceAccount
  name: airflow-helm-worker
  namespace: airflow
roleRef:
  kind: Role
  name: airflow-spark-manager-role
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f manifests/00_rbac/

5. Helm으로 Airflow 설치

Harbor 내부 레지스트리에서 OCI 방식으로 Helm Chart를 가져옵니다.

(Harbor가 없는 환경이라면 아래 공식 이미지를 확인해서 대체하시면 됩니다.)

bitnami/postgresql - Docker Image

POSTGRESQL_BASE_DIRPostgreSQL installation directory/opt/bitnami/postgresqlPOSTGRESQL_DEFAULT_CONF_DIRPostgreSQL configuration directory$POSTGRESQL_BASE_DIR/conf.defaultPOSTGRESQL_CONF_DIRPostgreSQL configuration directory$POSTGRESQL_BASE_DIR/confPOSTGRESQ

hub.docker.com

filebrowser/filebrowser - Docker Image

File Browser provides a file managing interface within a specified directory and it can be used to upload, delete, preview, rename and edit your files. It allows the creation of multiple users and each user can have its own directory. Please check the main

hub.docker.com

redis - Official Image | Docker Hub

⁠Quick reference ⁠Supported tags and respective Dockerfile links 8.8.0, 8.8, 8, 8.8.0-trixie, 8.8-trixie, 8-trixie, latest, trixie⁠ 8.8.0-alpine, 8.8-alpine, 8-alpine, 8.8.0-alpine3.23, 8.8-alpine3.23, 8-alpine3.23, alpine, alpine3.23⁠ 8.6.4, 8.6,

hub.docker.com

apache/airflow - Docker Image

⁠Apache Airflow Apache Airflow⁠ (or simply Airflow) is a platform to programmatically author, schedule, and monitor workflows. When workflows are defined as code, they become more maintainable, versionable, testable, and collaborative. Use Airflow to a

hub.docker.com

# helm/install.sh
NAMESPACE=airflow
RELEASE_NAME=airflow
REGISTRY=harbor.local
CHART_VERSION=1.15.0

helm registry login $REGISTRY

helm upgrade --install $RELEASE_NAME \
  oci://$REGISTRY/helm-chart/airflow \
  --version $CHART_VERSION \
  --namespace $NAMESPACE \
  --create-namespace \
  -f values.yaml

values.yaml의 핵심 설정은 아래와 같습니다.

Executor 설정

executor: "CeleryExecutor"

CeleryExecutor는 Redis를 브로커로 사용해 Worker를 분산 실행합니다.

이미지 설정 (Harbor 내부 레지스트리)

(Harbor가 없는 환경이라면 위 공식 이미지를 확인해서 대체하시면 됩니다.)

images:
  airflow:
    repository: harbor.local/library/airflow
    tag: 2.10.5
  redis:
    repository: harbor.local/library/redis
    tag: '7.2'

스토리지 설정

dags:
  persistence:
    enabled: true
    storageClassName: "rook-cephfs"
    accessMode: ReadWriteMany   # Scheduler + Worker + Spark Pod 동시 마운트
    size: 2Gi

logs:
  persistence:
    enabled: true
    storageClassName: "rook-cephfs"
    existingClaim: airflow-logs-manual-pvc  # 3번에서 수동 생성한 PVC 참조

ArgoCD 연동 설정

migrateDatabaseJob:
  useHelmHooks: false
  jobAnnotations:
    "argocd.argoproj.io/hook": Sync

createUserJob:
  useHelmHooks: false
  jobAnnotations:
    "argocd.argoproj.io/hook": Sync

ArgoCD GitOps 배포 환경에서는

Helm Hook 대신 ArgoCD Hook으로 Job을 제어합니다.

useHelmHooks: false로 설정하지 않으면 ArgoCD와 충돌이 발생할 수 있습니다.

ArgoCD 자체 구축 및 설정에 대한 내용은

추후 ArgoCD 구축 가이드에서 더 자세하게 다루겠습니다.

ArgoCD를 사용하지 않는 환경이라면 이 설정은 생략하셔도 됩니다.

Airflow Pod가 Running 상태인지 확인합니다.

kubectl get pods -n airflow

정상적인 경우 아래처럼 보입니다.

NAME                                        READY   STATUS    RESTARTS   AGE
airflow-helm-scheduler-xxxxxxxxxx-xxxxx     1/1     Running   0          ...
airflow-helm-webserver-xxxxxxxxxx-xxxxx     1/1     Running   0          ...
airflow-helm-worker-xxxxxxxxxx-xxxxx        1/1     Running   0          ...
airflow-helm-redis-0                        1/1     Running   0          ...
airflow-helm-postgresql-0                   1/1     Running   0          ...

만약 Pod가 Running 상태가 되지 않는 경우 아래 명령어로 원인을 확인합니다.

# Pod 상태 상세 확인
kubectl describe pod <pod-name> -n airflow

# Pod 로그 확인
kubectl logs <pod-name> -n airflow

자주 발생하는 원인은 아래와 같습니다.

증상	원인	조치
Pending 상태 지속	PVC 바인딩 실패	kubectl get pvc -n airflow로 PVC 상태 확인
CrashLoopBackOff	로그 PVC를 찾지 못함	airflow-logs-manual-pvc 사전 생성 여부 확인
ImagePullBackOff	이미지 pull 실패	Harbor 로그인 상태 또는 공식 이미지 URL 확인

6. Ingress 설정

Airflow Webserver Ingress를 설정합니다.

# manifests/20_ingress/10_airflow-ingress-webserver.yaml
spec:
  ingressClassName: nginx
  rules:
  - host: airflow.<your-ip>.sslip.io
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: airflow-helm-webserver
            port:
              number: 8080

kubectl apply -f manifests/20_ingress/

7. FileBrowser 구성

DAG 파일을 Web UI에서 직접 올리고 편집할 수 있도록 FileBrowser를 구성합니다.

Airflow에서 DAG 파일을 반영하는 방법은 다양하지만 크게 두 가지가 있습니다.

방법	특징
Git Sync	GitOps 방식, PR/Commit 기반 반영
FileBrowser	Web UI에서 직접 업로드/편집, 즉시 반영

이번 구성에서는 FileBrowser를 선택했습니다.

DAG PVC(airflow-helm-dags)를 직접 마운트해서, 파일을 업로드하는 즉시 Scheduler가 감지합니다.

# manifests/30_filebrowser/10_airflow_file_browser.yaml
containers:
- name: explorer
  image: harbor.local/library/filebrowser:latest
  args: ["--database", "/config/database.db", "--noauth"]
  volumeMounts:
  - name: dags-data
    mountPath: /srv/airflow_dags   # DAG PVC 마운트
  - name: fb-config
    mountPath: /config
volumes:
- name: dags-data
  persistentVolumeClaim:
    claimName: airflow-helm-dags   # Airflow DAG PVC 공유
- name: fb-config
  persistentVolumeClaim:
    claimName: airflow-filebrowser-config-pvc

kubectl apply -f manifests/30_filebrowser/

즉, 여기서 확인할 수 있는 핵심은

FileBrowser가 Airflow의 DAG PVC를 직접 마운트하기 때문에 Web UI에서 파일을 올리는 즉시 Scheduler가 새 DAG를 인식한다는 점입니다.

8. DAG 작성 - Spark Job 제출

Airflow에서 Spark Job을 실행하는 방법은 두 가지로 나눌 수 있습니다.

방법 1. SparkKubernetesOperator (YAML 기반)

K8s에 SparkApplication YAML을 직접 제출하는 방식입니다.

# spark_s3_daily_job_v2.4
from airflow.providers.cncf.kubernetes.operators.spark_kubernetes import SparkKubernetesOperator

submit_spark = SparkKubernetesOperator(
    task_id='submit_spark_s3_job',
    namespace='airflow',
    application_file='yaml/spark-s3-reader.yaml',  # DAG PVC 내 YAML 참조
    kubernetes_conn_id='kubernetes_default',
    do_xcom_push=False,
    params={
        'interval_min': INTERVAL_MINUTES
    }
)

SparkApplication YAML에서 핵심 설정은 다음과 같습니다.

# yaml/spark-s3-reader.yaml (주요 부분)
spec:
  mainApplicationFile: "local:///opt/airflow/dags/scripts/filter_review.py"
  arguments:
    - "--start_date"
    - "{{ data_interval_start.in_timezone('Asia/Seoul').strftime('%Y-%m-%d %H:%M:%S') }}"
    - "--end_date"
    - "{{ data_interval_end.in_timezone('Asia/Seoul').strftime('%Y-%m-%d %H:%M:%S') }}"
  timeToLiveSeconds: 300  # 완료 후 5분 뒤 Pod 자동 삭제
  restartPolicy:
    type: Never
  sparkConf:
    # DAG PVC를 Driver/Executor Pod에도 마운트
    "spark.kubernetes.driver.volumes.persistentVolumeClaim.airflow-dags-vol.options.claimName": "airflow-helm-dags"
    "spark.kubernetes.driver.volumes.persistentVolumeClaim.airflow-dags-vol.mount.path": "/opt/airflow/dags"
    "spark.kubernetes.executor.volumes.persistentVolumeClaim.airflow-dags-vol.options.claimName": "airflow-helm-dags"
    "spark.kubernetes.executor.volumes.persistentVolumeClaim.airflow-dags-vol.mount.path": "/opt/airflow/dags"
    # 이벤트 로그 → Ceph S3 저장
    "spark.eventLog.enabled": "true"
    "spark.eventLog.dir": "s3a://spark-event-logs/"

즉, 여기서 확인할 수 있는 핵심은

Spark Driver/Executor Pod도 DAG PVC를 마운트해야

local:///opt/airflow/dags/scripts/filter_review.py 경로의 스크립트를 실행할 수 있다는 점입니다.

방법 2. PythonOperator (S3 직접 처리 + Trino 파티션 동기화)

Ceph S3의 Spark 이벤트 로그를 직접 읽어 처리하는 방식입니다.

# spark_s3_optimizer_v1.2
def add_regdt_and_partition(**context):
    s3 = boto3.client('s3',
        endpoint_url='http://<ceph-rgw-endpoint>',
        ...
    )

    # dt= 접두사가 이미 있는 파일은 스킵 (중복 처리 방지)
    if key.startswith('dt='):
        skipped_count += 1
        continue

    # 처리 완료 후 Trino 파티션 자동 동기화
    query = "CALL hive.system.sync_partition_metadata('spark_logs', 'raw_logs_partitioned', 'ADD')"

이 DAG는 30분 주기로 실행되며,

Spark Job이 쌓은 이벤트 로그를 날짜별 파티션 구조로 정리하고

Trino에서 바로 조회할 수 있도록 파티션을 동기화합니다.

즉, 여기서 확인할 수 있는 핵심은

Airflow가 단순 스케줄링에 그치지 않고,

S3 데이터 정리부터 Trino 파티션 동기화까지 파이프라인 전체를 자동화한다는 점입니다.

마무리

이번 글에서는

Kubernetes 위에서 Airflow를 구축하고 Spark Job을 스케줄링하는 전체 파이프라인을 정리해 봤습니다.

정리하면,

CeleryExecutor + Redis → Worker 분산 실행
CephFS ReadWriteMany PVC → Scheduler, Worker, Spark Pod 간 DAG 파일 공유
FileBrowser → Web UI에서 DAG 직접 업로드/편집, 즉시 반영
SparkKubernetesOperator → YAML 기반으로 K8s에 Spark Job 제출
PythonOperator + Trino 연동 → S3 이벤트 로그 파티셔닝 후 쿼리 자동 동기화

라고 볼 수 있습니다.

특히 이번 구축에서 주의해야 할 포인트는

로그 PVC는 Helm 설치 전에 수동 생성 필수
DAG PVC는 반드시 ReadWriteMany — Spark Pod까지 동시 마운트 필요
ArgoCD 환경에서는 useHelmHooks: false + ArgoCD Hook 설정 필수
SparkApplication YAML에서 DAG PVC를 Driver/Executor 양쪽에 마운트해야 스크립트 실행 가능

이 4가지였습니다.

다음 편에서는 지금까지 구축한 전체 파이프라인을 모니터링하는 Prometheus + Grafana 구성을 다뤄보겠습니다.

궁금한 점이나 추가로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요!

『행복한 이기주의자』 리뷰 | 흔들리지 않는 사람이 되고 싶었다

환이s — Fri, 5 Jun 2026 13:53:34 +0900

시작하기 전에

마음이 단단한 사람을 보면

가끔 궁금해진다.

저 사람은 어떻게 저렇게

쉽게 흔들리지 않을 수 있을까.

누군가의 말 한마디에도,

뜻대로 풀리지 않는 하루에도,

크게 무너지지 않고

자기 자리를 지키는 사람.

나도 그런 사람이 되고 싶었다.

감정에 쉽게 끌려다니지 않고,

남의 시선보다 내 기준으로 살아가는 사람.

그 마음 하나를 붙들고

이 책을 펼쳤다.

웨인 다이어의 『행복한 이기주의자』는

그렇게 시작된 독서였다.

이기주의자라는 말이 불편하지 않았냐고?

처음 제목을 봤을 때 솔직히 조금 낯설었다.

이기주의자.

우리는 그 단어를 대개 부정적으로 배운다.

자기만 아는 사람,

타인을 배려하지 않는 사람.

그런데 이 책에서 말하는 이기주의는

그런 이기주의가 아니었다.

자신을 먼저 온전히 아끼고,

자신의 감정을 솔직하게 인정하며,

타인의 시선이 아닌 자신의 기준으로 살아가는 것.

그것이 이 책이 말하는

진짜 이기주의였다.

가장 오래 마음에 남았던 챕터

책을 읽는 내낸 여러 문장들이 마음에 걸렸지만,

그중에서도 챕터 5,

"미지의 세계를 탐험하라"는

유독 오래 머물렀다.

남들의 눈치를 보지 말고,

오직 내가 원한다는 이유만으로

새로운 경험과 모험을 즐겨라.

이 문장 앞에서 잠깐 멈췄다.

얼마나 많은 것들을

내가 원해서가 아니라

남들이 어떻게 볼까 두려워서

시작하지 못했는지.

혹은 시작했어도

주변의 반응에 흔들려

금세 포기해 버렸는지.

이 챕터는 조용하지만 분명하게 말하고 있었다.

당신의 인생은

당신이 원한다는 이유 하나만으로도

충분히 시작할 수 있다고.

읽고 나서 드는 솔직한 생각

책을 다 읽고 나서도

한동안 이런 생각을 했다.

나는 정말 더 단단해졌을까.

사실 잘 모르겠다.

책 한 권이 사람을 단번에 바꿔놓지는 않는다는 걸 안다.

그리고 단단해진다는 것이

어떤 감각으로 느껴지는 건지도

아직은 잘 모르겠다.

다만 한 가지는 알 것 같다.

이 책을 읽기 전의 나와

일고 난 후의 나 사이에

아주 작은 질문 하나가 생겼다는 것.

지금 나는 내 기준으로 살고 있는가.

그 질문이 남아있다는 것만으로도

이 책은 충분히 제 역할을 했다고 생각한다.

이런 분께 권하고 싶다

감정적으로 쉽게 휘둘린다고 느끼는 사람,

남의 말 한마디에 하루가 무너지는 것 같은 사람,

정작 자신이 뭘 원하는지 잘 모르겠다는 사람.

그런 분들께 한 번쯤 낭독해 보라고 권하고 싶다.

소리 내어 읽어보면 더 좋다.

눈으로 훑는 것과

목소리로 내뱉는 것은

마음에 닿는 깊이가 다르다.

마무리하며

『행복한 이기주의자』는

나를 사랑하라고 크게 외치는 책이 아니다.

대신 아주 조용하고 차분하게,

그러나 분명하게 묻는다.

당신은 지금 당신 자신의 편인가.

그 질문이

마음 어딘가에 오래 머물렀다.

곧 후속편인 두 번째 이야기도 다 읽게 되면

이어서 또 정리해보려 한다.

아마 그때는 조금 더 다른 생각을 하게 될지도 모른다.

[Data Platform] Trino 구축 가이드 (feat. Hive Metastore + Delta Lake)

환이s — Fri, 5 Jun 2026 12:12:00 +0900

Intro

안녕하세요. 환이s입니다

지난 글에서는 데이터 레이크하우스 플랫폼의

세 번째 스택으로 Strimzi Operator 기반의 Kafka 클러스터를

Kubernetes 위에 구축하는 과정을 정리해 봤습니다.

이번 글에서는 네 번째 스택,

Trino를 Kubernetes 환경에 구축하는 과정을 정리해보려고 합니다.

Kafka에서 수집되어 Spark Streaming으로 처리된 데이터는

Delta Lake 포맷으로 Ceph S3에 쌓이게 됩니다.

이 데이터를 SQL로 조회하려면 쿼리 엔진이 필요한데,

그 역할을 담당하는 것이 바로 Trino입니다.

Trino를 Kubernetes 위에서 운영하다 보면

단순히 쿼리 엔진 하나를 띄우는 것에서 끝나는 게 아니라,

Hive Metastore가 Delta Lake 테이블의 메타데이터를 관리하고
PostgreSQL이 Hive Metastore의 백엔드 DB 역할을 하고
Trino가 이 메타데이터를 참조해서 Ceph S3의 실제 데이터를 SQL로 조회하는

3계층 구조가 유기적으로 연결되어야 합니다.

이번 글에서는

Trino + Hive Metastore + PostgreSQL 3계층 아키텍처가 어떻게 동작하는지
실제로 어떤 순서로 설치하면 되는지
Delta Lake 커넥터와 Hive 커넥터를 어떻게 구성하는지
Delta Lake 테이블을 등록하고 SQL로 조회하는 방법

까지 순서대로 확인해 보겠습니다.

1. Trino 아키텍처 개요

본격적인 설치에 앞서,

이번 구성의 전체 아키텍처를 먼저 이해하는 것이 중요합니다.

Ceph S3 (Delta Lake 데이터)
        ↑ 실제 데이터 읽기
      Trino 468
        ↑ 메타데이터 조회 (Thrift 프로토콜)
  Hive Metastore 3.1.3
        ↑ 메타데이터 저장
    PostgreSQL 13

각 컴포넌트의 역할은 아래와 같습니다.

컴포넌트	역할
Trino	SQL 쿼리 실행 엔진 — Ceph S3의 실제 데이터를 읽고 결과 반환
Hive Metastore (HMS)	테이블 스키마, 위치, 파티션 정보 등 메타데이터 관리
PostgreSQL	HMS의 메타데이터를 영구 저장하는 백엔드 DB

즉, 여기서 확인할 수 있는 핵심은

Trino는 데이터를 저장하지 않고, Hive Metastore를 통해 메타데이터를 참조한 뒤 Ceph S3에서 직접 데이터를 읽어 쿼리 결과를 반환한다는 점입니다.

2. 설치 순서

이번 구축에서 사용하는 매니페스트 디렉토리 구조는 아래와 같습니다.

manifests/
├── ms/       # PostgreSQL (Hive Metastore 백엔드 DB)
│   ├── 00_ms_pvc.yaml
│   ├── 10_ms_deployment.yaml
│   └── 20_ms_service.yaml
│
├── hms/      # Hive Metastore
│   ├── 10_hms_configmap.yaml
│   ├── 20_hms_deployment.yaml
│   └── 30_hms_service.yaml
│
└── trino/    # Trino
    ├── 10_trino_namespace.yaml
    ├── 20_trino_configmap.yaml
    ├── 30_trino_deployment.yaml
    ├── 40_trino_service.yaml
    └── 50_trino_secret.yaml

참고: ms 디렉토리는 이름만 보면 MariaDB처럼 보이지만 실제로는 PostgreSQL입니다. Hive Metastore의 백엔드 DB로 PostgreSQL을 사용합니다.

설치 순서는 반드시 아래 순서를 지켜야 합니다.

trino(namespace) → ms(PostgreSQL) → ⏳ → hms(Hive Metastore) → ⏳ → trino(Trino)

반드시 지켜야 하는 대기 구간이 2곳 있습니다.

첫 번째로

PostgreSQL이 완전히 Running 상태가 된 이후에 Hive Metastore를 apply 해야 합니다.

HMS가 기동 시 PostgreSQL에 스키마를 초기화하는 작업을 수행하기 때문입니다.

두 번째로

Hive Metastore가 완전히 Running 상태가 된 이후에 Trino를 apply 해야 합니다.

Trino가 기동 시 HMS에 연결을 시도하기 때문입니다.

3. Namespace 설정

먼저 trino Namespace를 생성합니다.

# 10_trino_namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: trino

kubectl apply -f trino/10_trino_namespace.yaml

PostgreSQL, Hive Metastore, Trino 세 컴포넌트 모두

trino Namespace 하나에서 운영합니다.

4. PostgreSQL 설치 (Hive Metastore Back-End DB)

PostgreSQL은

Hive Metastore가 테이블 메타데이터를 영구 저장하는 백엔드 DB입니다.

PVC 생성

# ms/00_ms_pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: metastore-db-pvc
  namespace: trino
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: rook-ceph-block
  resources:
    requests:
      storage: 10Gi

rook-ceph-block StorageClass를 사용해서 RWO 방식의 PVC를 생성합니다.

DB 데이터는 단일 노드에서만 읽고 쓰기 때문에 RWO 모드가 적합합니다.

Deployment

# ms/10_ms_deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: metastore-db
  namespace: trino
spec:
  replicas: 1
  selector:
    matchLabels:
      app: metastore-db
  template:
    metadata:
      labels:
        app: metastore-db
    spec:
      affinity:
        nodeAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              preference:
                matchExpressions:
                  - key: eluna.role
                    operator: In
                    values:
                      - trino
      containers:
        - name: postgres
          image: harbor.local/library/metastore/postgres:13
          env:
            - name: POSTGRES_DB
              value: metastore
            - name: POSTGRES_USER
              value: hive
            - name: POSTGRES_PASSWORD
              value: YOUR_PASSWORD
          ports:
            - containerPort: 5432
          volumeMounts:
            - name: postgres-data-vol
              mountPath: /var/lib/postgresql/data
              subPath: pgdata
      volumes:
        - name: postgres-data-vol
          persistentVolumeClaim:
            claimName: metastore-db-pvc

⚠️ 운영 환경에서는 POSTGRES_PASSWORD를 Kubernetes Secret으로 분리해서 관리하는 것을 권장합니다.

nodeAffinity에서 eluna.role=trino 레이블이 있는 노드를 선호하도록 설정했습니다.

Service

# ms/20_ms_service.yaml
apiVersion: v1
kind: Service
metadata:
  name: metastore-db
  namespace: trino
spec:
  type: NodePort
  ports:
    - port: 5432
      targetPort: 5432
      nodePort: 30999
  selector:
    app: metastore-db

kubectl apply -f ms/

PostgreSQL Pod가 Running 상태인지 확인합니다.

kubectl get pods -n trino | grep metastore-db

metastore-db-xxxxxxxxxx-xxxxx   1/1   Running   0   ...

즉, 여기서 확인할 수 있는 핵심은

PostgreSQL이 완전히 Running 상태가 된 이후에만 Hive Metastore가 정상적으로 스키마를 초기화할 수 있다는 점입니다.

5. Hive Metastore 설치

Hive Metastore는 Delta Lake 테이블의 스키마, 위치, 파티션 정보를 PostgreSQL에 저장하고 Trino에 제공하는 메타데이터 서버입니다.

ConfigMap

# hms/10_hms_configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: hive-metastore-conf
  namespace: trino
data:
  hive-site.xml: |

        javax.jdo.option.ConnectionURL
        jdbc:postgresql://metastore-db:5432/metastore

        javax.jdo.option.ConnectionDriverName
        org.postgresql.Driver

        javax.jdo.option.ConnectionUserName
        hive

        javax.jdo.option.ConnectionPassword
        YOUR_PASSWORD
      
        fs.s3a.impl
        org.apache.hadoop.fs.s3a.S3AFileSystem

        fs.s3a.endpoint
        http://rook-ceph-rgw-ceph-store.rook-ceph.svc:80

        fs.s3a.access.key
        YOUR_ACCESS_KEY

        fs.s3a.secret.key
        YOUR_SECRET_KEY

        fs.s3a.path.style.access
        true

        hive.metastore.warehouse.dir
        /tmp/hive/warehouse

        hive.metastore.schema.verification
        false

Deployment

# hms/20_hms_deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: hive-metastore
  namespace: trino
spec:
  replicas: 1
  selector:
    matchLabels:
      app: hive-metastore
  template:
    metadata:
      labels:
        app: hive-metastore
    spec:
      affinity:
        nodeAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              preference:
                matchExpressions:
                  - key: eluna.role
                    operator: In
                    values:
                      - trino
      containers:
        - name: hive-metastore
          image: harbor.local/library/hive:3.1.3
          securityContext:
            runAsUser: 0
          command: ["/bin/sh", "-c"]
          args:
            - |
              set -e

              # S3 라이브러리 복사
              cp /opt/hadoop/share/hadoop/tools/lib/hadoop-aws-3.1.0.jar /opt/hive/lib/
              cp /opt/hadoop/share/hadoop/tools/lib/aws-java-sdk-bundle-1.11.271.jar /opt/hive/lib/

              # 스키마 초기화 (최초 기동 시에만 실행)
              /opt/hive/bin/schematool -dbType postgres -info || \
              /opt/hive/bin/schematool -dbType postgres -initSchema

              # Hive Metastore 기동
              exec /opt/hive/bin/hive --service metastore
          ports:
            - containerPort: 9083
          volumeMounts:
            - name: hive-config
              mountPath: /opt/hive/conf/hive-site.xml
              subPath: hive-site.xml
      volumes:
        - name: hive-config
          configMap:
            name: hive-metastore-conf

HMS 기동 시 schematool 명령어로

PostgreSQL에 스키마가 있는지 확인하고, 없으면 자동으로 초기화합니다.

|| initSchema 패턴 덕분에 최초 기동과 재기동 모두 안전하게 처리됩니다.

Service

# hms/30_hms_service.yaml
apiVersion: v1
kind: Service
metadata:
  name: hive-metastore
  namespace: trino
spec:
  ports:
    - port: 9083
      targetPort: 9083
  selector:
    app: hive-metastore

kubectl apply -f hms/

HMS Pod가 Running 상태인지 확인합니다.

kubectl get pods -n trino | grep hive-metastore

hive-metastore-xxxxxxxxxx-xxxxx   1/1   Running   0   ...

HMS 로그에서 스키마 초기화가 완료됐는지도 확인합니다.

kubectl logs -n trino deploy/hive-metastore | grep -i "schema"

Initialization script completed
schemaTool completed

즉, 여기서 확인할 수 있는 핵심은

HMS가 Running 상태이고 스키마 초기화가 완료된 이후에만 Trino를 apply 해야 한다는 점입니다.

6. Trino 설치

Secret (패스워드 인증)

Trino는 파일 기반 패스워드 인증을 사용합니다.

bcrypt로 해시된 패스워드를 Secret으로 관리합니다.

# trino/50_trino_secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: trino-password-file
  namespace: trino
type: Opaque
stringData:
  password.db: |
    admin:$2y$05$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ 운영 환경에서는 반드시 패스워드를 변경해서 사용하세요.
bcrypt 해시는 아래 명령어로 생성할 수 있습니다.
htpasswd -nbBC 10 admin YOUR_PASSWORD

ConfigMap

ConfigMap에는 Trino의 전체 설정이 담겨 있습니다.

# trino/20_trino_configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: trino-config
  namespace: trino
data:
  # 코디네이터 설정
  config.properties: |
    coordinator=true
    node-scheduler.include-coordinator=true
    http-server.http.port=8080
    discovery.uri=http://localhost:8080

    # 패스워드 인증 설정
    http-server.authentication.type=PASSWORD
    http-server.authentication.allow-insecure-over-http=true
    internal-communication.shared-secret=YOUR_INTERNAL_SECRET

  # JVM 설정
  jvm.config: |
    -server
    -Xmx2G
    -XX:+UseG1GC
    -XX:G1HeapRegionSize=32M
    -XX:+UseGCOverheadLimit
    -XX:+ExplicitGCInvokesConcurrent
    -XX:+HeapDumpOnOutOfMemoryError
    -XX:+ExitOnOutOfMemoryError

  # 파일 기반 패스워드 인증
  password-authenticator.properties: |
    password-authenticator.name=file
    file.password-file=/etc/trino/auth/password.db

  # 노드 설정
  node.properties: |
    node.environment=production
    node.data-dir=/data/trino
    plugin.dir=/usr/lib/trino/plugin

  # tpch 커넥터 (테스트용)
  tpch.properties: |
    connector.name=tpch

  # Hive 커넥터
  hive.properties: |
    connector.name=hive
    hive.metastore.uri=thrift://hive-metastore:9083

    fs.native-s3.enabled=true
    s3.endpoint=http://rook-ceph-rgw-ceph-store.rook-ceph.svc:80
    s3.aws-access-key=YOUR_ACCESS_KEY
    s3.aws-secret-key=YOUR_SECRET_KEY
    s3.region=us-east-1
    s3.path-style-access=true

  # Delta Lake 커넥터
  delta.properties: |
    connector.name=delta_lake
    hive.metastore.uri=thrift://hive-metastore:9083

    delta.register-table-procedure.enabled=true

    fs.native-s3.enabled=true
    s3.endpoint=http://rook-ceph-rgw-ceph-store.rook-ceph.svc:80
    s3.aws-access-key=YOUR_ACCESS_KEY
    s3.aws-secret-key=YOUR_SECRET_KEY
    s3.region=us-east-1
    s3.path-style-access=true

주요 설정 포인트는 아래와 같습니다.

커넥터 2개 구성

hive.properties    → Hive 커넥터 (일반 Hive 테이블 조회)
delta.properties   → Delta Lake 커넥터 (Delta Lake 테이블 조회)

두 커넥터 모두

hive.metastore.uri=thrift://hive-metastore:9083으로 동일한 Hive Metastore를 참조합니다.

delta.register-table-procedure.enabled=true

delta.register-table-procedure.enabled=true

이 설정이 핵심입니다.

Spark Streaming이 Ceph S3에 쌓은 Delta Lake 데이터를

Trino에서 CALL 프로시저로 테이블로 등록할 수 있게 해줍니다.

s3.path-style-access=true

Ceph RGW는 경로 방식 S3 URL을 사용하기 때문에 이 설정이 없으면 S3 연결이 실패합니다.

Deployment

# trino/30_trino_deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: trino-deployment
  namespace: trino
spec:
  replicas: 1
  selector:
    matchLabels:
      app: trino
  template:
    metadata:
      labels:
        app: trino
    spec:
      affinity:
        nodeAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              preference:
                matchExpressions:
                  - key: eluna.role
                    operator: In
                    values:
                      - trino
            - weight: 40
              preference:
                matchExpressions:
                  - key: role
                    operator: NotIn
                    values:
                      - kafka
      containers:
        - name: trino-container
          image: harbor.local/library/trino:468
          resources:
            requests:
              memory: "4Gi"
              cpu: "1"
          securityContext:
            runAsUser: 0
          ports:
            - containerPort: 8080
          volumeMounts:
            - name: config-vol
              mountPath: /etc/trino/config.properties
              subPath: config.properties
            - name: config-vol
              mountPath: /etc/trino/jvm.config
              subPath: jvm.config
            - name: config-vol
              mountPath: /etc/trino/node.properties
              subPath: node.properties
            - name: config-vol
              mountPath: /etc/trino/catalog/tpch.properties
              subPath: tpch.properties
            - name: config-vol
              mountPath: /etc/trino/catalog/hive.properties
              subPath: hive.properties
            - name: config-vol
              mountPath: /etc/trino/catalog/delta.properties
              subPath: delta.properties
            - name: config-vol
              mountPath: /etc/trino/password-authenticator.properties
              subPath: password-authenticator.properties
            - name: trino-password-secret
              mountPath: /etc/trino/auth/password.db
              subPath: password.db
              readOnly: true
            - name: data-vol
              mountPath: /data/trino
      volumes:
        - name: config-vol
          configMap:
            name: trino-config
        - name: trino-password-secret
          secret:
            secretName: trino-password-file
        - name: data-vol
          hostPath:
            path: /home/cys/trino
            type: DirectoryOrCreate

ConfigMap의 각 파일을 subPath로 하나씩 정확한 경로에 마운트 합니다.

catalog 디렉토리 아래에 마운트 된. properties 파일이 Trino에서 커넥터로 자동 인식됩니다.

참고: data-vol은 hostPath(/home/cys/trino)를 사용하고 있습니다.
운영 환경에서는 PVC로 교체하는 것을 권장합니다.

nodeAffinity 설정 포인트

# eluna.role=trino 노드 선호 (weight 100)
# role=kafka 노드 기피 (weight 40, NotIn)

Kafka 노드에 Trino가 올라가지 않도록 기피 설정을 함께 적용했습니다.

Service

# trino/40_trino_service.yaml
apiVersion: v1
kind: Service
metadata:
  name: trino-service
  namespace: trino
spec:
  type: NodePort
  selector:
    app: trino
  ports:
    - port: 8080
      targetPort: 8080
      nodePort: 30140

kubectl apply -f trino/

Trino Pod가 Running 상태인지 확인합니다.

kubectl get pods -n trino

NAME                                  READY   STATUS    RESTARTS   AGE
metastore-db-xxxxxxxxxx-xxxxx         1/1     Running   0          ...
hive-metastore-xxxxxxxxxx-xxxxx       1/1     Running   0          ...
trino-deployment-xxxxxxxxxx-xxxxx     1/1     Running   0          ...

Trino UI는 아래 주소로 접근할 수 있습니다.

http://<노드IP>:30140
ID: admin
PW: (50_trino_secret.yaml에서 설정한 패스워드)

즉, 여기서 확인할 수 있는 핵심은

ConfigMap의 각 설정 파일이 subPath로 정확한 경로에 마운트 되어야 Trino가 커넥터와 인증 설정을 정상적으로 읽어올 수 있다는 점입니다.

7. Delta Lake 테이블 등록 및 쿼리 테스트

Trino가 Running 상태가 되면

Spark Streaming이 Ceph S3에 쌓은 Delta Lake 데이터를 테이블로 등록합니다.

Table Call

delta.register-table-procedure.enabled=true 설정 덕분에

아래 CALL 프로시저로 S3의 Delta Lake 데이터를 테이블로 등록할 수 있습니다.

-- Delta Lake 테이블 등록
CALL delta.system.register_table(
  schema_name => 'default',
  table_name  => 'syslog',
  table_location => 's3a://버킷명/syslog/'
);

Query Test

테이블이 정상적으로 등록되면 SQL로 조회할 수 있습니다.

-- 전체 스키마 확인
SHOW SCHEMAS FROM delta;

-- 테이블 목록 확인
SHOW TABLES FROM delta.default;

-- 데이터 조회 (전체)
SELECT * FROM delta.default.syslog LIMIT 10;

-- 파티션 기준 조회 (dt=날짜 파티셔닝 적용 시)
SELECT * FROM delta.default.syslog
WHERE dt = '2026-06-04'
LIMIT 100;

-- 커넥터 목록 확인
SHOW CATALOGS;

파티션 기준 조회 시 Trino가 해당 날짜 폴더만 읽기 때문에

전체 데이터를 스캔하지 않고 쿼리 성능이 크게 향상됩니다.

즉, 여기서 확인할 수 있는 핵심은

register_table 프로시저로 테이블을 등록하면

이후부터는 일반 SQL로 Delta Lake 데이터를 조회할 수 있다는 점입니다.

8. 전체 구성 검증

모든 설치가 완료된 후 최종 상태를 확인합니다.

# 전체 Pod 상태
kubectl get pods -n trino

# 서비스 확인
kubectl get svc -n trino

# PVC 확인
kubectl get pvc -n trino

정상적인 경우 아래처럼 보입니다.

NAME                                  READY   STATUS    RESTARTS   AGE
metastore-db-xxxxxxxxxx-xxxxx         1/1     Running   0          ...
hive-metastore-xxxxxxxxxx-xxxxx       1/1     Running   0          ...
trino-deployment-xxxxxxxxxx-xxxxx     1/1     Running   0          ...

커넥터 연결도 확인합니다.

# Trino CLI로 커넥터 확인
kubectl exec -n trino deploy/trino-deployment -- \
  trino --server http://localhost:8080 \
        --user admin \
        --execute "SHOW CATALOGS;"

Catalog
--------
delta
hive
tpch

즉, 여기서 확인할 수 있는 핵심은

delta / hive / tpch 세 가지 카탈로그가 모두 보이면

Trino + Hive Metastore + PostgreSQL 전체 연동이 완료된 것이라는 점입니다.

마무리

이번 글에서는

Kubernetes 위에서 Trino + Hive Metastore + PostgreSQL 3계층 구조로

Delta Lake SQL 조회 환경을 구축하는 과정을 정리해 봤습니다.

정리하면,

PostgreSQL → Hive Metastore의 메타데이터 영구 저장
Hive Metastore → Delta Lake 테이블 스키마 및 위치 관리
Trino → HMS 참조 + Ceph S3 직접 접근으로 SQL 쿼리 실행

라고 볼 수 있습니다.

특히 이번 구축에서 주의해야 할 포인트는

PostgreSQL Running 확인 후 → Hive Metastore apply
Hive Metastore 스키마 초기화 완료 후 → Trino apply
delta.register-table-procedure.enabled=true 설정 필수
s3.path-style-access=true 설정 필수 (Ceph RGW 연동 시)
ConfigMap 각 파일을 subPath로 정확한 경로에 마운트

이 5가지였습니다.

다음 편에서는

이번에 구축한 Trino 위에서 Airflow로 데이터 파이프라인을 스케줄링하는 방법을 다뤄보겠습니다.

궁금한 점이나 추가로 다뤄줬으면 하는 내용이 있다면 언제든지 편하게 말씀해 주세요!