Helm Hook을 통한 리소스 생성 순서 제어

Posted Jan 15, 2025 Updated Oct 11, 2025

By KKamJi

views 8 min read

Kubernetes 환경에서 Helm을 Package Manager로 사용해 애플리케이션을 배포하는 과정에서 종종 데이터베이스 초기화, 스키마 마이그레이션, 캐시 무효화 등의 이유로 특정 리소스가 먼저 생성되어야 하는 경우를 마주할 때가 있습니다.

이때 Helm Hook을 사용하면 특정 이벤트(예: pre-install, post-install, pre-delete, post-delete)가 발생할 때 특정 작업을 수행할 수 있습니다.

1. Helm Hook이란?

Helm Hook은 Helm Chart 설치, 업그레이드, 삭제 등의 특정 LifeCycle Event가 발생할 때 실행되는 작업을 정의할 수 있는 기능입니다.

Helm Hook은 YAML 형식의 Kubernetes Manifest파일에 Metadata Annotation으로 아래와 같이 선언할 수 있습니다.

  
apiVersion: v1
kind: Pod
metadata:
  annotations:
    helm.sh/hook: pre-install
    helm.sh/hook-weight: "5"
    helm.sh/hook-delete-policy: hook-succeeded
spec:
  containers:
    - name: job
      image: busybox
      args: ['sh', '-c', 'echo "Hello, World!"']

2. Helm Hook Attributes

Hook 설정에 주로 사용하는 대표적인 어노테이션과 설명입니다.

Hook 속성	설명	예시 값
helm.sh/hook	Hook의 타입을 지정	pre-install, post-delete
helm.sh/hook-weight	동일한 Hook 타입 내에서 실행 순서 제어(낮은 값부터 실행)	0, 1, 2, … (default: 0)
helm.sh/hook-delete-policy	Hook 실행 완료 후 리소스를 어떻게 처리할지 결정	hook-succeeded, hook-failed

3. Helm Hook Types

Helm에서 지원하는 주요 Hook 타입과 활용 예시입니다.

Hook 타입	설명	활용 예시
pre-install	차트 설치 전 실행되는 훅	DB 스키마 세팅, 기본 데이터 로딩 등 사전 준비 단계
post-install	차트 설치 후 실행되는 훅	배포 확인, 알림 전송, 외부 시스템 연동
pre-upgrade	차트 업그레이드 전 실행	기존 리소스 백업, DB 마이그레이션 스크립트 실행, 캐시 갱신
post-upgrade	차트 업그레이드 후 실행	배포 성공 알림 전송, 새로운 기능 활성화 작업
pre-delete	차트 삭제 전 실행	외부 의존 리소스 정리 (스토리지, DNS 레코드), 인증 토큰 폐기
post-delete	차트 삭제 후 실행	리소스 정리 완료 알림, 로그 기록
pre-rollback	롤백 전 실행	롤백 대상 리소스 상태 백업, 알림 처리 자동화
post-rollback	롤백 후 실행	롤백 성공/실패 알림 전송, 리소스 상태 복구
test	`helm test` 명령 실행 시, 테스트용 리소스(또는 작업)	애플리케이션 기능 검증, API 통합 테스트, CI 파이프라인과 연동 시 유용
test-success	`helm test` 실행 후, 성공 시 호출	성공 알림 전송, 모니터링 시스템 업데이트
test-failure	`helm test` 실행 후, 실패 시 호출	실패 원인 로깅, 운영팀에 알림 전송

4. Hook 실행 예제

Helm Chart를 설치할 때 pre-install, post-install , hook-weight 을 사용한 예시입니다.
디렉토리는 다음과 같고 pre-install-job-w1.yaml, pre-install-job-w2.yaml, pre-install-job-w3.yaml 파일은 각각 helm.sh/hook-weight 의 값을 1, 2, 3으로 주었습니다.
예상대로라면 hook-weight 값이 낮은 순서대로 실행되고 pre-install -> Deployment -> post-install 순서로 실행이 되어야 합니다.

❯ tree
.
├── Chart.yaml
├── charts
├── templates
│   ├── NOTES.txt
│   ├── _helpers.tpl
│   ├── deployment.yaml
│   ├── post-install-job.yaml
│   ├── pre-install-job-w1.yaml
│   ├── pre-install-job-w2.yaml
│   └── pre-install-job-w3.yaml
└── values.yaml

Helm Chart에 대해 더 자세한 내용은 https://github.com/KKamJi98/kubernetes/tree/main/Helm/kkamji-hook-prac 에서 확인하실 수 있습니다.

4.1. `pre-install` Manifest 파일

  
apiVersion: batch/v1
kind: Job
metadata:
  name: pre-install-job-w1
  annotations:
    helm.sh/hook: pre-install # pre-install 훅 지정
    helm.sh/hook-delete-policy: hook-succeeded # Job 성공 시 자동 삭제
    helm.sh/hook-weight: "1" # 훅 실행 우선순위 (낮을수록 먼저 실행)
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: amazonlinux-pre-install
        image: public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
        command: [ "/bin/sh" ]
        args:
        - "-c"
        - |
          echo "start"
          sleep 10
          echo "done"

4.2. deployment(main) Manifest 파일

  
# deployment(main)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kkamji-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kkamji
  template:
    metadata:
      labels:
        app: kkamji
    spec:
      containers:
        - name: kkamji
          image: nginx
          ports:
            - containerPort: 80

4.3. `post-install` Manifest 파일

  
apiVersion: batch/v1
kind: Job
metadata:
  name: post-install-job
  annotations:
    helm.sh/hook: post-install
    helm.sh/hook-delete-policy: hook-succeeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
      - name: amazonlinux-pre-install
        image: public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
        command: [ "/bin/sh" ]
        args:
        - "-c"
        - |
          echo "start"
          sleep 10
          echo "done"

5. Helm Chart 설치 (Hook 확인인)

kubectl get pod -w 명령어로 Helm Chart가 리소스를 생성하는 순서를 확인하겠습니다.

  
❯ helm install hook-prac . -f values.yaml
NAME: hook-prac
LAST DEPLOYED: Wed Jan 15 18:20:03 2025
NAMESPACE: hook-prac
STATUS: deployed
...
...
...

❯ kubectl get pod -w
NAME                       READY   STATUS    RESTARTS   AGE
pre-install-job-w1-pgfb8   0/1     Pending   0          0s
pre-install-job-w1-pgfb8   0/1     Pending   0          0s
pre-install-job-w1-pgfb8   0/1     ContainerCreating   0          0s
pre-install-job-w1-pgfb8   1/1     Running             0          1s
pre-install-job-w1-pgfb8   0/1     Completed           0          11s
pre-install-job-w1-pgfb8   0/1     Completed           0          12s
pre-install-job-w1-pgfb8   0/1     Completed           0          13s
pre-install-job-w2-g9cnt   0/1     Pending             0          0s
pre-install-job-w2-g9cnt   0/1     Pending             0          0s
pre-install-job-w2-g9cnt   0/1     ContainerCreating   0          0s
pre-install-job-w2-g9cnt   1/1     Running             0          1s
pre-install-job-w2-g9cnt   0/1     Completed           0          11s
pre-install-job-w2-g9cnt   0/1     Completed           0          12s
pre-install-job-w2-g9cnt   0/1     Completed           0          13s
pre-install-job-w3-jqc7p   0/1     Pending             0          0s
pre-install-job-w3-jqc7p   0/1     Pending             0          0s
pre-install-job-w3-jqc7p   0/1     ContainerCreating   0          0s
pre-install-job-w3-jqc7p   1/1     Running             0          1s
pre-install-job-w3-jqc7p   0/1     Completed           0          11s
pre-install-job-w3-jqc7p   0/1     Completed           0          12s
pre-install-job-w3-jqc7p   0/1     Completed           0          13s
pre-install-job-w1-pgfb8   0/1     Completed           0          39s
pre-install-job-w1-pgfb8   0/1     Completed           0          39s
pre-install-job-w2-g9cnt   0/1     Completed           0          26s
pre-install-job-w2-g9cnt   0/1     Completed           0          26s
pre-install-job-w3-jqc7p   0/1     Completed           0          13s
pre-install-job-w3-jqc7p   0/1     Completed           0          13s
kkamji-deployment-7979949d4-zg5sp   0/1     Pending             0          0s
kkamji-deployment-7979949d4-zg5sp   0/1     Pending             0          0s
kkamji-deployment-7979949d4-zg5sp   0/1     ContainerCreating   0          0s
post-install-job-v74xs              0/1     Pending             0          0s
post-install-job-v74xs              0/1     Pending             0          1s
post-install-job-v74xs              0/1     ContainerCreating   0          1s
post-install-job-v74xs              1/1     Running             0          2s
kkamji-deployment-7979949d4-zg5sp   1/1     Running             0          3s
post-install-job-v74xs              0/1     Completed           0          12s
post-install-job-v74xs              0/1     Completed           0          13s
post-install-job-v74xs              0/1     Completed           0          14s
post-install-job-v74xs              0/1     Completed           0          14s
post-install-job-v74xs              0/1     Completed           0          14s

6. 결과

예상대로 hook-weight가 낮은 pre-install Job들이 순서대로 실행된 뒤, 메인 Deployment가 생성되고, 마지막으로 post-install Job이 실행되었습니다.
이를 통해 hook-weight 값이 낮은 순서대로 실행되고 pre-install -> Deployment -> post-install 순서로 실행이 되었음을 확인할 수 있습니다.

궁금하신 점이나 추가해야 할 부분은 댓글이나 아래의 링크를 통해 문의해주세요.
Written with KKamJi

Kubernetes, Helm

This post is licensed under CC BY 4.0 by the author.