차트 뼈대 만들고 표준 라벨 붙이기

목표

Helm 차트의 표준 구조를 직접 만들고, 이름과 라벨을 한 자리에서 관리해 모든 오브젝트에 일관된 표준 라벨이 붙게 만듭니다.

왜 중요한가

차트를 배울 때 사람들은 템플릿 문법부터 궁금해하지만, 실제로 차트의 수명을 결정하는 것은 구조입니다. Chart.yaml 은 이 묶음이 무엇인지, values.yaml 은 사용자가 무엇을 만질 수 있는지, templates/ 는 그 값이 어떤 모양이 되는지를 각각 책임집니다. 이 분리가 있어야 "환경마다 파일을 복사해 고치는" 습관이 사라집니다. 라벨도 취향의 문제가 아닙니다. app.kubernetes.io/* 는 쿠버네티스 공식 권장 표준이고, 관리 도구와 대시보드가 이 라벨로 리소스를 묶습니다. 특히 공통 라벨과 셀렉터 라벨은 반드시 분리해야 합니다. Deployment 의 spec.selector 는 생성 후 변경할 수 없는 필드인데, 공통 라벨에는 차트 버전과 앱 버전이 섞여 있어서 셀렉터에 그대로 쓰면 버전을 올리는 순간 업그레이드가 거부됩니다.

단계

1. /root/helm/lab/labhub-web 에 차트 뼈대를 만드세요(helm create labhub-web 을 /root/helm/lab 안에서 실행하면 됩니다). Chart.yaml, values.yaml, .helmignore 세 파일과 templates/(파일 3개 이상), charts/ 디렉터리가 모두 있어야 합니다. 산출물을 담을 /root/helm/lab/out 디렉터리도 미리 만들어 두세요.
2. /root/helm/lab/labhub-web/Chart.yaml 을 채우세요. apiVersion: v2, name: labhub-web, type: application, version 은 0.1.0 같은 SemVer, appVersion: "1.27", 그리고 description 한 줄이 반드시 있어야 합니다.
3. /root/helm/lab/labhub-web/values.yaml 의 기본값을 다음으로 맞추세요. replicaCount: 2, image.repository: nginx, image.tag: "1.27", image.pullPolicy: IfNotPresent, service.port: 80. 이 파일에는 # 으로 시작하는 주석이 최소 한 줄 있어야 합니다.
4. /root/helm/lab/labhub-web/templates/_helpers.tpl 에 labhub-web.fullname, labhub-web.labels, labhub-web.selectorLabels 세 개의 정의가 있어야 하고, 이름을 만드는 곳에 trunc 63 처리가 들어가야 합니다. 그리고 /root/helm/lab/labhub-web/templates/deployment.yaml 은 이 정의들을 include "labhub-web... 형태로 불러 써야 합니다.
5. helm template labhub-web /root/helm/lab/labhub-web > /root/helm/lab/out/rendered.yaml 로 렌더링을 저장하세요. 결과에는 오브젝트가 2개 이상 있어야 하고, Deployment 의 metadata.labels 에 app.kubernetes.io/managed-by: Helm, app.kubernetes.io/name: labhub-web, app.kubernetes.io/version 이 있어야 하며, Service 의 metadata.labels 에도 같은 공통 라벨이 붙어 있어야 합니다.
6. /root/helm/lab/labhub-web/templates/NOTES.txt 가 .Release.Name 과 .Values. 로 시작하는 값을 최소 하나씩 참조하게 하세요. 그리고 실제로 렌더링된 안내문을 /root/helm/lab/out/notes.txt 에 저장하세요. helm install labhub-web /root/helm/lab/labhub-web --dry-run 의 출력에서 NOTES: 아래 부분만 잘라 내면 됩니다(sed -n '/^NOTES:/,$p'). 저장한 파일에는 labhub-web 이 들어 있어야 하고 렌더링되지 않은 중괄호 구문이 남아 있으면 안 됩니다.
7. helm lint /root/helm/lab/labhub-web > /root/helm/lab/out/lint.txt 로 린트 결과를 저장하세요. 파일에 린트 요약 줄이 있어야 하고 [ERROR] 가 하나도 없어야 합니다.
8. 값을 덮어쓴 렌더링을 helm template labhub-web /root/helm/lab/labhub-web --set replicaCount=5 > /root/helm/lab/out/scaled.yaml 로 저장하세요. 최종 확인 조건은 네 가지입니다. /root/helm/lab/out/rendered.yaml 의 Deployment spec.replicas 는 2, /root/helm/lab/out/scaled.yaml 의 것은 5, 컨테이너 이미지는 nginx:1.27, Service 의 첫 포트는 80. 그리고 Service 의 spec.selector 에 있는 app.kubernetes.io/name 과 Deployment 파드 템플릿 라벨의 app.kubernetes.io/name 이 같은 값이어야 합니다.

참고

실습 파드는 실습마다 새로 뜨므로 다른 실습에서 만든 차트나 릴리스는 남아 있지 않습니다. 필요한 차트는 매번 여기서 처음부터 만듭니다 — 차트가 곧 재현 가능한 패키지라는 사실이 여기서 드러납니다.
뼈대 생성 명령이 만들어 주는 기본 차트에는 이미 헬퍼와 표준 라벨이 들어 있습니다. 지우고 새로 쓰기보다 값과 이름을 맞추는 편이 빠릅니다.
helm template 은 클러스터 없이도 동작하고, helm install --dry-run 은 클러스터에 아무것도 만들지 않으면서 NOTES 까지 보여 줍니다. 안내문을 확인할 때는 후자가 필요합니다.
흔한 실수 1: appVersion 을 그대로 두는 것. 이미지 태그 기본값과 app.kubernetes.io/version 라벨이 여기서 나오므로 값이 어긋납니다.
흔한 실수 2: NOTES.txt 원본을 그대로 복사해 /root/helm/lab/out/notes.txt 로 저장하는 것. 그러면 중괄호가 남아 있어 렌더링된 결과가 아니라고 판정됩니다.

단계 8개

차트 뼈대 만들기
Chart.yaml 의 신원 채우기
values.yaml 기본값 설계하기
이름과 라벨을 헬퍼로 뽑기
모든 오브젝트에 표준 라벨 붙이기
설치 안내문 쓰고 렌더링하기
차트 린트 통과시키기
렌더링 결과 검증하기