Packaging the Same App Twice, with Helm and Kustomize

목표

같은 Deployment 를 두 가지 전달 도구로 패키징해 봅니다. Helm 으로 차트를 만들고 values 를 바꿔 템플릿·설치·업그레이드하고, Kustomize 로 base 를 짠 뒤 prod 오버레이로 replicas 와 라벨을 덧씌웁니다. "어떤 매니페스트가 실제로 클러스터에 적용됐는가" 를 helm 릴리스와 kustomize 산출물 양쪽에서 확인합니다.

왜 중요한가

쿠버네티스 매니페스트는 손으로 쓴 YAML 하나로 끝나지 않습니다. 환경마다 replicas·이미지·라벨이 달라지고, 그 차이를 관리하는 방법이 곧 "앱 전달(delivery)" 의 핵심입니다. Helm 은 값(values)을 끼워 넣는 템플릿으로, Kustomize 는 base 위에 오버레이를 겹치는 방식으로 같은 문제를 풉니다. 둘의 사고방식은 다르지만 결과물은 똑같이 API 서버로 가는 매니페스트입니다.

helm install 과 helm upgrade 가 릴리스라는 단위로 변경 이력을 남긴다는 점, Kustomize 가 원본을 건드리지 않고 오버레이로만 차이를 표현한다는 점을 직접 만져 보면, 배포 파이프라인에서 "지금 무엇이 적용돼 있는가" 를 릴리스 리비전과 조립 결과로 되짚는 감각이 생깁니다.

단계

1. 네임스페이스 kcna-pkg 를 만듭니다.
2. helm create 로 webapp 차트 뼈대를 찍어 냅니다.
3. replicaCount 를 3 으로 바꿔 helm template 결과를 파일로 저장합니다.
4. 릴리스 web 으로 차트를 설치합니다.
5. --set replicaCount=5 로 업그레이드해 리비전과 replicas 를 올립니다.
6. Kustomize base(store Deployment)를 손으로 짜고 kubectl kustomize 로 조립을 확인합니다.
7. prod 오버레이로 replicas 4·env=prod 라벨을 덧씌워 적용합니다.
8. helm·kustomize 결과를 /root/kcna-pkg/report.txt 에 장부로 남깁니다.

참고

• helm list -n kcna-pkg -o json 과 helm history web -n kcna-pkg 로 릴리스 상태·리비전을 봅니다.
• kubectl kustomize <디렉터리> 는 클러스터에 손대지 않고 조립 결과만 보여 주므로, 적용 전에 확인하기 좋습니다.
• 공식 문서: Helm Charts · Kustomize 레퍼런스.

패키징 작업장 네임스페이스를 연다

네임스페이스 kcna-pkg 를 만듭니다. 이후 helm 릴리스와 kustomize 산출물이 모두 이 네임스페이스로 배포됩니다.

네임스페이스는 kubectl create namespace 로 만들 수 있습니다. 여러 번 돌려도 안전하게 하려면 --dry-run=client -o yaml | kubectl apply -f - 패턴을 쓰세요.

helm 이 차트 뼈대를 찍어 낸다

/root/kcna-pkg/webapp 위치에 helm 기본 차트를 새로 만듭니다(차트 이름 webapp). Chart.yaml 과 templates/deployment.yaml 이 생겨야 합니다.

helm create <경로> 는 values.yaml·Chart.yaml·templates/ 를 갖춘 표준 차트 뼈대를 만들어 줍니다. 경로의 마지막 이름이 차트 이름이 됩니다.

values 를 바꿔 3개로 템플릿한다

/root/kcna-pkg/webapp/values.yaml 의 replicaCount 를 3 으로 바꾼 뒤, helm template web /root/kcna-pkg/webapp 의 결과를 /root/kcna-pkg/rendered.yaml 로 저장합니다. 렌더된 Deployment 에 replicas: 3 이 나와야 합니다.

helm template 은 클러스터에 손대지 않고 values 를 끼워 넣어 최종 매니페스트를 문자열로 찍어 줍니다. 기본 차트는 replicaCount 값을 Deployment 의 replicas 로 흘려보냅니다. 값은 sed 나 yq 로 고칠 수 있습니다.

차트를 클러스터에 설치한다

차트를 릴리스 이름 web 으로 네임스페이스 kcna-pkg 에 설치합니다(helm install web /root/kcna-pkg/webapp -n kcna-pkg). helm 릴리스 목록에 web 이 deployed 상태로 보이고, 그 릴리스가 만든 Deployment 가 실제로 생겨야 합니다.

helm install <릴리스> <차트> -n <네임스페이스> 는 렌더된 매니페스트를 클러스터에 적용하고 릴리스를 기록합니다. helm list -n <ns> -o json 으로 상태를 확인할 수 있습니다. helm 이 만든 오브젝트에는 meta.helm.sh/release-name 주석이 붙습니다.

업그레이드로 5개로 키운다

릴리스 web 을 --set replicaCount=5 로 업그레이드합니다(helm upgrade web /root/kcna-pkg/webapp -n kcna-pkg --set replicaCount=5). 업그레이드 후 릴리스 리비전은 2 이상이 되고, 해당 Deployment 의 spec.replicas 는 5 가 돼야 합니다.

helm upgrade 는 같은 릴리스의 새 리비전을 만듭니다. --set 은 values 파일을 고치지 않고 특정 값만 덮어씁니다. helm history <릴리스> -n <ns> 로 리비전이 올라갔는지 볼 수 있습니다.

Kustomize base 를 손으로 짠다

/root/kcna-pkg/kustomize/base 에 kustomization.yaml 과 deployment.yaml 을 만듭니다. Deployment 이름은 store, 이미지 nginx:1.27-alpine, replicas 1, 셀렉터·라벨은 app: store 로 맞춥니다. kustomization 의 resources 는 [deployment.yaml] 입니다. kubectl kustomize /root/kcna-pkg/kustomize/base 가 성공하고 결과에 Deployment store 가 나와야 합니다.

Kustomize base 는 원본 매니페스트와, 그것을 가리키는 kustomization.yaml 로 이뤄집니다. resources: 에 파일 이름을 나열합니다. kubectl kustomize <디렉터리> 로 조립 결과를 미리 볼 수 있습니다. Deployment 의 selector.matchLabels 와 template 라벨은 서로 맞아야 합니다.

prod 오버레이로 4개·env=prod 를 씌운다

/root/kcna-pkg/kustomize/overlays/prod 에 오버레이를 만듭니다. ../../base 를 resources 로 참조하고, replicas 를 4 로 올리는 패치와 공통 라벨 env=prod 를 더합니다. 그런 다음 kubectl apply -k /root/kcna-pkg/kustomize/overlays/prod -n kcna-pkg 로 적용합니다. 결과적으로 네임스페이스 kcna-pkg 의 Deployment store 는 spec.replicas 4, 라벨 env=prod 를 가져야 합니다.

오버레이는 base 를 resources: [../../base] 로 끌어와 그 위에 변경을 덧씌웁니다. replicas 는 같은 이름의 Deployment 를 담은 패치로 바꾸고(patches:), 공통 라벨은 commonLabels: 로 한 번에 붙입니다. kubectl apply -k 는 오버레이를 조립해 바로 적용합니다.

무엇을 어떻게 패키징했는지 장부로 남긴다

/root/kcna-pkg/report.txt 에 정확히 네 줄을 적습니다 — helm-release=web, helm-replicas=5, kustomize-replicas=4, kustomize-label=env=prod. 값은 실제 클러스터 상태와 일치해야 합니다.

채점기는 이 네 줄을 실제 상태와 대조합니다. helm 릴리스가 만든 Deployment 의 현재 replicas, kustomize 로 배포한 store 의 replicas 와 env 라벨을 확인해서 옮기세요. 추측하지 말고 kubectl get deploy -n kcna-pkg 로 읽은 값을 적습니다.