CI/CDDevOps 학습 로드맵 · 5/28편

yaml 복붙 관리의 드리프트 문제를 Kustomize overlay로 구조화하기

로컬·개발·에어갭 3환경 매니페스트를 복사해서 관리하다 겪은 드리프트 문제부터, Kustomize base/overlay 구조로 옮기는 절차, ArgoCD Application 연동, 드리프트 재발 방지 검증까지.

2026-07-2422 min read
#Kustomize#Kubernetes#GitOps#ArgoCD#환경 분리#Helm#ApplicationSet
DevOps 학습 로드맵시리즈 목차
1채용공고 요구사항 6개 중 자신 있게 답할 수 있는 게 절반도 안 됐다2kubeadm으로 온프레미스 Kubernetes 클러스터를 처음부터 세우는 절차3FastAPI 서비스 골격, RabbitMQ DLQ, Harbor+Trivy, Jenkins→ArgoCD 파이프라인 구축 절차4Argo Rollouts로 카나리 배포와 Prometheus 메트릭 기반 자동 롤백 붙이기5yaml 복붙 관리의 드리프트 문제를 Kustomize overlay로 구조화하기6Terraform과 Ansible로 클러스터를 코드에서 다시 세울 수 있게 만드는 절차7Prometheus·Loki·OpenTelemetry로 세운 관측 스택 - 메트릭·로그·트레이스를 하나로8관측 스택이 진짜로 장애를 잡는가 - 노드 다운·OOMKill·디스크풀 직접 주입해보기9SLI/SLO/에러 버짓을 실제로 계산해서 배포 판단 기준으로 써보기10임계값 없이 - 통계 기반 이상탐지로 Datadog Watchdog 흉내내기11Grafana OnCall로 PagerDuty 없이 온콜·에스컬레이션 구현하기12자체 JWT 구현부터 취약점 실험, Keycloak 마이그레이션까지의 실제 절차13ISMS-P 인프라 영역 심사를 가정하고 내 클러스터의 증적을 만드는 절차14SealedSecret이 못 남기는 것 - OpenBao + External Secrets Operator로 감사 로그 확보하기15번외: 더미 워커를 실제 ONNX 추론으로, GPU 스케줄링까지 교체하는 절차16번외: 인터넷을 완전히 끊고도 클러스터가 돌아가는지 - 폐쇄망(에어갭) 시뮬레이션 절차17번외: 부하테스트로 관측 스택을 실전 검증하기 - k6 + HPA + MSA 파이프라인18번외: DORA 4대 지표를 Four Keys로 자동 집계해보기19실무와 다른 4가지를 채우려고 로드맵을 이렇게 짰다20OpenSearch·Loki·Datadog, 로그 스택은 왜 하나로 안 끝나는가21Control-Plane HA는 언제 정당한가 - etcd 쿼럼, kube-vip 페일오버, cordon/drain의 수학22OpenTelemetry는 무엇을 표준화하는가 - Prometheus·Grafana·Loki·Tempo가 실제로 맞물리는 지점23Helm은 템플릿 도구가 아니라 릴리스 버전 관리자다24카나리 배포와 블루그린 배포, 뭐가 다르고 언제 뭘 써야 하는가25SRE는 정확히 무엇을 하는 직군인가 - '운영을 소프트웨어 문제로 본다'는 말의 실체26온콜은 왜 필요하고, 어떻게 지속 가능하게 운영하는가27IaC는 한 계층이 아니다 - Terraform·Packer·Helm이 각각 다루는 것, 그리고 RKE2 vs kubeadm28SLI·SLO·에러 버짓과 온콜·에스컬레이션 - 숫자로 문제를 정의하고 사람에게 연결하기

목표

이 로드맵은 환경을 로컬·개발·에어갭 3개로 나눠 운영하는데, 지금까지는 환경별로 매니페스트 디렉토리를 통째로 복사해서 관리하고 있었다 - k8s/local/, k8s/dev/, k8s/airgap/ 세 폴더에 거의 동일한 yaml이 중복돼 있는 구조다. 이 시리즈는 그 복붙 관리가 실제로 어떤 문제(드리프트)를 만드는지 겪어보고, Kustomize의 base/overlay 구조로 옮겨 그 문제를 구조적으로 없애는 절차를 다룬다.

개념: 설정 드리프트(Config Drift)란 무엇인가

드리프트는 "같아야 할 설정이 시간이 지나며 조금씩 달라지는 것"을 말한다. 환경별로 yaml을 복사해서 관리하면, 공통으로 고쳐야 할 부분(예: 리소스 요청량, 헬스체크 경로)을 수정할 때마다 3개 파일을 전부 손으로 고쳐야 한다. 사람이 하는 일이라 언젠가 한 곳을 빠뜨리게 되고, 그 순간부터 "왜 개발 환경에서는 되는데 에어갭에서는 안 되지?"라는 질문이 생긴다 - 코드가 문제가 아니라 환경 설정이 몰래 갈라져 있어서 생기는 장애다.

Kustomize는 이 문제를 "공통 부분(base)과 환경별 차이(overlay)를 분리"하는 방식으로 푼다. base에는 모든 환경이 공유하는 원본 매니페스트만 두고, 각 환경은 base를 그대로 참조하면서 자신에게 필요한 차이만 patch로 얹는다. 복붙이 아니라 참조이므로, base를 고치면 모든 환경에 자동으로 반영된다 - 드리프트가 애초에 발생할 수 없는 구조가 된다.

방식공통 설정 변경 시환경별 차이
yaml 복붙 (기존)N개 파일을 전부 손으로 수정 - 누락 위험파일 전체가 환경마다 별도로 존재
Kustomize overlaybase 1곳만 수정 - 모든 환경에 자동 반영patch로 차이만 명시적으로 선언

Kustomize vs Helm - 어떤 상황에 어떤 도구를 쓰는가

Kustomize를 고르기 전에 반드시 짚어야 할 질문이 있다 - "왜 Helm이 아닌가?" 둘은 같은 문제(환경별 매니페스트 차이)를 완전히 다른 방식으로 푼다.

  • Helm은 템플릿 엔진이다. {{ .Values.replicaCount }} 같은 placeholder를 원본 yaml에 박아두고, 환경별 values.yaml로 채워서 렌더링한다. 원본 yaml은 이미 순수한 Kubernetes 매니페스트가 아니라 Go 템플릿 문법이 섞인 반쪽짜리 yaml이 된다.
  • Kustomize는 patch 엔진이다. base yaml은 처음부터 끝까지 순수한 Kubernetes 매니페스트 그대로다. 환경별 차이는 원본을 건드리지 않고 밖에서 strategic merge patch/JSON patch로 얹는다.

이 차이가 실무에서 갈리는 지점은 명확하다.

상황유리한 도구이유
환경별로 값만 몇 개 다르고 구조는 동일 (이번 케이스)Kustomizebase가 원본 yaml 그대로 유지되어 kubectl apply -f로도 검증 가능, 학습 곡선이 낮음
조건 분기가 필요 (예: ingress 유무, replica 수에 따라 PDB 생성 여부 등)Helm{{ if }} 같은 조건문·반복문을 yaml 안에서 표현 가능, Kustomize에는 조건 분기 자체가 없음
외부에 배포 가능한 패키지로 재사용 (차트 배포, 버전 태깅)Helm차트 저장소(repo)로 패키징/버전 관리가 표준화돼 있음, helm install로 제3자가 즉시 설치
사내 3환경처럼 내부 전용, 배포 대상이 고정Kustomize패키징 오버헤드 없이 Git만으로 충분, ArgoCD가 네이티브로 지원

이번 시리즈에서 Kustomize를 택한 이유는 단순하다 - 로컬·개발·에어갭 3환경은 조건 분기가 필요한 게 아니라 값이 다른 것뿐이고, 외부에 배포할 패키지도 아니다. 복잡한 템플릿 문법을 새로 배우는 대신 원본 yaml을 그대로 두고 차이만 선언하는 쪽이 유지보수 비용이 낮다. (참고로 둘을 같이 쓰는 것도 가능하다 - Helm chart를 렌더링한 결과물을 Kustomize base로 삼아 후처리하는 helm template | kustomize build 조합도 실무에서 종종 쓰인다.)

실제 구축 절차

1. 기존 복붙 구조 확인 - 어디가 실제로 갈라져 있는지 먼저 찾는다

Kustomize로 옮기기 전에, 지금 세 환경의 yaml이 실제로 어디서 다른지부터 diff로 확인한다. 이 작업 자체가 "우리가 인지하지 못한 드리프트가 이미 있었는지"를 드러낸다.

diff -r k8s/local/ k8s/dev/
diff -r k8s/dev/ k8s/airgap/

여기서 나오는 차이는 크게 두 종류로 갈린다 - 의도한 차이(에어갭 환경만 이미지 레지스트리가 harbor.local인 것 등)와 의도하지 않은 차이(누군가 dev에서만 리소스 limit을 고치고 다른 환경엔 반영 안 한 것). 후자를 발견하는 순간이 바로 "복붙 관리의 대가"를 실감하는 지점이다.

2. base 추출 - 공통 매니페스트만 남긴다

세 환경에서 공통인 부분만 뽑아 base/로 옮긴다. 여기엔 환경별로 달라지는 값(이미지 레지스트리, replica 수, context-path 등)을 넣지 않는다 - 넣는 순간 base가 다시 특정 환경에 종속된다.

k8s/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   └── configmap.yaml
└── overlays/
    ├── local/
    ├── dev/
    └── airgap/
# k8s/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml

3. overlay 작성 - 환경별 차이만 patch로 선언

각 overlay는 base를 참조(resources: [../../base])하면서, 자신에게 필요한 차이만 patch로 얹는다.

# k8s/overlays/airgap/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
images:
  - name: api-server
    newName: harbor.local/proxy-cache/api-server   # 에어갭만 내부 미러 레지스트리 사용
patches:
  - target:
      kind: Deployment
      name: api-server
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 5
  - path: configmap-patch.yaml
# k8s/overlays/airgap/configmap-patch.yaml - context-path 등 에어갭 전용 값만 override
apiVersion: v1
kind: ConfigMap
metadata:
  name: api-server-config
data:
  EXTERNAL_API_HOST: "localhost:8081"   # 에어갭 환경은 내부 API를 path prefix로 우회
# 렌더링 결과 미리보기 - 실제 적용 전에 최종 yaml이 의도대로 나오는지 확인
kustomize build k8s/overlays/local/
kustomize build k8s/overlays/dev/
kustomize build k8s/overlays/airgap/

kustomize build는 base와 patch를 합쳐 최종 yaml을 출력만 할 뿐 클러스터에 아무것도 적용하지 않는다 - 세 환경의 렌더링 결과를 나란히 비교해서 의도한 차이만 남아있는지, 실수로 base 내용이 깨지지 않았는지 눈으로 검증할 수 있다.

overlay가 늘어나면 생기는 역설 - "또 다른 복붙 관리"

overlay 구조로 옮기고 나면 안심하기 쉽지만, 환경이 늘어나거나 요구사항이 세분화되면 새로운 함정이 생긴다. overlay마다 patch를 계속 쌓다 보면 어느 순간 각 overlay의 patch 목록이 base보다 길어지고, patch끼리 내용이 겹치기 시작한다 - 이건 yaml 파일 전체를 복붙하던 것과 본질적으로 같은 문제다. 다만 이번엔 "파일"이 아니라 "patch"가 복붙되는 것뿐이다.

실제로 나타날 수 있는 증상:

  • 세 overlay에 거의 동일한 patch가 반복된다 (예: 세 환경 모두 resources.limits를 같은 값으로 override)
  • base를 한 번 고치면 여러 overlay의 patch가 base와 충돌하거나 무의미해진다
  • 새 환경을 추가할 때마다 기존 overlay의 patch를 통째로 복사해서 시작한다

이걸 막기 위해 정한 관례:

  1. 두 개 이상의 overlay가 같은 patch를 필요로 하면, 그 patch는 overlay가 아니라 base와 overlay 사이의 공유 계층으로 끌어올린다. Kustomize는 Component 리소스로 여러 overlay가 재사용할 patch 묶음을 base 근처에 따로 둘 수 있다.

    # k8s/components/common-resources/kustomization.yaml
    apiVersion: kustomize.config.k8s.io/v1alpha1
    kind: Component
    patches:
      - target:
          kind: Deployment
        patch: |-
          - op: replace
            path: /spec/template/spec/containers/0/resources/limits/memory
            value: 512Mi
    
    # overlay에서는 patch를 복붙하지 않고 component를 참조만 한다
    components:
      - ../../components/common-resources
    
  2. overlay의 patch는 "그 환경에만 존재하는 이유가 있는 값"만 담는다. replica 수처럼 정말 환경마다 다른 값은 overlay에 남기고, 리소스 limit처럼 사실은 전체 공통이어야 하는 값은 base(또는 component)로 되돌린다.

  3. overlay의 patch 개수가 늘어나는 걸 정기적으로 점검한다. patch가 5개, 10개를 넘어가면 "이 중 몇 개가 실제로 이 환경만의 차이인가"를 다시 diff로 확인한다 - 1번 절차에서 복붙 구조를 걷어낼 때와 같은 방식이다.

핵심은 "overlay가 있으니 안전하다"가 아니라, overlay 안에서도 여전히 중복이 쌓일 수 있다는 것을 인지하고 주기적으로 base(혹은 component)로 끌어올리는 리팩터링을 계속하는 것이다.

4. ArgoCD Application에 Kustomize 연동

시리즈 2에서 만든 ArgoCD GitOps 배포에 Kustomize를 편입한다. Application의 source.path가 overlay 디렉토리를 가리키게만 바꾸면, ArgoCD가 자동으로 kustomize build를 실행해서 그 결과를 배포한다 - 별도 빌드 스크립트가 필요 없다.

# argocd-application-airgap.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: api-server-airgap
spec:
  source:
    repoURL: https://git.internal/infra-manifests.git
    path: k8s/overlays/airgap
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true   # 클러스터에서 누가 kubectl로 직접 고쳐도 Git 상태로 되돌림

selfHeal: true가 이 구조의 마지막 조각이다 - Kustomize로 드리프트를 구조적으로 없앴어도, 누군가 클러스터에 kubectl edit으로 직접 손을 대면 Git과 실제 상태가 다시 갈라질 수 있다. ArgoCD의 self-heal은 그 수동 변경을 감지해 Git에 선언된 상태로 자동으로 되돌린다 - "설정 소스는 Git 하나뿐"이라는 원칙을 배포 이후에도 강제하는 셈이다.

5. ApplicationSet으로 멀티 환경 확장

지금은 환경이 3개뿐이라 Application 리소스를 환경마다 손으로 만드는 게 그럭저럭 버틸 만하다. 하지만 환경이 늘어나면 이 방식 자체가 다시 복붙 관리다 - Application yaml 여러 개를 거의 동일하게 복사해서 이름과 source.path만 바꾸는 구조는, 애초에 이 시리즈에서 없애려던 문제와 똑같다.

ApplicationSet은 하나의 템플릿과 generator로 여러 Application을 자동으로 생성한다. overlay 디렉토리 구조를 그대로 generator 입력으로 쓰면, 새 환경을 추가할 때 overlays/ 아래에 디렉토리 하나만 만들면 ArgoCD가 나머지를 처리한다.

# argocd-applicationset.yaml
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: api-server
spec:
  generators:
    - git:
        repoURL: https://git.internal/infra-manifests.git
        revision: main
        directories:
          - path: k8s/overlays/*   # overlays 밑 디렉토리 하나당 Application 하나 생성
  template:
    metadata:
      name: 'api-server-{{path.basename}}'
    spec:
      source:
        repoURL: https://git.internal/infra-manifests.git
        targetRevision: main
        path: '{{path}}'
      destination:
        server: https://kubernetes.default.svc
        namespace: '{{path.basename}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

git: directories generator는 지정한 glob에 매칭되는 디렉토리를 스캔해서 디렉토리마다 Application을 하나씩 만든다 - overlays/local, overlays/dev, overlays/airgap 세 개가 자동으로 세 개의 Application이 된다. 새 환경(overlays/staging 등)을 추가하면 ApplicationSet 컨트롤러가 다음 리컨실 주기에 자동으로 네 번째 Application을 만든다 - Application yaml을 손으로 추가하거나 실수로 하나를 빠뜨릴 위험이 없어진다.

(멀티 클러스터로 확장할 때는 cluster generator를 함께 쓴다 - 등록된 클러스터 목록을 순회하며 클러스터마다 Application을 생성하는 방식으로, "환경"과 "클러스터"라는 두 축이 늘어나도 관리 대상은 ApplicationSet 하나로 유지된다.)

6. 드리프트 재발 방지 - CI에서 먼저 잡고, 배포 후에는 ArgoCD가 잡는다

드리프트를 막는 지점은 두 군데다 - 배포되기 전(CI)과 배포된 후(ArgoCD). 하나만으론 부족하다.

CI: kustomize build 결과를 diff로 검사

PR에서 overlay나 base를 수정하면, merge되기 전에 렌더링 결과가 의도한 대로 바뀌었는지 자동으로 확인한다. 방법은 두 가지를 병행한다.

# (1) 이전 커밋 대비 렌더링 결과 diff - "의도한 변경만 있는가"를 리뷰어가 눈으로 확인
git worktree add /tmp/prev-tree HEAD~1 -q
for env in local dev airgap; do
  kustomize build k8s/overlays/$env/ > /tmp/new-$env.yaml
  kustomize build /tmp/prev-tree/k8s/overlays/$env/ > /tmp/old-$env.yaml
  diff /tmp/old-$env.yaml /tmp/new-$env.yaml
done

# (2) 실제 클러스터 상태 대비 diff - "Git과 클러스터가 이미 갈라져 있는가"를 배포 전에 확인
kustomize build k8s/overlays/airgap/ | kubectl diff -f - -n airgap

(1)은 "이 PR이 실제로 무엇을 바꾸는지"를 사람이 리뷰하기 쉽게 만든다 - patch 몇 줄만 보고는 최종적으로 어느 필드가 바뀌는지 알기 어렵지만, 렌더링된 최종 결과의 diff는 명확하다. (2)는 kubectl diff의 dry-run 비교 기능을 이용해서 "누군가 클러스터를 직접 고쳐놔서 이번 배포가 예상 못한 곳까지 덮어쓰는" 상황을 병합 전에 미리 드러낸다. 둘 다 CI 파이프라인에 넣어 PR 단계에서 결과를 노출시키면, 드리프트가 배포되기도 전에 걸러진다.

ArgoCD: 자체 drift 감지 - 자동 sync와 manual sync 중 무엇을 쓸까

CI를 통과해도 배포 이후에 누군가 kubectl edit으로 직접 손을 대는 경로는 막을 수 없다. 이건 ArgoCD의 몫이다. ArgoCD는 주기적으로 클러스터의 실제 상태와 Git에 선언된 상태를 비교해서 OutOfSync로 표시하는데, 이걸 감지했을 때 자동으로 되돌릴지(automated.selfHeal) 사람이 확인 후 눌러야 되돌릴지(manual)는 환경마다 다르게 정했다.

환경sync 정책이유
local, devautomated: { selfHeal: true }실험적 변경이 잦고, 잘못된 수동 변경을 즉시 되돌려도 리스크가 낮음
airgapmanual sync (automated 미설정)망분리 특성상 배포 자체가 신중해야 하고, 되돌리기 전에 "왜 클러스터가 Git과 달라졌는지" 원인 파악이 먼저 필요할 수 있음 - 자동 되돌림이 오히려 조사 흔적을 지워버릴 위험

자동 sync는 "Git이 유일한 소스"라는 원칙을 강하게 지키지만, 되돌리는 순간 클러스터의 이전 상태(누가 왜 손을 댔는지)가 사라진다. 재배포 자체가 비용이 큰 에어갭 같은 환경에서는, 일단 OutOfSync 알림만 받고 사람이 원인을 확인한 뒤 수동으로 sync하는 쪽이 더 안전하다.

local/dev처럼 selfHeal이 켜진 환경에서는 실제로 되돌아오는지를 다음과 같이 검증한다.

# 의도적으로 클러스터에 직접 변경을 가한 뒤
kubectl scale deployment api-server -n dev --replicas=99

# ArgoCD가 감지해 Git 선언 값으로 되돌리는지 확인
argocd app get api-server-dev --refresh

airgap처럼 manual sync인 환경에서는 같은 변경을 가했을 때 자동으로 되돌아가지 않고 OutOfSync 상태로 남아 있는지, 그리고 argocd app diff로 무엇이 달라졌는지 확인할 수 있는지를 검증한다.

검증 방법

  • 3환경의 kustomize build 렌더링 결과를 diff로 비교해, 의도한 차이만 남아있는지 확인
  • base를 수정했을 때 3환경 모두에 자동으로 반영되는지 확인 (환경별로 따로 고치지 않아도 됨)
  • 클러스터에 수동으로 가한 변경이 ArgoCD self-heal로 Git 선언 상태로 자동 복구되는지 확인 (local/dev)
  • manual sync 환경(airgap)은 같은 변경이 자동으로 복구되지 않고 OutOfSync로 노출되는지 확인
  • 1번 절차에서 발견한 "의도하지 않은 차이"가 overlay 구조로 옮긴 뒤 문서화된 patch로 명시됐는지 확인
  • overlay별 patch 목록을 주기적으로 점검해, 두 개 이상 overlay에 중복되는 patch가 base/component로 승격됐는지 확인
  • ApplicationSet이 overlays 디렉토리 추가/삭제에 맞춰 Application을 정확히 생성/제거하는지 확인
  • CI에서 kustomize build 결과가 이전 커밋 diff + 클러스터 상태 diff로 PR 단계에 노출되는지 확인

체크리스트

  • 기존 3환경 yaml을 diff로 비교해 의도한 차이/의도하지 않은 차이 구분
  • 공통 매니페스트를 base로 추출
  • 환경별 차이를 overlay patch로 분리 (이미지 레지스트리, replica 수, 설정값 등)
  • Helm 대신 Kustomize를 선택한 이유(조건 분기 불필요, 원본 yaml 유지) 문서화
  • kustomize build로 3환경 렌더링 결과 사전 검증
  • ArgoCD Application의 source.path를 overlay로 전환
  • overlay별 patch 중복을 점검해 공통 patch를 base/Component로 승격
  • ApplicationSet generator로 환경별 Application 자동 생성 전환
  • CI 파이프라인에 kustomize build diff 검사(이전 커밋 대비 + 클러스터 상태 대비) 추가
  • 환경별 automated selfHeal / manual sync 정책 결정 및 적용
  • selfHeal 활성화 후 수동 변경이 자동 복구되는지 검증