헬름 배우기 - Helm, 차트, 릴리스, 수명주기, 훅, 차트 빌드, 차트 테스트

예전에 헬름 배우기 책을 읽으면서 필요한 내용들을 정리 했었는데 정리되지 않은 내용들이 많아 이해가 되지 않을 수도 있습니다. 참고만 해주시면 좋겠습니다.

헬름 환경 준비

헬름 설정

상위 레포지토리 추가

헬름은 사용자가 설정된 차트 리포지토리를 관리할 수 있도록 repo 하위 명령을 제공한다.

$ helm repo add $REPO_NAME $REPO_URL
$ helm repo list
$ helm repo remove
$ helm repo update

헬름 차트 설치

차트 찾기

헬름 차트는 차트 리포지토리에 게시하여 사용할 수 있다. 차트 레포지토리는 패키지화된 차트를 저장하고 공유할 수 있는 위치다. 깃헙 페이지 http 서버 등에 호스팅 될 수 있다.

다양한 차트 레포가 존재한다. 따라서 사용 사례에 맞는 차트 레포를 좀 더 쉽게 찾을 수 있도록, 헬름 허브라는 플랫폼을 만들었다. 헬름 허브는 상위 차트 레포에 대한 중앙화된 저장소다.

레포가 이전에 추가되지 않은 경우, 사용자는 helm search hub 명령을 실행해 모든 공용 차트 리포지토리에서 사용 가능한 헬름 차트를 검색해야 한다. 레포가 추가된 후, 사용자는 helm search repo 명령을 실행해 특정 레포를 검색할 수 있다.

$ helm search hub wordpress
$ helm search hub wordpress --max-col-width=0 # 결과 잘리지 않게
$ helm search hub wordpress --output yaml # yaml 형식으로 출력

차트 레포 추가하기

$ helm repo add bitnami https://charts.bitnami.com/bitnami
$ helm repo list
$ helm search repo bitnami --output yaml # bitnami라는 단어르  포함하는 레포의 차트 보기
$ helm search repo wordpress
$ helm search repo wordpress --versions

차트 정보 보기

$ helm show chart bitnami/wordpress # 차트 정의, 메타데이터
$ helm show readme bitnami/wordpress
$ helm show values bitnami/wordpress
$ helm show all # 차트 정의, README, value

차트 설치

설치

$ helm install [NAME] [CHART] [flags]
$ helm install wordpress bitnami/wordpress --values=wordpress-value.yaml --namespace wordpress

$ helm get notes # 헬름 설치 결과

사용자가 특정 릴리스에 대해 알고 싶은 정보가 있을 때, get 사용

$ helm get hooks # hooks은 애플리케이션 수명 주기의 특정 단계에서 헬름이 수행하는 작업
$ helm get manifest # 쿠버 리소스 목록
$ helm get notes
$ helm get values
$ helm get all

추가 설치 정보

--set, --values

명령햇에서 값을 전달하거나 yaml을 통해 값을 지정할 수 있다. --values 선호.

릴리스 업그레이드

$ helm upgrade [RELEASE] [CHART] [flags]

업그레이드 중 값 재사용 및 재설정

• --reuse-values: 업그레이드 시 마지막 릴리스 값을 재사용
• --reset-values: 업그레이드 시 값을 차트 기본 값으로 재설정

--values 플래그를 사용하지 않그 그냥 업그레이드 하면 --reuse-values 플래그가 추가된다.

업그레이드 과정에서 하나 이상의 값이 제공될 경우 헬름은 자동으로 --reset-values 플래그를 적용한다. 이렇게 될 경우 --set, --values 플래그와 함께 제공된 개별 속성을 제외하고 모든 값이 기본값으로 다시 설정된다.

릴리스 롤백

$ helm history # 리비전 이력 정보

helm get 명령은 --revision 플래그를 사용해 특정 리비전 번호를 지정할 수 있다.

$ helm get values [name] --revision [num]

이런식으로 helm get의 모든 옵션에 revision 옵션 가능.

릴리스 삭제

$ helm uninstall [name]

헬름 차트 이해

YAML 형식 이해

name: LearnHelm # :뒤에 무조건 공백 있어야함


configuration: | 
  server.port=8443
  logging.file.path=/var/log


ingress: 
  enable: true # 허용되는 불리언 값 : yes, no, on, off, y, n Y, N


# 리스트
servicePorts: 
  - 8080
  - 8443


# 객체로 이루어진 리스트
deployment: 
  env: 
    - name: MY_VAR
      value: MY_VALUE
    - name: SERVICE_NAME
      value: MY_SERVICE

차트 구조

• Charts.yaml: 헬름 차트에 대한 메타데이터를 포함하고 있는 파일
• templates/: YAML 형식의 쿠버네티스 리소스를 포함하고 있는 디렉토리
• values.yaml: 차트의 기본 값을 포함하고 있는 파일
• charts/: 헬름 차트가 의존하고 있는 차트가 포함된 디렉토리
• crds/: 리소스에 앞서 설치된 CRD yaml 리소스

차트 템플릿

# values.yaml
chapterNumber: 4
chapterName: Understanding Helm Charts
---

# resource.yaml
env: 
  - name: CHAPTER_NUMBER 
    value: {{ .Values.chapterNumber }}
  - name: CHAPTER_NAME
    values: {{ .Values.chapterName }}

내장 객체 목록

• .Release.Name: 릴리스 이름
• .Release.Namespace: 네임스페이스
• .Release.Revision: 리비전 번호
• .Values: values.yaml 파일의 값, 사용자가 제공한 값을 참조하는데 사용
• .Chart.Name, .Chart.Version, .Chart.Appversion…: Chart.yaml의 필드를 참조. Chart.$Field 컨벤센을 따름
• .Files.Get: 차트 디렉토리 내 파일을 가져오기 위해 사용
• .Files.AsSecrets: 파일을 Base64 인코딩 문자열로 반환하여 차트 디렉토리에 파일로 시크릿 데이터를 생성
• .Files.AsConfig: 파일의 내용을 YAM 맵으로 반환하여 차트 디렉토리에 파일로 컨피그맵 데이터를 생성
• .Capabilities.APIVersions: 사용 가능한 API 버전 목록
• .Template.Name: 해당 객체가 사용하는 템플릿 파일에 대한 상대 경로

.scope는 전역 범위를 나타내며 모든 객체와 이전 표에 정의된 공통 객체를 표시

values.schema.json 파일

values 파일에서 특정 스키마를 적용하는 데 사용. 이 스키마는 설치 또는 업그레이드 과정에서 제공된 값의 유효성 검사르 수행하는데 사용

흐름 제어를 통한 세분화된 템플릿 처리

• if/else: 파일의 섹션을 조건부로 포함하거나 제외하는 데 사용
• with: 참조되는 값의 범위를 수정하는데 사용
• range: 값의 목록을 반복하는 데 사용

readinessProbe:
{{- if .Vvalues.probeType.httpGet }}
  httpGet: 
    path: /healthz
    port: 8080
    scheme: HTTP
{{- else }}
  tcpSocket: 
    port: 8080
{{- end }}
  initialDelaySeconds: 30
  periodSeconds: 10

중괄호 뒤에 상요된 대시는 처리 후 공백을 제거해야 함을 나타냄. 여는 중괄호 뒤에 사용된 대시는 중괄호 앞의 공백을 제거하고, 닫는 중괄호 바로 앞에 사용된 대시는 중괄호 뒤의 공백을 제거.

with 액션을 사용해 값의 범위를 수정할 수 있다. 이 액션은 참조되는 값의 블록이 깊게 중첩된 경우에 유용하다.

application: 
  resources: 
    limits: 
      cpu: 100m
      memory: 512Mi
---

cpu: {{ .Values.application.resoures.limits.cpu }}
memory: {{ .Values.application.resources.limits.memory }}
---

{{- with .Values.application.resources.limits }}
cpu: {{ .cpu }}
memory: {{ .memory }}
{{- end }}

range 액션을 사용해 반복적인 작업을 수행할 수 있다.

servicePorts: 
  - name: http
    port: 8080
  - name: https
    port: 8443
  - name: jolokia
    port: 8778
---

spec: 
  ports: 
{{- range .Values.servicePorts }}
  - name: {{- name }} # ??
  port: {{ .port }}
  {{- end }}

range, with 구문안에서 전역 범위를 적용하려면 달러($)를 붙인다.

{{- range .Values.servicePorts }}
  - name: {{ $.Release.Name }}-{{ .name }}
  port: {{ .port }}
{{- end }}

템플릿 변수

{{ $myvar := 'Hello World!' }}
{{ $myvar := .Values.greeting }}
---

data: 
  greeting.txt: | 
    {{ $myvar }}
---

data: 
  greetings.txt: | 
{{- range $inex, $value := .Values.greetings }}
    Greeting {{ $index }}: {{ $Value }} 
{{- end }}
---

data: 
  greetings.txt: |
{{- range $key, $val := .Values.greetings }}
    Greeting in {{ $key }}: {{ $val }}
{{- end }}

함수 및 파이프라인을 사용한 복잡한 처리

indent 함수는 들여쓰기 할 공백의 수와 들여쓰 할 문자열을 입력으로 사용한다.

# functionName arg1 arg2 ... 이런 형태
data: 
  application-config: |-
{{ indent 4 .Values.config }}

파이프라인은 한 명령의 출력이 다른 명령에 대한 입력으로 제공된다.

data: 
  application-config: |-
{{ .Values.config | indent 4 | quote }}
# config 값을 4칸 들여쓰고, 인용 부호 붙임

Go 템플릿 기능

• data
• default
• fail
• include: Go 템플릿 실행 후 결과 반환
• nindent: 새 행 추가 후 들여쓰기
• indent
• now
• quote
• required: 사용자 입력
• splitList: 문자열을 문자열 목록으로 분할
• toYaml

if 액션 불리언 연산자

• and
• or
• not
• eq
• ne(not equal)
• lt(less than)
• le(less than or equal to)
• gt(greater than)
• ge(greater than or equal to)

명명된 템플릿으로 코드 재사용 활성화

리소스 라벨 같은거 반복되기 때문에 재사용하기. 재사용 가능한 템플릿을 생성할 수 있는 명명된 템플릿이라고 하는 구성을 제공.

명명된 템플릿은 templates/ 디렉토리 하위에 정의되며 밑줄 문자로 시작하고 .tpl 파일 확장자로 끝나는 파일 (_helpers.tpl)

.tpl 파일 안에서 define 액션을 취할 수 있다.

{{- define 'mychart.labels' }}
labels: 
  'app.kubernetes.io/instance': {{ .Release.Name }}
  'app.kubernetes.io/managed-by': {{ .Release.Service '}}

define 액션은 템플릿 이름을 인수로 사용한다. 일반적인 규칙은 $CHART_NAME.$TEMPLATE_NAME이다.

위의 템프릿을 사용하려면, include 함수를 쓰면 된다.

# include [TEMPLATE_NAME] [SCOPE]
metadata: 
  name: {{ .Release.Name }}
{{- include 'mychart.labels' . | indent 2 }}
# 이게 아래처럼 됨
---
metadata: 
  name: {{ .Release.Name }}
  labels: 
    'app.kubernetes.io/instance': template-demonstration # 예시
    'app.kubernetes.io/managed-by': Helm # 예시

라이브러리 차트

Chart.yaml 파일에 정의된 type 필드가 존재하는데 application, library 2가지가 있다. 애플리케이션 차트는 쿠버네티스에 전체 애플리케이션을 배포하는 데 사용된다. 라이브러리 차트로 정의할수도 있는데 이건 여러 다른 차트에서 사용할 수 잇는 명명된 템플릿을 제공하는데 사용된다.

CR 템플릿

헬름 차트에는 템플릿을 설치하기 전에 제공해야 하는 CRD로 구성된 crds/ 폴더가 포함될 수 있다. crds/ 폴더의 예제는 다음과 같다.

차트 정의

Chart.yaml: 헬름 차트에 대한 다양한 메타데이터를 선언하는 리소스

필수 필드

• apiVersion
• name
• version

name은 케밥 케이스, 즉 대시로 단어를 구분함. (ex: redis-cluster)

version은 SemVer 2.0.0 형식을 따름. Major.Minor.Patch 형식

선택적인 필드

• appVersion
• dependencies: Chart.yaml로 정의된 차트가 종속된 차트의 목록
• deprecated
• description
• home: 프로젝트 홈페이지의 url
• icon
• keywords
• kubecersion
• maintainers
• sources: 헬름 차트 또는 애플리케이션의 소스 코드로 연결되는 url 목록
• type

차트 디펜던시 관리

헬름 차트가 의존할 수 있는 다른 차트의 리소스를 설치하는데 사용. 예로 워드프레스 차트에서 백엔드 데이터를 저장하기 위해 디펜던시로 선언한 마리아DB 차트가 있음.

dependencies 블록 필드

• name
• repository
• version
• alias
• condition: 디펜던시를 포함해야 하는지 여부를 결정
• import-values: 디펜던시 차트의 값을 상위 차트
• tags: 차트를 포함할지 여부를 결정하는 불리언값 목록?

디펜던시 다운로드

$ helm dependency build
Chart.lock 파일을 기반으로 charts/ 디렉토리를 재빌드한다. Chart.lock 파일을 찾을 수 없는 경우, 이 명령은 helm depency update 명령의 동작을 미러링한다. 

$ helm dependency list
주어진 차트에 대한 디펜던시를 나열한다. 

$ helm dependency update
Chart.yaml 파일의 내용을 기반으로 charts/ 디렉토리를 업데이트하고 Chart.lock 파일을 생성한다. 

update 명령은 아카이브 형식으로 레포에서 디펜던시를 charts/ 디렉토리에 다운로드한다. Chart.lock이라는 파일도 생성한다. 이 파일에는 적용된 디펜더시의 실제 상태가 정의되어 있다.

조건부 디펜던시

condition 필드는 사용자가 제공하거나 차트의 values.yaml 파일에 설정해야 하는 값이 나열된다.

tag 필드는 태그가 활성화된 경우 디펜던시가 포함되게된다. values.yaml 파일에 있는 tags YAML 객체 아래에 true, false로 설정할 수 있다.

자식 차트에서 값 재정의 및 참조

# my-dep이라는 자식 차트 values
replicas: 1
servicePorts: 
  - 8080
  - 8443
---

# 부모 차트
my-dep: 
  replicas: 1
  servicePorts: 
    - 8080
    - 8443
    - 8778

import-values를 통한 값 가져오기

Chart.yaml 파일의 dependencies 블록은 자식 차트의 기본 값을 가져오는 데 사용할 수 있는 import-values 필드를 지원한다.

자식 차트에서 exports 블록 아래에 선언된 값이 존재해야 한다.

# 자식 차트
exports: 
  image: 
    registry: 'my-registry.io'
    name: learnhelm/my-image
    tag: latest

부모 차트는 Chart.yaml 파일에서 import-values 필드를 정의한다.

dependencies: 
  - name: mariadb
    repository: https://charts.bitnami.com
    version: 7.x.x
    import-values: 
      - image

이렇게 하면 자식 차트의 exports.image 하위의 기본값이 부모 차트에서 다음과 같이 참조 될 수 있다.

registry: 'my-registry.io'
name: learnhelm/my-image
tag: latest

이렇게 하면 image 맵이 제거되고 그 아래에 있던 키-값 쌍만 남게 된다.

image 맵을 유치하고, exports 블록을 쓰지 않고도 수행할 수 있다.

dependencies: 
  - name: mariadb
    repository: https://charts.bitnami.com
    version: 7.x.x
    import-values: 
      - child: image
        parent: image

걍 재정의를 쓰자..ㅇㅇ

수명주기 관리

• 릴리스 주기의 여러 시점에서 작업을 수행할 수 있도록 훅 메커니즘을 제공.
• 헬름 훅은 쿠버네티스 잡으로 구성.
• templates/ 폴더에 배치, helm.sh/hook 애노테이션 주석이 추가됨
• 일반적인 리소스와 다르게, 위 애노테이션의 값을 기반으로 렌더링, 적용됨

훅 실횅

애노테이션에서 사용가능한 옵션들

• pre, post-install: 리소스 생성 전, 후
• pre, post-delete: 리소스 삭제 전, 후
• pre, post-upgrade: 업그레이드 전, 후
• pre, post-rollback: 롤백 전, 후
• test: helm test 명령 호출 시

고급 훅

실행할 수 있는 훅 수에는 제한이 없고, 동일한 수명주기 단계에 대해 여러 훅이 구성된 경우가 있을 수 있다. 기본적으로 이름을 기준으로 알파벳순으로 정렬된다. 그러나 helm.sh/weight 애노테이션을 사용해 각 훅의 가중치를 지정하여 순서를 정의할 수 있다. 가중치가 동일하면 이름을 기준으로 알파벳순으로 정렬한다.

헬름에서 훅을 추적, 관리를 하지 않아서 삭제 정책, TTL을 설정해서 훅을 제거하기 위한 전략을 세워야됨

helm.sh/hook-delete-policy 애놑테이션을 훅과 연관된 잡에 지정할 수 있다. 이 애노테이션의 값에 따라 리소스를 제거할 때 액션을 취해야하는 시기를 결정한다.

애노테이션의 값

• before-hook-creation: 훅이 시작되기 전에 이전 리소스를 삭제
• hook-succeeded: 훅이 성공적으로 실행된 후 리소스 삭제
• hook-failed: 실행 중 훅이 실패하면 리소스 삭제

잡의 ttlSecondsAfterFinished 속성을 사용하여 완료된 후 리소스가 유지되는 시간을 제한하는 TTL 메커니즘을 정의하는 옵션을 제공한다.

표준 차트 템플릿이 제거되지 않고 특정 리소스를 유지하기를 원할 수 있다. 이 때는 아래의 옵셥을 활용한다.

'helm.sh/resource-policy': keep

헬름 차트 패키징

helm package [차트이름] [...] [플래그]

헬름 차트 빌드

헬름 차트 생성

helm create guestbook

# Charts.yaml
dependencies:
  - name: redis
    version: 17.3.x
    repository: https://charts.bitnami.com/bitnami

helm dependency update guestbook

helm show values charts/redis-17.3.8.tgz > redis-values.yaml # 참고 redis values 파일 만들기

# values.yaml
redis: 
  image: 
    registry: 
    repository: 
    tag: 
  fullnameOverride: redis
  auth: 
    enabled: false
  commonConfiguration: |-
    appendonly no

~~

차트 mac m1에 맞게 수정해서 돌림

방명록 헬름 차트 개선

• 데이터베이스 백업, 복원을 위한 수명주기 훅
• 유효한 값만 제공될 수 있도록 입력에 대한 유효성 검사

시나리오

• pre-upgrade: 데이터베이스 스냅샷 생성
• pre-rollback: 스냅샷으로 복원

데이터 스냅샷 생성을 위한 사전 업그레이드 훅 생성

• 레디스 데이터 스냅샷은 dump.
  완료

입력 유효성 검사

fail

{{- $변수 := list "", "" }}
{{- if has 값 $변수 }}
~~
{{- else }}
  {{- fail "설명"}}
{{- end }}

required

{{ required '설명' 값}

github.io 헬름 차트 만들기

private repository

github 사이트 활성화

gh-pages 브랜치의 root에 index.yaml, 아카이브 있어야됨

# 패키징
helm package {chart name}
helm repo index .
# archive, index.yaml git repo로 옮기기

헬름 차트 테스트

헬름 템플릿 확인

리소스 템플릿이 쿠버네티스 클러스터에 적용되기 전에 제대로 생성됐는지 확인 필요

helm template [NAME] [CHART] [flags]
helm template my-guestbook guestbook 

리소스가 생성된 후 유효한지 확인. 쿠버네티스 API 서버와 통신하도록 helm template에 지시.

helm template my-chart $CHRT_DIRECTORY --validate

클러스터에 대한 접근 권한이 있고 차트가 유효한 쿠버네티스 리소스를 생성하는지 여부의 확인이 필요한 경우

helm install my-chart $CHART --dry-run

lint

차트가 유효하고 올바른 형식인지 확인하기 위해 사용

helm lint $GUESTBOOK_CHART_PATH

차트의 YAML 스타일에 대한 광범위한 정적 검사 수행 yamllint

brew install yamllint
helm template my-guestbook guestbook | yamllint -
# 행 확인 어려움
cat -n <(helm template my-guestbook guestbook)

위의 error들은 리스트 들여쓰기 규칙 때문임. yamllint 들여쓰기 규칙 재정의. 아래의 파일을 yamllint 실행하는 위치에 만든다.

# .yamllint.yaml
rules: 
  indentation:
    indent-sequences: whatever

helm template my-guestbook guestbook | yamllint -

차트 테스트

• helm.sh/hook: test 애노테이션이 포함된 pod 템플릿을 templates/ 디렉토리 하위에 생성
• helm test 명령어로 실행

helm install시 --wait쓰면 파드가 준비 상태가 된 시점을 좀 더 쉽게 확인할 수 있다.

# --wait쓰면 생성 완료까지 기다림. 파드가 준비 상태가 된 시점을 좀 더 쉽게 확인할 수 있다. 
helm install my-guestbook $GUESTBOOK_CHART_DIR --wait

helm test my-guestbook
helm test my-guestbook --logs # 로그 확인

ct 도구

• lint: 수정된 차트에 대한 정적 검사 및 유효성 검사를 수행
• install: 수정된 차트를 설치하고 테스트를 수행
• lint-and-install: 수정된 차트에 대해 정적 검사, 설치 테스트를 수행한다.
• list-changed: 수정된 차트 나열

lint-and-install 명령은 이전 버전의 차트에서 업그레이드를 수행해 이전 버전과의 호환성을 확인하지는 않는다. 이 기능은 --upgrade 플래그를 추가해 활성화할 수 있다.

# 빈 폴더 안에서
osdk init --plugins helm --kind Guestbook --helm-chart Learn-Helm/helm-charts/charts/guestbook

rbac

k create role gpv --resource=pods --verb=get,list -n chapter9

k create sa gb -n chapter9

k create rolebinding gpv --role=gpv --serviceaccount=chapter9:gb

helm install my-guestbook guestbook \
--set serviceAccount.name=gb \
--set serviceAccount.create=false \
-n chapter9

k auth can-i list pods --as=system:serviceaccount:chapter9:gb

k auth can-i list deploy --as=system:serviceaccount:chapter9:gb

---

출처: 헬름 배우기 - 효율적인 쿠버네티스 애플리케이션 관리(앤드류 블록 & 오스틴 듀이 지음, 이준 옮김, 에이콘 출판사)