標準ラベルをライブラリチャート一か所にまとめる

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

목표

type: library 차트를 만들어 두 애플리케이션 차트가 같은 Deployment 템플릿과 라벨 규칙을 나눠 쓰게 하고, 같은 이름을 부모가 다시 정의했을 때 무엇이 이기는지 렌더로 확인한다.

왜 중요한가

차트가 늘어나면 가장 먼저 흩어지는 것이 표준 라벨이다. 같은 회사 차트인데 어떤 것은 app.kubernetes.io/instance 를 붙이고 어떤 것은 release 를 붙인다. 모니터링 대시보드와 네트워크 정책이 라벨로 대상을 고르기 때문에, 이 불일치는 나중에 '왜 이 파드만 지표가 안 잡히냐' 로 돌아온다. 라이브러리 차트는 이 규칙을 한 곳에 못 박는 장치다. 자기 혼자서는 설치도 렌더도 되지 않고 define 만 담기 때문에, 오직 남이 쓰라고 존재한다는 것이 종류 이름에 드러나 있다. 여기서 함께 배우는 것이 두 가지 더 있다 — tpl 로 values 안의 문자열을 템플릿으로 다시 돌리는 법, 그리고 템플릿 이름이 차트 전체에서 하나의 이름 공간이라서 이름이 겹치면 조용히 덮어써진다는 사실이다.

단계

/root/hc-library/platform-lib 에 type: library 인 차트(이름 platform-lib, 버전 0.1.0)를 만드세요. /root/hc-library/platform-lib/templates/_helpers.tpl 에 platform-lib.fullname 과 platform-lib.labels 두 개를 define 으로 정의합니다. labels 는 app.kubernetes.io/name, app.kubernetes.io/instance, app.kubernetes.io/managed-by, platform.labhub.io/tier 네 줄을 냅니다. templates 아래에는 밑줄로 시작하는 파일만 두세요.
helm install liblab /root/hc-library/platform-lib --dry-run 과 helm template liblab /root/hc-library/platform-lib 를 차례로 돌려 두 출력(오류 포함)을 /root/hc-library/out/library-error.txt 에 모두 담으세요. 헬름이 어떤 말로 거절하는지가 이 단계의 답입니다.
/root/hc-library/platform-lib/templates/_deployment.tpl 에 platform-lib.deployment 를 정의하세요. 이 템플릿은 Deployment 를 내며 이름은 platform-lib.fullname, metadata.labels 는 platform-lib.labels 를 nindent 4 로 꽂아 만듭니다. spec.replicas 는 .Values.replicas(기본 1), 컨테이너 이름은 .Chart.Name, 이미지는 .Values.image 를 따옴표로 감싸 씁니다. selector 와 파드 라벨은 name·instance 두 줄만 씁니다.
/root/hc-library/billing 애플리케이션 차트(버전 0.1.0, appVersion "1.4.2")를 만들고 platform-lib 0.1.0 을 file://../platform-lib 저장소로 의존성 선언한 뒤 확정하세요. values.yaml 은 replicas: 1, image: "registry.local/billing:1.4.2", tier: core, 그리고 note: "{{ .Release.Name }} in {{ .Release.Namespace }}" 네 값을 담고, templates/deployment.yaml 은 platform-lib.deployment 를 include 한 줄만 둡니다. helm template shop /root/hc-library/billing 결과를 /root/hc-library/out/billing.yaml 에 저장하세요.
/root/hc-library/reporting 차트(버전 0.1.0, appVersion "0.9.0")를 같은 방식으로 만들되 replicas: 3, image: "registry.local/reporting:0.9.0", tier: batch, note: "{{ .Chart.Name }} {{ .Chart.Version }}" 로 두고 의존성을 확정하세요. helm template insight /root/hc-library/reporting 결과를 /root/hc-library/out/reporting.yaml 에 저장합니다. 두 렌더 결과의 라벨 키 목록이 같고 값만 다른지 확인하세요.
라이브러리에 platform-lib.configmap 을 추가하세요(/root/hc-library/platform-lib/templates/_configmap.tpl). 이름은 <fullname>-note, data.note 는 .Values.note 를 tpl 로 한 번 더 렌더해 따옴표로 감쌉니다. 두 차트에 templates/configmap.yaml(include 한 줄)을 추가하세요. note 값은 4·5단계에서 이미 values.yaml 에 넣어 두었습니다 — 중괄호가 든 채로 그대로 두세요. 라이브러리를 고쳤으니 두 차트에서 의존성을 다시 받아야 합니다. 두 렌더 파일을 다시 저장하세요.
/root/hc-library/billing/templates/_override.tpl 에 같은 이름 platform-lib.deployment 를 다시 정의하세요. 내용은 라이브러리 것과 같되 metadata.annotations 에 platform.labhub.io/overridden-by: billing 한 줄을 더합니다. 두 차트를 다시 렌더해 저장하고, billing 에만 그 애너테이션이 붙는지 확인하세요.
/root/hc-library/out/report.json 에 이 실습의 결과를 정리하세요. 키는 library(라이브러리 차트 이름), type(차트 종류), installable(불리언), consumers(소비 차트 이름 배열), billing_replicas, reporting_replicas(각 렌더의 실제 replicas 숫자), shared_label_keys(라이브러리 헬퍼가 만드는 라벨 키 개수), override_winner(같은 이름을 다시 정의해 이긴 차트 이름) 여덟 개입니다.

참고

type: library 차트의 templates 에는 밑줄로 시작하는 파일만 둔다
의존성 repository: "file://../<디렉터리>" 는 이 파드에서 동작한다(저장소 등록의 file:// 와는 다른 자리다)
helm dependency update 는 그 시점의 라이브러리를 tgz 로 떠 간다 — 라이브러리를 고쳤으면 다시 받는다
흔한 실수: 라이브러리를 helm install 해 보고 차트가 깨진 줄 안다
흔한 실수: define 이름에 차트 이름을 붙이지 않아 다른 차트의 정의와 조용히 충돌한다
공식 문서: https://helm.sh/docs/topics/library_charts/ · https://helm.sh/docs/chart_template_guide/named_templates/

아무것도 렌더하지 않는 차트를 만든다

/root/hc-library/platform-lib 에 type: library 인 차트(이름 platform-lib, 버전 0.1.0)를 만드세요. /root/hc-library/platform-lib/templates/_helpers.tpl 에 platform-lib.fullname 과 platform-lib.labels 두 개를 define 으로 정의합니다. labels 는 app.kubernetes.io/name, app.kubernetes.io/instance, app.kubernetes.io/managed-by, platform.labhub.io/tier 네 줄을 냅니다. templates 아래에는 밑줄로 시작하는 파일만 두세요.

라이브러리 차트에는 렌더되는 템플릿이 없습니다. 헬름은 _ 로 시작하는 파일을 '출력하지 않는 조각' 으로 다루므로, 모든 내용이 _*.tpl 안의 define 블록에 들어갑니다. tier 는 값이 없을 수도 있으니 default 를 걸고 quote 로 감싸세요.

라이브러리 차트를 설치해 본다

helm install liblab /root/hc-library/platform-lib --dry-run 과 helm template liblab /root/hc-library/platform-lib 를 차례로 돌려 두 출력(오류 포함)을 /root/hc-library/out/library-error.txt 에 모두 담으세요. 헬름이 어떤 말로 거절하는지가 이 단계의 답입니다.

두 명령 모두 실패합니다. 오류는 표준오류로 나가므로 2>&1 로 함께 받아야 파일에 담깁니다. 두 번째 명령은 첫 출력을 지우지 않도록 이어붙이기(>>)로 쓰세요. 설치가 막히는 이유를 생각해 보세요 — 이 차트에는 렌더될 것이 하나도 없습니다.

Deployment 한 벌을 통째로 라이브러리에 넣는다

/root/hc-library/platform-lib/templates/_deployment.tpl 에 platform-lib.deployment 를 정의하세요. 이 템플릿은 Deployment 를 내며 이름은 platform-lib.fullname, metadata.labels 는 platform-lib.labels 를 nindent 4 로 꽂아 만듭니다. spec.replicas 는 .Values.replicas(기본 1), 컨테이너 이름은 .Chart.Name, 이미지는 .Values.image 를 따옴표로 감싸 씁니다. selector 와 파드 라벨은 name·instance 두 줄만 씁니다.

include 는 다른 define 의 결과를 문자열로 받아 오므로 파이프로 들여쓰기를 걸 수 있습니다. nindent 4 는 줄바꿈을 먼저 넣고 네 칸을 들여씁니다 — labels: 바로 아래 줄에서 쓰기에 알맞습니다. 채점기는 이 정의를 임시 차트에 넣고 직접 렌더해 봅니다.

애플리케이션 차트가 라이브러리를 의존성으로 건다

/root/hc-library/billing 애플리케이션 차트(버전 0.1.0, appVersion "1.4.2")를 만들고 platform-lib 0.1.0 을 file://../platform-lib 저장소로 의존성 선언한 뒤 확정하세요. values.yaml 은 replicas: 1, image: "registry.local/billing:1.4.2", tier: core, 그리고 note: "{{ .Release.Name }} in {{ .Release.Namespace }}" 네 값을 담고, templates/deployment.yaml 은 platform-lib.deployment 를 include 한 줄만 둡니다. helm template shop /root/hc-library/billing 결과를 /root/hc-library/out/billing.yaml 에 저장하세요.

라이브러리는 설치할 수 없지만 의존성으로는 걸 수 있습니다. file:// 는 저장소 등록에는 안 되지만 의존성 repository 로는 동작합니다. 확정하면 Chart.lock 과 charts/platform-lib-0.1.0.tgz 가 생깁니다. 릴리스 이름을 shop 으로 주면 오브젝트 이름이 shop-billing 이 됩니다.

두 번째 차트가 같은 템플릿을 다른 값으로 쓴다

/root/hc-library/reporting 차트(버전 0.1.0, appVersion "0.9.0")를 같은 방식으로 만들되 replicas: 3, image: "registry.local/reporting:0.9.0", tier: batch, note: "{{ .Chart.Name }} {{ .Chart.Version }}" 로 두고 의존성을 확정하세요. helm template insight /root/hc-library/reporting 결과를 /root/hc-library/out/reporting.yaml 에 저장합니다. 두 렌더 결과의 라벨 키 목록이 같고 값만 다른지 확인하세요.

라이브러리가 값어치를 내는 지점이 바로 여기입니다 — 라벨을 붙이는 규칙은 한 곳에만 있고, 차트마다 다른 것은 values 뿐입니다. 라벨 키만 뽑아 비교하려면 yq '.metadata.labels | keys' 를 두 파일에 대해 돌려 보세요.

values 안에 든 템플릿 문자열을 다시 렌더한다

라이브러리에 platform-lib.configmap 을 추가하세요(/root/hc-library/platform-lib/templates/_configmap.tpl). 이름은 <fullname>-note, data.note 는 .Values.note 를 tpl 로 한 번 더 렌더해 따옴표로 감쌉니다. 두 차트에 templates/configmap.yaml(include 한 줄)을 추가하세요. note 값은 4·5단계에서 이미 values.yaml 에 넣어 두었습니다 — 중괄호가 든 채로 그대로 두세요. 라이브러리를 고쳤으니 두 차트에서 의존성을 다시 받아야 합니다. 두 렌더 파일을 다시 저장하세요.

tpl <문자열> <컨텍스트> 는 문자열을 그 자리에서 템플릿으로 해석합니다. values 에 적힌 중괄호는 그냥 글자라서 이 함수를 거치지 않으면 그대로 출력됩니다. helm dependency update 는 그 시점의 라이브러리를 tgz 로 떠서 charts/ 에 넣습니다 — 라이브러리를 고친 뒤 다시 받지 않으면 옛 사본이 계속 쓰입니다.

부모가 같은 이름을 다시 정의하면 무엇이 이기나

/root/hc-library/billing/templates/_override.tpl 에 같은 이름 platform-lib.deployment 를 다시 정의하세요. 내용은 라이브러리 것과 같되 metadata.annotations 에 platform.labhub.io/overridden-by: billing 한 줄을 더합니다. 두 차트를 다시 렌더해 저장하고, billing 에만 그 애너테이션이 붙는지 확인하세요.

헬름의 템플릿 이름은 차트 전체에서 하나의 이름 공간을 씁니다. 같은 이름이 둘이면 나중에 읽힌 것이 이기고, 부모 차트의 템플릿이 서브차트보다 나중에 읽힙니다. 그래서 이름 앞에 차트 이름을 붙이는 관례가 생겼습니다 — 우연한 충돌을 막으려는 것입니다.

라이브러리가 무엇을 지웠는지 숫자로 적는다

/root/hc-library/out/report.json 에 이 실습의 결과를 정리하세요. 키는 library(라이브러리 차트 이름), type(차트 종류), installable(불리언), consumers(소비 차트 이름 배열), billing_replicas, reporting_replicas(각 렌더의 실제 replicas 숫자), shared_label_keys(라이브러리 헬퍼가 만드는 라벨 키 개수), override_winner(같은 이름을 다시 정의해 이긴 차트 이름) 여덟 개입니다.

숫자는 지어내지 말고 렌더 결과에서 읽으세요 — yq '. | select(.kind=="Deployment") | .spec.replicas' out/billing.yaml 처럼 뽑을 수 있습니다. installable 은 따옴표 없는 불리언이어야 합니다.