Helm 로컬 차트와 Kustomize 오버레이

목표

인터넷 없이 로컬 Helm 차트를 만들어 렌더링·설치·업그레이드하고, Kustomize base/overlay 구조로 같은 매니페스트를 환경별로 변형해 적용할 수 있게 된다.

왜 중요한가

Helm 과 Kustomize 는 접근 방식이 정반대다. Helm 은 템플릿이다. Go 템플릿으로 매니페스트를 문자열 수준에서 만들어 내므로 조건문·반복문 같은 것이 자유롭지만, 렌더링 전에는 유효한 YAML 이 아니다. Kustomize 는 패치다. 이미 유효한 YAML 을 구조적으로 병합하므로 항상 유효한 결과가 나오지만, 표현할 수 있는 변형의 폭은 좁다.

둘 다 리비전 개념을 갖는다는 점은 같다. Helm 은 릴리스 리비전을 네임스페이스 안 Secret 으로 쌓고, Kustomize 는 Git 커밋이 그 역할을 한다. 그래서 Helm 은 helm rollback 이 있고 Kustomize 는 git revert 후 다시 적용한다.

helm template 을 습관으로 만드는 것이 중요하다. 설치 전에 무엇이 만들어질지 확인하는 유일한 방법이고, CI 에서 매니페스트를 검사하는 지점이기도 하다. 시험장에서도 "이 차트가 뭘 만드는지 확인하라" 류 문제가 나온다.

이 실습 환경에는 인터넷이 없다. helm repo add 는 동작하지 않는다. 실무에서도 폐쇄망 환경은 흔하고, 그때는 차트를 tgz 로 반입하거나 로컬 경로로 설치한다. 여기서 연습하는 방식이 바로 그것이다.

단계

1. helm create /root/ckad-pkg/webapp 으로 차트를 만든다. (필요하면 /root/ckad-pkg 디렉터리를 먼저 만든다.)
2. /root/ckad-pkg/webapp/values.yaml 을 고친다. replicaCount: 3, image.repository: nginx, image.tag: "1.27", service.type: NodePort, service.port: 8080.
3. helm template webapp /root/ckad-pkg/webapp 결과를 /root/ckad-pkg/rendered.yaml 에 저장한다.
4. 로컬 차트 경로를 그대로 지정해, 네임스페이스 ckad-pkg 에 릴리스 이름 webapp 으로 설치한다. 네임스페이스는 미리 만들어도 되고 설치할 때 함께 만들어도 된다.
5. helm upgrade 로 replicaCount 만 5 로 바꾼다. 릴리스 리비전이 2가 되어야 한다.
6. Kustomize base 를 만든다. /root/ckad-pkg/kustomize/base/deployment.yaml 에 Deployment report(레플리카 1, 라벨 app=report, 이미지 nginx:1.27)를 쓰고, 같은 디렉터리의 kustomization.yaml 에 그 파일을 resources 로 등록한다.
7. 오버레이 /root/ckad-pkg/kustomize/overlays/prod/kustomization.yaml 을 만든다. base 를 참조하고, 이름 앞에 prod- 접두어를 붙이고, 공통 라벨 env=prod 를 넣고, 레플리카를 4 로 바꾸는 패치를 적용한다. kubectl kustomize /root/ckad-pkg/kustomize/overlays/prod 결과에 prod-report 가 레플리카 4, 라벨 env: prod 로 나와야 한다.
8. 그 오버레이를 네임스페이스 ckad-pkg 에 적용한다 (kubectl apply -k ... -n ckad-pkg). Deployment prod-report 가 레플리카 4, 라벨 env=prod, 이미지 nginx:1.27 로 존재해야 한다.

참고

• helm list -n ckad-pkg, helm history webapp -n ckad-pkg 로 릴리스 상태와 리비전을 본다.
• kubectl kustomize <경로> 는 빌드만, kubectl apply -k <경로> 는 빌드 후 적용이다.
• 레플리카 패치는 patches: 에 path: 로 패치 파일을 가리키는 방식이 가장 무난하다. replicas: 전용 필드를 써도 된다.
• 흔한 실수 1: helm repo add 를 시도하는 것. 인터넷이 없으니 반드시 로컬 경로만 쓴다.
• 흔한 실수 2: 오버레이의 resources 에 절대 경로를 쓰는 것. ../../base 처럼 kustomization.yaml 기준 상대 경로가 안전하다.
• 흔한 실수 3: image.tag 를 숫자처럼 1.27 로 두는 것. YAML 이 실수로 파싱해 1.27 이 아닌 값이 될 수 있으니 따옴표로 감싼다.

단계 8개

1. helm create 로 차트 뼈대 만들기
2. values.yaml 고치기
3. helm template 으로 렌더 결과 확인
4. 로컬 경로에서 helm install
5. helm upgrade 로 리비전 쌓기
6. Kustomize base 만들기
7. 오버레이로 이름·라벨·레플리카 바꾸기
8. 오버레이를 클러스터에 적용 (종합)