Attaching Subcharts and Creating Order With Hooks

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

목표

독립된 두 차트를 부모와 서브차트로 조립하고, 값 전달·조건부 활성화·전역 값·훅까지 의존성 관리의 네 축을 모두 손으로 만듭니다.

왜 중요한가

플랫폼 차트를 만들다 보면 반드시 "이 컴포넌트를 같은 차트에 넣을까, 따로 뺄까"라는 질문을 만납니다. 의존성은 그 사이의 답입니다. 자식은 혼자서도 설치 가능한 독립 차트로 남고, 부모는 그것을 선언으로 끌어다 쓰면서 값을 덮어씁니다. 이때 규칙은 하나뿐입니다 — 부모 values 에서 서브차트 이름과 같은 키 아래에 적은 것이 자식의 .Values 최상위가 된다. 부모와 자식 모두에게 닿아야 하는 값만 global 아래에 둡니다. 그리고 이 환경은 인터넷이 없으므로 저장소는 반드시 file:// 로컬 경로여야 합니다. 이는 제약이 아니라 실무에서도 흔한 구성입니다 — 저장소 하나에 여러 차트를 두고 서로 참조할 때 쓰는 바로 그 방식입니다. 마지막으로 훅은 배포 안에 순서를 만드는 유일한 수단이지만, 훅 리소스는 릴리스가 소유하지 않으므로 삭제 정책을 적지 않으면 배포할 때마다 쌓입니다.

단계

/root/helm/deps/cache 에 이름이 cache 인 차트를, /root/helm/deps/platform 에 부모가 될 차트를 각각 만드세요. 두 차트 모두 Chart.yaml, values.yaml, templates/ 를 갖춰야 합니다. /root/helm/deps/cache/values.yaml 의 replicaCount 는 1 로 둡니다. 산출물 디렉터리 /root/helm/deps/out 도 미리 만드세요.
/root/helm/deps/platform/Chart.yaml 의 dependencies 첫 항목에 name: cache, repository: "file://../cache", version 은 cache 차트의 version 과 같은 값(예: 0.1.0), condition: cache.enabled 를 적으세요. 인터넷이 없으므로 원격 저장소 URL 은 동작하지 않습니다.
helm dependency update /root/helm/deps/platform 을 실행하세요. /root/helm/deps/platform/Chart.lock 이 생겨야 하고, 그 안의 첫 의존성 이름이 cache, digest 가 sha256: 으로 시작해야 하며, /root/helm/deps/platform/charts/ 안에 cache 패키지가 놓여야 합니다.
/root/helm/deps/platform/values.yaml 에 cache.enabled: true 와 cache.replicaCount: 3 을 적고 helm template platform /root/helm/deps/platform > /root/helm/deps/out/rendered.yaml 로 렌더링하세요. 이름에 cache 가 들어간 Deployment 의 spec.replicas 가 3이어야 합니다. 이때 /root/helm/deps/cache/values.yaml 의 replicaCount 는 반드시 1 그대로 두세요 — 부모가 덮어쓰는 것을 확인하는 단계입니다.
helm template platform /root/helm/deps/platform --set cache.enabled=false > /root/helm/deps/out/disabled.yaml 을 저장하세요. 이 파일에는 cache 라는 문자열이 한 군데도 없어야 하고, 부모 차트의 오브젝트는 그대로 남아 있어야 합니다(오브젝트 1개 이상). 부모 차트 자신의 리소스 이름이나 내용에 cache 라는 단어를 쓰지 마세요.
/root/helm/deps/platform/values.yaml 에 global.environment: stage 를 두고, 부모와 서브차트 양쪽 템플릿의 metadata.labels 에 labhub.io/environment: {{ .Values.global.environment }} 를 붙이세요. 다시 렌더링한 /root/helm/deps/out/rendered.yaml 에 labhub.io/environment: stage 줄이 2개 이상 있어야 하고, 이름에 cache 가 들어간 오브젝트에도 그 라벨이 있어야 합니다.
/root/helm/deps/platform/templates/ 에 훅 Job 을 하나 추가하세요. 이름은 {{ .Release.Name }}-db-migrate 처럼 짓고(이름에 cache 를 넣지 마세요), 어노테이션으로 helm.sh/hook: pre-install,pre-upgrade, helm.sh/hook-weight: "-5", helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded 를 답니다. 훅이 포함된 렌더링을 /root/helm/deps/out/hooks.yaml 로 저장하세요(helm template 은 기본적으로 훅도 함께 출력합니다).
/root/helm/deps/out/deps-report.json 을 만드세요. 키는 네 개입니다. object_count 는 /root/helm/deps/out/rendered.yaml 에서 kind: 로 시작하는 줄의 개수, subcharts 는 ["cache"], lock_digest 는 /root/helm/deps/platform/Chart.lock 의 digest 값 그대로, hooks 는 훅 리소스 이름을 담은 배열(1개 이상)입니다. 또한 렌더링된 Deployment 이름 중 하나에는 릴리스 이름 platform 이 들어 있어야 합니다.

참고

실습 파드는 실습마다 새로 뜨므로 다른 실습에서 만든 차트는 남아 있지 않습니다. 두 차트 모두 /root/helm/deps 아래에 여기서 처음부터 만듭니다 — 차트가 곧 재현 가능한 패키지라는 사실이 여기서 드러납니다.
file:// 경로는 부모 차트 디렉터리 기준 상대 경로로 해석됩니다. 절대 경로로 적어도 되지만 저장소를 옮기면 깨집니다.
helm dependency update 는 charts/ 를 채우고 Chart.lock 을 새로 씁니다. helm dependency build 는 잠금 파일에 적힌 그대로만 재현하므로 CI 에서 써야 할 쪽은 build 입니다.
서브차트 값은 부모 values 의 서브차트 이름과 같은 키 아래에 적습니다. cache: 아래 적은 것이 곧 자식의 .Values 최상위입니다.
흔한 실수 1: 자식을 껐는데 부모 템플릿이 여전히 자식 이름이 든 리소스를 만들어 5번이 실패하는 것. 조건은 자식 차트만 끕니다.
흔한 실수 2: 훅에 hook-delete-policy 를 빠뜨리는 것. 훅 리소스는 릴리스가 소유하지 않아 스스로 정리되지 않고, 다음 배포에서 같은 이름으로 충돌합니다.

서브차트와 부모 차트 준비하기

/root/helm/deps/cache 에 이름이 cache 인 차트를, /root/helm/deps/platform 에 부모가 될 차트를 각각 만드세요. 두 차트 모두 Chart.yaml, values.yaml, templates/ 를 갖춰야 합니다. /root/helm/deps/cache/values.yaml 의 replicaCount 는 1 로 둡니다. 산출물 디렉터리 /root/helm/deps/out 도 미리 만드세요.

두 개의 독립된 차트가 필요합니다. 자식 차트도 그 자체로 완결된 구조(메타데이터·기본값·템플릿)를 가져야 나중에 패키징됩니다.

부모 Chart.yaml 에 의존성 선언하기

/root/helm/deps/platform/Chart.yaml 의 dependencies 첫 항목에 name: cache, repository: "file://../cache", version 은 cache 차트의 version 과 같은 값(예: 0.1.0), condition: cache.enabled 를 적으세요. 인터넷이 없으므로 원격 저장소 URL 은 동작하지 않습니다.

이 환경은 인터넷이 없습니다. 원격 저장소 URL 대신 부모 차트 기준 상대 경로를 쓰는 방식을 찾아보세요. 켜고 끌 수 있게 만드는 필드도 함께 적어야 합니다.

의존성 확정하고 charts/ 채우기

helm dependency update /root/helm/deps/platform 을 실행하세요. /root/helm/deps/platform/Chart.lock 이 생겨야 하고, 그 안의 첫 의존성 이름이 cache, digest 가 sha256: 으로 시작해야 하며, /root/helm/deps/platform/charts/ 안에 cache 패키지가 놓여야 합니다.

의존성을 확정하면 잠금 파일이 생기고 charts/ 에 패키지가 놓입니다. 선언한 버전과 자식 차트의 버전이 다르면 여기서 실패합니다.

부모에서 서브차트 값 덮어쓰기

/root/helm/deps/platform/values.yaml 에 cache.enabled: true 와 cache.replicaCount: 3 을 적고 helm template platform /root/helm/deps/platform > /root/helm/deps/out/rendered.yaml 로 렌더링하세요. 이름에 cache 가 들어간 Deployment 의 spec.replicas 가 3이어야 합니다. 이때 /root/helm/deps/cache/values.yaml 의 replicaCount 는 반드시 1 그대로 두세요 — 부모가 덮어쓰는 것을 확인하는 단계입니다.

자식 차트의 기본값 파일은 건드리지 마세요. 부모 values 에서 서브차트 이름과 같은 키 아래에 값을 적으면 그것이 자식의 최상위 값이 됩니다.

condition 으로 서브차트 끄기

helm template platform /root/helm/deps/platform --set cache.enabled=false > /root/helm/deps/out/disabled.yaml 을 저장하세요. 이 파일에는 cache 라는 문자열이 한 군데도 없어야 하고, 부모 차트의 오브젝트는 그대로 남아 있어야 합니다(오브젝트 1개 이상). 부모 차트 자신의 리소스 이름이나 내용에 cache 라는 단어를 쓰지 마세요.

조건은 자식 차트만 끕니다. 껐는데도 결과에 자식 이름이 보인다면 부모 템플릿이 그 리소스를 직접 만들고 있는 것입니다.

global 값을 서브차트까지 전달하기

/root/helm/deps/platform/values.yaml 에 global.environment: stage 를 두고, 부모와 서브차트 양쪽 템플릿의 metadata.labels 에 labhub.io/environment: {{ .Values.global.environment }} 를 붙이세요. 다시 렌더링한 /root/helm/deps/out/rendered.yaml 에 labhub.io/environment: stage 줄이 2개 이상 있어야 하고, 이름에 cache 가 들어간 오브젝트에도 그 라벨이 있어야 합니다.

부모와 자식 모두에게 닿아야 하는 값을 두는 자리가 따로 있습니다. 양쪽 템플릿에서 같은 라벨을 붙여 실제로 전달되는지 눈으로 확인하세요.

설치 훅 붙이기

/root/helm/deps/platform/templates/ 에 훅 Job 을 하나 추가하세요. 이름은 {{ .Release.Name }}-db-migrate 처럼 짓고(이름에 cache 를 넣지 마세요), 어노테이션으로 helm.sh/hook: pre-install,pre-upgrade, helm.sh/hook-weight: "-5", helm.sh/hook-delete-policy: before-hook-creation,hook-succeeded 를 답니다. 훅이 포함된 렌더링을 /root/helm/deps/out/hooks.yaml 로 저장하세요(helm template 은 기본적으로 훅도 함께 출력합니다).

훅은 어노테이션 세 개로 정의합니다. 언제 도는지, 여러 개일 때 순서가 어떻게 되는지, 그리고 끝난 뒤 누가 치우는지를 각각 적어야 합니다.

엄브렐라 렌더링 보고서 만들기

/root/helm/deps/out/deps-report.json 을 만드세요. 키는 네 개입니다. object_count 는 /root/helm/deps/out/rendered.yaml 에서 kind: 로 시작하는 줄의 개수, subcharts 는 ["cache"], lock_digest 는 /root/helm/deps/platform/Chart.lock 의 digest 값 그대로, hooks 는 훅 리소스 이름을 담은 배열(1개 이상)입니다. 또한 렌더링된 Deployment 이름 중 하나에는 릴리스 이름 platform 이 들어 있어야 합니다.

렌더링 결과와 잠금 파일에서 숫자를 직접 뽑아 JSON 으로 정리합니다. 오브젝트 개수와 다이제스트는 손으로 적지 말고 파일에서 읽어 넣으세요.