Scaffolding a Chart and Adding Standard Labels

한국어 원문으로 표시합니다.

목표

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

왜 중요한가

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

단계

/root/helm/lab/labhub-web 에 차트 뼈대를 만드세요(helm create labhub-web 을 /root/helm/lab 안에서 실행하면 됩니다). Chart.yaml, values.yaml, .helmignore 세 파일과 templates/(파일 3개 이상), charts/ 디렉터리가 모두 있어야 합니다. 산출물을 담을 /root/helm/lab/out 디렉터리도 미리 만들어 두세요.
/root/helm/lab/labhub-web/Chart.yaml 을 채우세요. apiVersion: v2, name: labhub-web, type: application, version 은 0.1.0 같은 SemVer, appVersion: "1.27", 그리고 description 한 줄이 반드시 있어야 합니다.
/root/helm/lab/labhub-web/values.yaml 의 기본값을 다음으로 맞추세요. replicaCount: 2, image.repository: nginx, image.tag: "1.27", image.pullPolicy: IfNotPresent, service.port: 80. 이 파일에는 # 으로 시작하는 주석이 최소 한 줄 있어야 합니다.
/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... 형태로 불러 써야 합니다.
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 에도 같은 공통 라벨이 붙어 있어야 합니다.
/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 이 들어 있어야 하고 렌더링되지 않은 중괄호 구문이 남아 있으면 안 됩니다.
helm lint /root/helm/lab/labhub-web > /root/helm/lab/out/lint.txt 로 린트 결과를 저장하세요. 파일에 린트 요약 줄이 있어야 하고 [ERROR] 가 하나도 없어야 합니다.
값을 덮어쓴 렌더링을 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 로 저장하는 것. 그러면 중괄호가 남아 있어 렌더링된 결과가 아니라고 판정됩니다.

차트 뼈대 만들기

/root/helm/lab/labhub-web 에 차트 뼈대를 만드세요(helm create labhub-web 을 /root/helm/lab 안에서 실행하면 됩니다). Chart.yaml, values.yaml, .helmignore 세 파일과 templates/(파일 3개 이상), charts/ 디렉터리가 모두 있어야 합니다. 산출물을 담을 /root/helm/lab/out 디렉터리도 미리 만들어 두세요.

Helm 에는 표준 구조를 한 번에 만들어 주는 명령이 있습니다. 만들어진 뒤에는 Chart.yaml, values.yaml, .helmignore, templates/, charts/ 다섯 자리가 모두 있는지 확인하세요. charts/ 는 비어 있어도 있어야 합니다.

Chart.yaml 의 신원 채우기

/root/helm/lab/labhub-web/Chart.yaml 을 채우세요. apiVersion: v2, name: labhub-web, type: application, version 은 0.1.0 같은 SemVer, appVersion: "1.27", 그리고 description 한 줄이 반드시 있어야 합니다.

Helm 3 의 apiVersion 은 하나로 고정입니다. 그리고 차트 자체의 버전과 앱 버전은 서로 다른 필드라는 점에 주의하세요 — 이미지 태그와 맞춰야 하는 쪽이 어느 것인지 생각해 보세요.

values.yaml 기본값 설계하기

/root/helm/lab/labhub-web/values.yaml 의 기본값을 다음으로 맞추세요. replicaCount: 2, image.repository: nginx, image.tag: "1.27", image.pullPolicy: IfNotPresent, service.port: 80. 이 파일에는 # 으로 시작하는 주석이 최소 한 줄 있어야 합니다.

관련된 값은 평평하게 늘어놓지 말고 image 처럼 묶습니다. 그리고 values.yaml 은 사용자가 읽는 유일한 문서이므로 주석이 최소한 하나는 있어야 합니다.

이름과 라벨을 헬퍼로 뽑기

/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... 형태로 불러 써야 합니다.

밑줄로 시작하는 템플릿 파일은 매니페스트로 렌더링되지 않습니다. 공통 라벨과 셀렉터 라벨을 따로 정의해야 하는 이유를 생각해 보세요. 이름에는 길이 제한 처리가 필요합니다.

모든 오브젝트에 표준 라벨 붙이기

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 에도 같은 공통 라벨이 붙어 있어야 합니다.

Deployment 뿐 아니라 Service 에도 같은 공통 라벨이 붙어야 합니다. managed-by 값은 손으로 적지 말고 릴리스 정보에서 가져오세요. 렌더링 결과를 파일로 저장해야 채점됩니다.

설치 안내문 쓰고 렌더링하기

/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 이 들어 있어야 하고 렌더링되지 않은 중괄호 구문이 남아 있으면 안 됩니다.

NOTES.txt 도 템플릿입니다. 릴리스 이름과 values 값을 함께 써야 사용자가 무엇을 설치했는지 알 수 있습니다. 저장할 파일에는 렌더링된 결과가 들어가야 하며 중괄호가 남아 있으면 안 됩니다.

차트 린트 통과시키기

helm lint /root/helm/lab/labhub-web > /root/helm/lab/out/lint.txt 로 린트 결과를 저장하세요. 파일에 린트 요약 줄이 있어야 하고 [ERROR] 가 하나도 없어야 합니다.

린트 출력 전체를 파일로 남기세요. ERROR 가 하나라도 있으면 실패입니다. 경고는 통과지만 왜 났는지는 읽어 보는 편이 좋습니다.

렌더링 결과 검증하기

값을 덮어쓴 렌더링을 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 이 같은 값이어야 합니다.

기본 렌더링과 값을 덮어쓴 렌더링 두 개가 필요합니다. 그리고 Service 의 셀렉터와 파드 템플릿의 라벨이 같은 키·값인지 직접 눈으로 대조해 보세요. 다르면 트래픽이 파드에 닿지 않습니다.