Post

[로컬 레이크하우스 #7] GitOps 저장소 구조 읽기 — apps/ · values/ · manifests/와 오퍼레이터 패턴, CloudNativePG 설치

📚 들어가며

6편에서 SeaweedFS(S3) 점검을 마쳤다. 다음은 Lab 4, Polaris 카탈로그가 쓸 PostgreSQL이다.

그런데 Lab 4부터 저장소의 모양이 달라진다. 지금까지는 apps/에 Application 하나, values/에 설정 파일 하나를 두면 됐다. Lab 4부터는 manifests/ 아래 폴더를 가리키는 Application이 섞여 나오기 시작한다. 그래서 Lab 4를 시작하기 전에 “어떤 건 apps/, 어떤 건 manifests/, 어떤 건 values/로 가는 이유” 를 먼저 정리했다. 가이드에는 따로 없는 장이다.

  • 결국 전부 YAML이다. Argo CD가 클러스터에 apply하는 것은 일반 Kubernetes YAML이다. Helm과 Kustomize는 그 YAML을 만드는 데에만 쓰인다.
  • 주문서와 재료. apps/는 Argo CD에게 주는 주문서, values/와 manifests/는 그 주문서가 가리키는 재료다. manifests/tools/와 jobs/는 일부러 Argo CD 밖에 둔다.
  • 오퍼레이터 + 인스턴스. 앞으로 반복될 패턴은 “오퍼레이터는 Helm으로 설치하고, 인스턴스(CR)는 manifests/에 직접 쓴다”이다. 이번 편에서 첫 오퍼레이터인 CloudNativePG를 설치한다.

이번 편 학습 지도

1
2
3
4
5
6
저장소 구조 (1~4장)                  오퍼레이터 (5장)                CNPG 설치 (6장)
───────────────────                  ────────────────                ───────────────
apps/ = 주문서, values·manifests = 재료  CRD = 새 kind 등록              single source, values 없음
Helm 타입 11 · Git 디렉터리 타입 4 🔦   오퍼레이터 = 운영 지식의 코드      CRD 11개 등록
repo-server: template · build · 읽기    오퍼레이터(Helm) ➡ 인스턴스(CR) 🔦  ServerSideApply 🔦
tools/ · jobs/는 일부러 밖에            순서: CRD가 먼저                  clusters CRD 275KB

1. 저장소의 디렉터리별 역할

정답 저장소의 Application 15개 파일을 전부 열어 분류해 봤다. 결론부터 적으면 이렇다. 디렉터리마다 역할이 다르다. apps/는 주문서이고, values/와 manifests/는 그 주문서가 가리키는 재료다.

디렉터리들어 있는 것누가 쓰나클러스터에 직접 apply되나
bootstrap/루트 앱(root.yaml) 하나나 (kubectl apply 최초 1회)✅
apps/Application (주문서)root 앱이 감시✅ (Application 리소스로)
values/Helm values overrideHelm 타입 Application이 $values/...로 참조❌ 재료일 뿐
manifests/<컴포넌트>/일반 K8s YAMLGit 디렉터리 타입 Application이 path:로 참조✅ (Argo CD가)
manifests/tools/점검용 Pod (toolbox 등)나 (kubectl apply)✅ (손으로)
jobs/1회 실행 Job, SparkApplication나 (kubectl apply)✅ (손으로)
flowchart TB
    ME["나"]
    ME -->|"최초 1회"| BOOT["bootstrap/root.yaml"]
    BOOT -->|"감시"| APPS["apps/<br>주문서 (Application)"]
    APPS -->|"$values/... 참조"| VAL["values/<br>Helm 설정값 (재료)"]
    APPS -->|"path: 참조"| MAN["manifests/컴포넌트/<br>내가 쓴 K8s YAML (재료)"]
    VAL --> ARGO["Argo CD가 apply"]
    MAN --> ARGO
    ME -->|"손으로 kubectl apply"| TOOLS["manifests/tools/<br>jobs/"]

    style APPS fill:#EF7B4D,color:#fff
    style VAL fill:#3a3a1a,color:#fff
    style MAN fill:#3a3a1a,color:#fff
    style TOOLS fill:#1a2a3a,color:#fff

values/ 파일은 Kubernetes 리소스가 아니다. kind:가 없는 설정값 묶음일 뿐이라 혼자서는 apply할 수 없다. Helm 차트와 합쳐져야 의미가 생긴다.

4편 3-4에서 “values/metrics-server.yaml을 helm으로 설치해야 하나?” 하고 헷갈렸던 이유가 여기서 풀린다. values/는 디렉터리 이름만 보면 설치할 것들이 모인 곳 같지만, 실제로는 재료 창고다.


2. Application의 두 가지 타입

정답 저장소의 Application 15개를 소스 종류로 나누면 두 종류뿐이다.

flowchart LR
    ALL["Application 15개"] --> A["A. Helm 타입 — 11개<br>외부 차트 + values/"]
    ALL --> B["B. Git 디렉터리 타입 — 4개<br>manifests/폴더"]
    A --> A1["남이 만든 소프트웨어 설치"]
    B --> B1["차트 없이 내가 쓴 리소스"]

    style A fill:#5A45FF,color:#fff
    style B fill:#00875A,color:#fff

2-1. A. Helm 타입 — 외부 차트 + values/

남이 만든 소프트웨어를 설치할 때 쓴다.

Application차트소스
metrics-servermetrics-servermulti-source
seaweedfsseaweedfsmulti-source
cnpg-operatorcloudnative-pgsingle source
polarispolarismulti-source
spark-operatorspark-operatormulti-source
trinotrinomulti-source
strimzi-operatorstrimzi-kafka-operatormulti-source
kube-prometheus-stackkube-prometheus-stackmulti-source
lokilokimulti-source
alloyalloymulti-source
airflowairflowmulti-source

대부분 4편에서 본 multi-source다. 첫 번째 소스는 차트 저장소, 두 번째 소스는 내 Git 저장소(ref: values)이고, $values/values/xxx.yaml로 설정을 끼워 넣는다.

1
2
3
4
5
6
7
8
9
10
# A. Helm 타입 (예: apps/seaweedfs.yaml, 5편)
sources:
  - repoURL: https://seaweedfs.github.io/seaweedfs/helm   # 차트 저장소
    chart: seaweedfs
    targetRevision: 4.53.0
    helm:
      valueFiles: [$values/values/seaweedfs.yaml]          # ← values/ 참조
  - repoURL: https://github.com/<GITHUB_ID>/lakehouse-lab.git
    targetRevision: main
    ref: values

예외는 cnpg-operator 하나다. 차트 기본값으로 충분해서 values 파일 없이 single source다(6장).

2-2. B. Git 디렉터리 타입 — manifests/<폴더>

차트가 없는, 내가 직접 쓴 리소스를 배포할 때 쓴다.

Application경로안에 있는 것
polaris-dbmanifests/polaris-dbCNPG Cluster
airflow-dbmanifests/airflowCNPG Cluster, RBAC
kafkamanifests/kafkaStrimzi Kafka, KafkaTopic, 이벤트 생성기
monitoring-extrasmanifests/monitoringPodMonitor, 알림 규칙, 대시보드 ConfigMap (Kustomize)
1
2
3
4
5
# B. Git 디렉터리 타입 (예: apps/polaris-db.yaml, 다음 편에서 사용)
source:
  repoURL: https://github.com/<GITHUB_ID>/lakehouse-lab.git
  targetRevision: main
  path: manifests/polaris-db        # ← 이 폴더의 YAML 전부

chart: 대신 path: 가 있다. 이 폴더 안의 YAML을 전부 배포하라는 뜻이다. 4편의 루트 앱도 path: apps였으니, 사실 루트 앱도 이 타입이다.

15개 모두 syncOptions에 ServerSideApply=true가 들어 있다. 4편 3-6에서 “모든 앱에 같은 틀을 쓰려고 넣어 둔 것”이라고 했는데, 정답 저장소 전체가 실제로 그렇게 되어 있다.


3. Argo CD 내부에서 일어나는 일 — 결국 전부 YAML

3-1. 🔦 repo-server가 YAML을 만들고, application-controller가 apply한다

Argo CD의 repo-server가 소스 종류를 보고 알맞은 도구로 YAML을 만든다. 그다음 application-controller가 Git에서 만든 YAML과 클러스터의 현재 상태를 비교(diff)하고 apply한다. 세 경우 모두 이 뒷부분은 똑같다.

flowchart LR
    SRC["Application 소스"]
    SRC -->|"chart: 가 있음"| H["helm template<br>(+ values 파일)"]
    SRC -->|"path: 에 kustomization.yaml"| K["kustomize build"]
    SRC -->|"path: 에 YAML만"| D["폴더의 YAML을<br>그대로 읽음"]
    H --> Y["일반 K8s YAML"]
    K --> Y
    D --> Y
    Y --> C["Git의 YAML vs 클러스터<br>비교 → apply"]

    subgraph RS["repo-server"]
      H
      K
      D
    end
    subgraph AC["application-controller"]
      C
    end

    style Y fill:#5A45FF,color:#fff
    style RS fill:#1a2a3a,color:#fff
    style AC fill:#3a1a1a,color:#fff

Helm이든 Kustomize든 YAML을 만드는 도구일 뿐이고, apply는 Argo CD가 한다.

3-2. 그래서 보이는 것들

현상이유
Helm으로 설치한 앱이 helm list에 안 나온다 (4편 3-5에서 확인)Argo CD는 helm install을 실행하지 않는다. helm template으로 YAML만 만들어 직접 apply한다
Argo CD 자체만 helm list에 나온다 (3편)그것만 내가 helm install로 설치했다
manifests/monitoring/에 kustomization.yaml이 있다Argo CD가 이 파일을 발견하면 Kustomize로 처리한다. 그 안의 configMapGenerator가 Grafana 대시보드 JSON을 ConfigMap으로 만들어 준다(Lab 9 예정)

정답 저장소의 manifests/monitoring/에는 kustomization.yaml, podmonitors.yaml, rules.yaml, 그리고 dashboards/ 폴더가 있다. 대시보드 JSON 파일을 그대로 두고, Kustomize가 ConfigMap으로 감싸 주는 구조다.

3장의 렌더링 경로는 Argo CD 문서를 기준으로 정리한 것이다. helm list에 argocd만 나오는 것은 4편에서 직접 확인했다.


4. manifests/tools/와 jobs/가 Argo CD 밖에 있는 이유

정답 저장소의 Application 15개 중 어느 것도 manifests/tools/나 jobs/를 가리키지 않는다. 일부러 뺀 것이다.

디렉터리들어 있는 것Argo CD에 넣으면
manifests/tools/toolbox.yaml, spark-shell.yaml, kafka-client.yaml필요할 때 띄웠다가 지우는 점검 도구다. Argo CD가 관리하면 지워도 selfHeal 때문에 다시 살아난다
jobs/polaris-bootstrap.yaml, spark-pi.yaml, iceberg-basics.yaml 등 7개한 번 실행하고 끝나는 작업이다. 동기화할 때마다 다시 실행되거나, 실패한 Job이 쌓인다
flowchart TB
    subgraph IN["Argo CD 안 — 계속 유지해야 하는 것"]
      I1["SeaweedFS · PostgreSQL · Kafka …"]
      I2["지우면 → selfHeal로 되살림 ✅"]
    end
    subgraph OUT["Argo CD 밖 — 잠깐 쓰거나 한 번 실행하는 것"]
      O1["toolbox · spark-shell · Job"]
      O2["지우면 → 그냥 사라짐 ✅<br>(Argo CD에 있었다면 되살아남 ❌)"]
    end

    style IN fill:#0a3a1a,color:#fff
    style OUT fill:#1a2a3a,color:#fff

6편에서 toolbox를 kubectl apply로 띄운 이유가 이것이다. 가이드 Lab 5에서도 Polaris 부트스트랩 Job을 Argo CD에 넣지 않은 이유로 같은 점을 설명한다.

새 파일을 어디에 둘지 고르는 기준

만들려는 것둘 곳
Helm 차트가 있는 소프트웨어 설치apps/xxx.yaml (Helm 타입) + values/xxx.yaml
차트 없이 내가 쓰는 리소스를 GitOps로 관리manifests/xxx/ + apps/xxx.yaml (Git 디렉터리 타입)
잠깐 쓰는 점검 Podmanifests/tools/ → kubectl apply
한 번 실행하고 끝나는 작업jobs/ → kubectl apply

5. 오퍼레이터 패턴 — 운영 지식을 코드로 만든 것

5-1. CRD와 오퍼레이터

CRD(Custom Resource Definition) 는 Kubernetes에 새 리소스 종류(kind)를 등록하는 것이다. 예를 들어 CNPG CRD를 설치하면 kind: Cluster(postgresql.cnpg.io/v1)를 Pod나 Service처럼 쓸 수 있다. 4편 1-1에서 Argo CD가 Application을 추가한 것과 같은 방식이다.

오퍼레이터(Operator) 는 CRD로 만든 리소스(CR)를 계속 감시하면서, 적힌 대로 실제 리소스를 만들고 유지하는 컨트롤러 프로그램이다. “PostgreSQL 2대짜리 클러스터”라는 요청서를 읽고 Pod·디스크·계정·복제·장애 조치를 알아서 처리한다. DBA가 하던 운영 지식을 코드로 만든 것이다.

flowchart LR
    CR["CR (요청서)<br>kind: Cluster<br>instances: 2"] -->|"감시"| OP["오퍼레이터<br>(CNPG)"]
    OP -->|"만들고 유지"| R1["Pod · PVC"]
    OP --> R2["Service"]
    OP --> R3["Secret (계정)"]
    OP --> R4["복제 · failover"]
    R1 -.->|"실제 상태"| OP

    style CR fill:#00875A,color:#fff
    style OP fill:#5A45FF,color:#fff

5-2. 🔦 오퍼레이터는 Helm 타입, 인스턴스는 Git 디렉터리 타입

2장의 Git 디렉터리 타입 폴더에 들어 있는 것은 대부분 오퍼레이터에게 보내는 요청서(CR) 다. 그래서 Helm 타입 앱과 짝을 이룬다.

오퍼레이터 설치 (Helm 타입)➡인스턴스 요청 (Git 디렉터리 타입)
cnpg-operator➡polaris-db, airflow-db: “PostgreSQL 클러스터 만들어 줘”
strimzi-operator➡kafka: “Kafka 클러스터와 토픽 만들어 줘”
kube-prometheus-stack➡monitoring-extras: “이 Pod들 메트릭 수집하고 이 조건이면 알림 줘”

이렇게 나누는 이유는 이렇다.

  • 오퍼레이터는 “PostgreSQL을 운영하는 프로그램”이다. 누구나 같은 것을 쓰므로 차트로 설치한다.
  • “어떤 DB를 몇 대로 만들지” 는 환경마다 다르므로 내가 직접 YAML로 쓴다.

4편의 metrics-server와 5편의 SeaweedFS는 “앱 자체” 를 설치한 것이었다. 이번에는 처음으로 “앱을 운영하는 앱” 을 설치한다.

5-3. 순서 주의 — CRD가 먼저다

kind: Cluster는 오퍼레이터가 CRD를 등록해야 생긴다. 오퍼레이터보다 인스턴스를 먼저 apply하면 no matches for kind "Cluster" 같은 오류가 날 것이다.

flowchart LR
    subgraph OK["올바른 순서"]
      direction LR
      O1["cnpg-operator<br>Healthy"] --> O2["CRD 등록됨<br>kind: Cluster 사용 가능"] --> O3["polaris-db<br>apply ✅"]
    end
    subgraph NG["순서가 바뀌면"]
      direction LR
      N1["polaris-db 먼저"] --> N2["no matches for kind<br>Cluster ❌"]
    end

    style O3 fill:#0a3a1a,color:#fff
    style N2 fill:#4a1a1a,color:#fff

그래서 가이드도 cnpg-operator를 먼저 켜고 Healthy가 된 뒤 polaris-db를 켠다.

순서가 바뀌었을 때의 오류 메시지는 예상이다. 일부러 순서를 바꿔 보지는 않았다.


6. CloudNativePG 오퍼레이터 설치

6-1. 왜 오퍼레이터로 PostgreSQL을 만드나

Polaris 카탈로그는 메타데이터(네임스페이스, 테이블 포인터, 권한)를 PostgreSQL에 저장한다. 1편에서 “카탈로그가 테이블의 최신 메타데이터 포인터를 관리한다”고 했는데, 그 포인터가 여기에 들어간다. 이 DB가 죽으면 모든 커밋이 멈춘다.

그래서 직접 StatefulSet으로 만들지 않고, 복제와 failover를 알아서 해 주는 CloudNativePG(CNPG) 오퍼레이터를 쓴다.

6-2. 가이드와 다른 점

 가이드내 practice
앱 켜는 방법apps-disabled/cnpg-operator.yaml을 git mv로 apps/에 옮긴다apps/cnpg-operator.yaml을 직접 작성해 커밋했다 (d3da8ad feat: lab4 cnpg 추가 - app of apps of argocd)
파일 내용—정답지와 같다

4편부터 계속 이 방식이다. 파일 하나하나를 직접 써 보면서 익히려고 한다. 결과는 같다. root 앱이 apps/를 감시하고 있으므로 push하면 cnpg-operator Application이 생긴다.

6-3. Application

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# apps/cnpg-operator.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: cnpg-operator
  namespace: argocd
  finalizers:
    - resources-finalizer.argocd.argoproj.io
spec:
  project: default
  source:
    repoURL: https://cloudnative-pg.github.io/charts
    chart: cloudnative-pg
    targetRevision: 0.29.1      # 오퍼레이터 1.30.1
    helm:
      releaseName: cnpg
  destination:
    server: https://kubernetes.default.svc
    namespace: cnpg-system
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
      # CRD가 커서 client-side apply의 annotation 크기 제한(256KB)에 걸린다
      - ServerSideApply=true
  • 차트 cloudnative-pg 0.29.1 을 설치하면 오퍼레이터 1.30.1이 들어온다. 3편에서 본 “차트 버전 ≠ 앱 버전”이다.
  • source(단수) — values 파일이 없는 single source다. 차트 기본값으로 충분하다.
  • releaseName cnpg, 네임스페이스 cnpg-system. 6-5에서 보는 Deployment 이름 cnpg-cloudnative-pg는 이 releaseName과 차트 이름을 이어 붙인 것이다.

6-4. 🔦 ServerSideApply가 필요한 이유 — CRD가 256KB를 넘는다

 client-side apply (기본)server-side apply
“마지막으로 apply한 내용” 저장kubectl.kubernetes.io/last-applied-configuration annotation에 전체를 저장annotation을 쓰지 않는다
병합 방식클라이언트가 계산API 서버가 필드 단위로 소유자(managedFields)를 관리
큰 리소스annotation 크기 제한(256KB)에 걸린다문제없다
flowchart TB
    CRD["CNPG clusters CRD<br>275,326바이트"]
    CRD --> CSA["client-side apply<br>전체를 annotation에 복사"]
    CSA --> X["annotation 256KB 초과<br>metadata.annotations: Too long ❌"]
    CRD --> SSA["server-side apply<br>managedFields로 관리"]
    SSA --> OK["적용 ✅"]

    style X fill:#4a1a1a,color:#fff
    style OK fill:#0a3a1a,color:#fff

말로만 “CRD가 크다”고 하면 감이 안 와서 실제로 재 봤다.

1
2
3
4
for c in clusters poolers backups; do
  printf "%s " $c
  kubectl get crd $c.postgresql.cnpg.io -o json | jq -c 'del(.metadata.managedFields, .status)' | wc -c
done
1
2
3
clusters   275326
poolers   352086
backups    13113
CRD크기256KiB(262,144바이트)와 비교
clusters275,326바이트넘는다
poolers352,086바이트넘는다
backups13,113바이트여유 있다

clusters 하나만 해도 annotation에 통째로 복사하면 제한을 넘는다. 실제로 이 CRD에는 last-applied-configuration annotation이 없다. server-side apply로 들어갔기 때문이다.

3편 7장의 “막히면” 표에 있던 “metadata.annotations: Too long → ServerSideApply=true“ 가 실제로 필요한 첫 앱이 이것이다.

6-5. 설치와 확인

1
2
3
git add apps/cnpg-operator.yaml && git commit -m "feat: lab4 cnpg 추가" && git push
argocd app get root --refresh >/dev/null && argocd app wait cnpg-operator --health --timeout 300
kubectl get crd | grep cnpg.io

4편에서 쓴 argocd app get root --refresh(Git 변경을 즉시 반영)를 그대로 썼다. 한 번에 Synced/Healthy가 됐다.

1
2
3
4
5
6
7
$ kubectl -n argocd get applications
NAME             SYNC STATUS   HEALTH STATUS
cnpg-operator    Synced        Healthy
metrics-server   Synced        Healthy
polaris-db       Synced        Healthy
root             Synced        Healthy
seaweedfs        Synced        Healthy

출력은 글을 쓰는 시점에 클러스터를 조회한 결과라 polaris-db가 이미 있다. polaris-db는 다음 편에서 다룬다.

1
2
3
$ kubectl -n cnpg-system get deploy
NAME                  READY   UP-TO-DATE   AVAILABLE   IMAGES
cnpg-cloudnative-pg   1/1     1            1           ghcr.io/cloudnative-pg/cloudnative-pg:1.30.1

오퍼레이터는 Deployment 하나, Pod 하나다. 이미지 태그가 1.30.1, 즉 오퍼레이터 버전이다.

6-6. CRD 11개 — 오퍼레이터가 받는 요청서 종류

1
2
3
4
5
6
7
8
9
10
11
12
$ kubectl get crd | grep cnpg.io
backups.postgresql.cnpg.io                Namespaced   v1(storage)
clusterimagecatalogs.postgresql.cnpg.io   Cluster      v1(storage)
clusters.postgresql.cnpg.io               Namespaced   v1(storage)
databaseroles.postgresql.cnpg.io          Namespaced   v1(storage)
databases.postgresql.cnpg.io              Namespaced   v1(storage)
failoverquorums.postgresql.cnpg.io        Namespaced   v1(storage)
imagecatalogs.postgresql.cnpg.io          Namespaced   v1(storage)
poolers.postgresql.cnpg.io                Namespaced   v1(storage)
publications.postgresql.cnpg.io           Namespaced   v1(storage)
scheduledbackups.postgresql.cnpg.io       Namespaced   v1(storage)
subscriptions.postgresql.cnpg.io          Namespaced   v1(storage)

CRD가 11개 등록됐다. 이번 Lab에서 쓰는 것은 clusters 하나지만, PostgreSQL 운영의 거의 모든 일을 CR로 관리할 수 있다는 뜻이다.

분류CRD
클러스터clusters ← 다음 편에서 사용
백업backups, scheduledbackups
커넥션 풀러poolers
DB·롤 선언databases, databaseroles
논리 복제publications, subscriptions
이미지imagecatalogs, clusterimagecatalogs
장애 조치failoverquorums

clusterimagecatalogs만 SCOPE가 Cluster이고 나머지는 Namespaced다. 대부분의 요청서는 네임스페이스 안에 만든다.


📝 이번 편 요약

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
저장소 구조
├─ apps/ = 주문서 (Application), values/ · manifests/ = 재료
├─ values/는 K8s 리소스가 아님 (kind 없음) → 혼자 apply 불가
└─ manifests/tools/ · jobs/ = 일부러 Argo CD 밖 (selfHeal · 재실행 방지)

Application 두 타입 (정답 저장소 15개)
├─ 🔦 A. Helm 타입 11개: 외부 차트 + values/ (cnpg-operator만 single source)
└─ 🔦 B. Git 디렉터리 타입 4개: path: manifests/<폴더>

Argo CD 내부
├─ repo-server: helm template / kustomize build / 폴더 YAML 읽기
├─ → 전부 일반 K8s YAML
└─ application-controller: Git vs 클러스터 비교 → apply (helm list엔 안 나옴)

오퍼레이터 패턴
├─ CRD = 새 kind 등록, 오퍼레이터 = CR을 감시하며 실제 리소스 유지
├─ 🔦 오퍼레이터(Helm 타입) ➡ 인스턴스 CR(Git 디렉터리 타입)
│    cnpg → polaris-db · airflow-db / strimzi → kafka / prometheus → monitoring-extras
└─ 순서: 오퍼레이터(CRD)가 먼저, 인스턴스는 그다음

CNPG 설치
├─ 차트 cloudnative-pg 0.29.1 → 오퍼레이터 1.30.1, cnpg-system
├─ 🔦 ServerSideApply: clusters CRD 275KB > annotation 제한 256KB
└─ CRD 11개 등록 (clusters · backups · poolers · databases …)
개념한 줄 정의
Helm 타입 Application외부 Helm 차트를 소스로 하는 Application. 설정은 values/에서
Git 디렉터리 타입 ApplicationGit 저장소의 폴더(path:)를 소스로 하는 Application
repo-server소스를 받아 Helm·Kustomize 등으로 YAML을 렌더링하는 Argo CD 구성 요소
KustomizeYAML을 템플릿 없이 덧붙이고 변형해서 최종 YAML을 만드는 도구
configMapGenerator파일 내용으로 ConfigMap을 만들어 주는 Kustomize 기능
CRDKubernetes에 새 리소스 종류(kind)를 등록하는 것
CR (Custom Resource)CRD로 만든 kind의 실제 리소스. 오퍼레이터에게 보내는 요청서
오퍼레이터CR을 감시하며 실제 리소스를 만들고 유지하는 컨트롤러
CloudNativePG (CNPG)PostgreSQL 클러스터의 복제·failover·백업을 관리하는 오퍼레이터
client-side apply마지막 apply 내용을 annotation에 저장하고 클라이언트가 병합하는 방식
server-side applyAPI 서버가 필드별 소유자(managedFields)로 병합을 관리하는 방식

💭 느낀 점

1. “주문서와 재료”로 나누니 한 번에 정리됐다.

처음에는 apps/, values/, manifests/가 뒤섞여 보였다. 15개 파일을 다 열어서 분류해 보니 Application은 두 종류뿐이었고, 디렉터리는 주문서와 재료로 나뉘었다. values/라는 이름 때문에 “여기 있는 걸 설치해야 하나?” 했던 4편의 헷갈림도 같이 풀렸다.

2. Helm이든 Kustomize든 결국 YAML을 만드는 도구일 뿐이다.

Argo CD 안에서 Helm은 helm template만 쓰는 렌더링 도구다. Kustomize도 마찬가지다. apply는 언제나 Argo CD가 한다. 이걸 알고 나니 “이 리소스는 누가 관리하나?”라는 질문의 답이 항상 Argo CD라는 게 분명해졌다.

3. 오퍼레이터 = 운영 노하우를 코드로 만든 것.

앞으로 Kafka(Strimzi), 모니터링(Prometheus Operator)도 “오퍼레이터는 Helm으로, 인스턴스는 manifests/에”라는 같은 구조로 나온다. 미리 알아 두니 큰 그림이 보인다. Lab마다 새로운 걸 배우는 게 아니라, 같은 틀에 다른 컴포넌트를 끼우는 것이다.

4. 처음 보는 GitOps 저장소도 이 질문부터 하면 된다.

실무에서 처음 보는 데이터 플랫폼 저장소를 열었을 때도 “이건 Helm 앱인가, Git 디렉터리 앱인가, 손으로 apply하는 건가”부터 구분하면 될 것 같다. 디렉터리 이름은 저장소마다 달라도 이 세 가지 구분은 그대로일 것이다.


🔗 다음 편 예고

CNPG에 Cluster 요청서 한 장(manifests/polaris-db/cluster.yaml)을 보내 PostgreSQL primary 1 + standby 1을 만든다. CNPG가 대신 만들어 주는 Pod·PVC·Service·Secret을 하나씩 확인하고, Polaris가 이 Secret을 어떻게 쓰는지 본다.


📚 참고

1·2·4장의 분류는 정답 저장소의 Application 15개와 manifests/·jobs/ 디렉터리를 직접 열어 확인한 결과다(15개 모두 ServerSideApply=true인 것, 어느 앱도 manifests/tools/·jobs/를 가리키지 않는 것 포함). 6장의 Application 상태, CRD 목록, 오퍼레이터 Deployment, CRD 크기, CRD에 last-applied-configuration annotation이 없는 것은 실제 클러스터에서 확인했다. 3장의 렌더링 경로는 Argo CD 문서 기준이고, 4장의 Lab 5 Job 관련 설명은 가이드 기준이다. 5-3의 순서가 바뀌었을 때의 오류 메시지는 예상이며 직접 실험하지 않았다. 저장소 주소의 GitHub ID는 <GITHUB_ID>로 바꿨다.

This post is licensed under CC BY 4.0 by the author.

Comments powered by Disqus.