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 로 반입하거나 로컬 경로로 설치한다. 여기서 연습하는 방식이 바로 그것이다.

단계

helm create /root/ckad-pkg/webapp 으로 차트를 만든다. (필요하면 /root/ckad-pkg 디렉터리를 먼저 만든다.)
/root/ckad-pkg/webapp/values.yaml 을 고친다. replicaCount: 3, image.repository: nginx, image.tag: "1.27", service.type: NodePort, service.port: 8080.
helm template webapp /root/ckad-pkg/webapp 결과를 /root/ckad-pkg/rendered.yaml 에 저장한다.
로컬 차트 경로를 그대로 지정해, 네임스페이스 ckad-pkg 에 릴리스 이름 webapp 으로 설치한다. 네임스페이스는 미리 만들어도 되고 설치할 때 함께 만들어도 된다.
helm upgrade 로 replicaCount 만 5 로 바꾼다. 릴리스 리비전이 2가 되어야 한다.
Kustomize base 를 만든다. /root/ckad-pkg/kustomize/base/deployment.yaml 에 Deployment report(레플리카 1, 라벨 app=report, 이미지 nginx:1.27)를 쓰고, 같은 디렉터리의 kustomization.yaml 에 그 파일을 resources 로 등록한다.
오버레이 /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 로 나와야 한다.
그 오버레이를 네임스페이스 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 이 아닌 값이 될 수 있으니 따옴표로 감싼다.

helm create 로 차트 뼈대 만들기

helm create /root/ckad-pkg/webapp 으로 차트를 만든다. (필요하면 /root/ckad-pkg 디렉터리를 먼저 만든다.)

helm create <경로> 는 인터넷 없이 로컬에 표준 차트 구조를 만든다. Chart.yaml, values.yaml, templates/ 가 생겼는지 확인한다.

values.yaml 고치기

/root/ckad-pkg/webapp/values.yaml 을 고친다. replicaCount: 3, image.repository: nginx, image.tag: "1.27", service.type: NodePort, service.port: 8080.

values.yaml 을 직접 편집한다. 이미지 태그는 문자열로 두는 편이 안전하다(따옴표). 서비스 타입과 포트는 service 블록 밑에 있다.

helm template 으로 렌더 결과 확인

helm template webapp /root/ckad-pkg/webapp 결과를 /root/ckad-pkg/rendered.yaml 에 저장한다.

helm template <릴리스이름> <차트경로> 는 클러스터에 아무것도 만들지 않고 최종 매니페스트만 출력한다. 리다이렉트로 파일에 저장한다.

로컬 경로에서 helm install

로컬 차트 경로를 그대로 지정해, 네임스페이스 ckad-pkg 에 릴리스 이름 webapp 으로 설치한다. 네임스페이스는 미리 만들어도 되고 설치할 때 함께 만들어도 된다.

차트 경로를 그대로 넘긴다(helm install 이름 /경로). 네임스페이스가 없으면 --create-namespace 를 붙인다. 인터넷이 없으므로 저장소 이름은 쓸 수 없다.

helm upgrade 로 리비전 쌓기

helm upgrade 로 replicaCount 만 5 로 바꾼다. 릴리스 리비전이 2가 되어야 한다.

--set 으로 값 하나만 덮어쓴다. 업그레이드하면 릴리스 리비전이 늘어나고 이전 리비전은 superseded 로 남는다. helm history 로 확인한다.

Kustomize base 만들기

Kustomize base 를 만든다. /root/ckad-pkg/kustomize/base/deployment.yaml 에 Deployment report(레플리카 1, 라벨 app=report, 이미지 nginx:1.27)를 쓰고, 같은 디렉터리의 kustomization.yaml 에 그 파일을 resources 로 등록한다.

base 디렉터리에 매니페스트 파일과 kustomization.yaml 을 둔다. kustomization 의 resources 는 같은 디렉터리 기준 상대 경로 배열이다. kubectl kustomize <경로> 로 빌드 결과를 본다.

오버레이로 이름·라벨·레플리카 바꾸기

오버레이 /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 로 나와야 한다.

오버레이의 resources 는 base 를 상대 경로로 가리킨다. 이름 앞에 접두어를 붙이는 필드와 공통 라벨을 붙이는 필드가 따로 있고, 레플리카는 전략적 병합 패치 파일로 덮어쓴다. 결과는 kubectl kustomize 출력으로 확인한다.

오버레이를 클러스터에 적용 (종합)

그 오버레이를 네임스페이스 ckad-pkg 에 적용한다 (kubectl apply -k ... -n ckad-pkg). Deployment prod-report 가 레플리카 4, 라벨 env=prod, 이미지 nginx:1.27 로 존재해야 한다.

kubectl apply -k <오버레이경로> 는 빌드와 적용을 한 번에 한다. 네임스페이스를 지정해야 원하는 곳에 들어간다. 적용 후 이름이 접두어와 함께 바뀌었는지 확인한다.