[Helm] helm hook 사용법

Helm Hook이란

Helm Hook은 Kubernetes에서 Helm을 이용해 리소스를 배포하거나 삭제하는 과정 중에 특정 타이밍에 맞추어 추가 작업을 자동으로 실행할 수 있는 기능입니다. 즉, 단순히 애플리케이션만 배포하는 것이 아닌 설치 전/후, 업그레이드 전/후, 삭제 전/후 등 필요한 다양한 작업을 미리 정의해 놓을 수 있습니다. Helm Hook을 이용하면 복잡한 배포 시나리오를 쉽게 관리할 수 있고 특히 데이터베이스 초기화, 마이그레이션, 시스템 점검, 백업 그리고 CI/CD파이프라인이나 대규모 운영환경에 적용하여 다양한 자동화 작업에 활용할 수 있습니다.
이번 문서에서는 Helm Hook의 개념과 사용법에 대해 알아보겠습니다.

 

Helm Hook 작성법

Helm Hook은 Helm 차트의 메타데이터에 annotations을 추가하여 정의합니다. annotations은 `helm.sh/hook` 키를 사용하여 후크의 종류를 지정합니다. 예를 들어 설치 전에 실행되는 후크는 다음과 같이 정의할 수 있습니다.

metadata:
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-delete-policy": before-hook-creation

Helm Hook 이벤트 종류

Helm Hook은 다음과 같은 이벤트 종류를 지원합니다.

• pre-install: 차트 설치 전에 실행
• post-install: 차트 설치 후에 실행
• pre-upgrade: 차트 업그레이드 전에 실행
• post-upgrade: 차트 업그레이드 후에 실행
• pre-delete: 차트 삭제 전에 실행
• post-delete: 차트 삭제 후에 실행
• pre-rollback: 차트 롤백 전에 실행
• post-rollback: 차트 롤백 후에 실행

Helm delete policy 종류

• before-hook-creation: 후크가 실행되기 전에 기존 후크를 삭제합니다. (기본값)
• hook-succeeded: 후크가 성공적으로 실행된 후에 삭제합니다.
• hook-failed: 후크가 실패한 후에 삭제합니다.

 

Helm Hook 예제

이번 실습에서는 간단하게 nginx deployment와 service를 배포하고, 배포 후에 실행되는 후크를 정의하여 배포가 완료된 후에 nginx의 상태를 확인하는 예제를 만들어 보겠습니다.

 

1. Helm 차트 생성

helm create nginx-hook-test

 

2. values.yaml 수정

replicaCount: 1

image:
  repository: nginx
  tag: "1.25.0"
  pullPolicy: IfNotPresent

service:
  type: NodePort
  port: 80

nodePort: 30080

 

3. templates/deployment.yaml 수정

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
        ports:
        - containerPort: 80

 

4. templates/service.yaml 수정

apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  type: {{ .Values.service.type }}
  selector:
    app: nginx
  ports:
  - protocol: TCP
    port: {{ .Values.service.port }}
    targetPort: 80
    nodePort: {{ .Values.nodePort }}

 

5. templates/hook.yaml 생성

Helm Hook을 정의하는 Job 리소스를 생성합니다. 이 Job은 Helm 차트가 설치되기 전에 실행됩니다. 이번 테스트에서는 아주 간단하게 실습을 하기 위해 메시지를 출력하고 5초 후에 종료되록 설정하였습니다. 현업에서는 데이터베이스 초기화, 마이그레이션, 시스템 점검, 백업 등 다양한 작업을 수행할 수 있으니 본인의 환경에 맞게 수정하여 사용하시면 됩니다.

apiVersion: batch/v1
kind: Job
metadata:
  name: preinstall-hook
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-delete-policy": before-hook-creation
spec:
  template:
    spec:
      containers:
      - name: preinstall
        image: busybox
        command: ['sh', '-c', 'echo "Helm Pre-install Hook 실행 완료!" && sleep 5']
      restartPolicy: Never

 

6. 불필요한 파일 삭제

나머지 불필요한 파일은 모두 삭제하고 아래와 같이 Helm 차트를 구성하여 실행합니다.

├── Chart.yaml
├── templates
│   ├── deployment.yaml
│   ├── hook.yaml
│   └── service.yaml
└── values.yaml

 

7. Helm 실행

helm install nginx-hook-test .

# # Helm Hook 실행 결과
kubectl get pods -w
NAME                    READY   STATUS      RESTARTS   AGE
preinstall-hook-rb6bw   1/1     Running     0          3s
preinstall-hook-rb6bw   0/1     Completed   0          9s
nginx-55b5b869bd-b424z  0/1     Pending     0          0s
nginx-55b5b869bd-b424z  1/1     Running     0          1s

preinstall-hook이 실행 후에 5초 후에 종료되고 nginx가 실행되는 것을 확인할 수 있습니다.

 

8. Helm Hook 삭제

위와 같이 테스트를 진행하였다면 이제는 Helm Hook 삭제에 대해 알아보겠습니다. Helm Hook은 기본적으로 Helm 차트가 삭제될 때 자동으로 삭제되지 않습니다. 따라서 수동으로 삭제해주어야 합니다. 아래와 같이 Helm 차트를 삭제하고 Job 리소스를 수동으로 삭제합니다.
만약 Helm Hook이 성공하였을 시 자동적으로 삭제되도록 설정을 하기 위해서는 before-hook-creation 대신에 hook-succeeded를 사용하면 job 리소스가 성공적으로 실행된 후에 자동적으로 삭제됩니다.

helm delete nginx-hook-test
kubectl delete job preinstall-hook

 

참조

https://helm.sh/ko/docs/topics/charts_hooks/