차트 후크 (Chart Hooks)

릴리스의 수명주기 어느 시점에 특별한 작업을 끼워 넣고 싶을 때가 있어요. 예를 들어 설치 전에 ConfigMap/Secret을 먼저 올린다거나, 새 차트를 설치하기 전에 DB 백업 Job을 돌리는 식이죠. Helm의 훅(hook) 메커니즘이 정확히 그런 지점에 개입할 수 있게 해 줘요.

출처

Helm provides a hook mechanism to allow chart developers to intervene at certain points in a release's life cycle. 출처: https://helm.sh/docs/topics/charts_hooks/

사용 가능한 훅

훅은 정해진 시점에 따라 이름이 달라져요.

애노테이션 값	실행 시점
`pre-install`	템플릿 렌더 후, 리소스를 만들기 전
`post-install`	모든 리소스를 클러스터에 올린 뒤
`pre-delete`	리소스를 지우기 전
`post-delete`	릴리스의 모든 리소스를 지운 뒤
`pre-upgrade`	템플릿 렌더 후, 리소스를 갱신하기 전
`post-upgrade`	모든 리소스가 업그레이드된 뒤
`pre-rollback`	템플릿 렌더 후, 롤백 적용 전
`post-rollback`	롤백이 모두 적용된 뒤
`test`	`helm test` 하위 명령이 실행될 때

초기 Helm 버전의 crd-install 훅은 Helm 3에서 제거됐고, 대신 crds/ 디렉터리가 그 역할을 해요.

훅이 릴리스 수명주기에 끼어드는 방식

예를 들어 helm install foo의 기본 흐름은 이렇게 진행돼요.

사용자가 helm install foo 실행
Helm 라이브러리의 install API 호출
검증 후 foo 템플릿 렌더
결과 리소스를 쿠버네티스에 로드
릴리스 객체를 클라이언트에 반환
클라이언트 종료

차트 작성자가 pre-install·post-install 훅을 정의하면 이 흐름 사이에 훅 실행 단계가 끼어들어요. 훅 리소스가 준비(Ready)될 때까지 Helm이 기다린다는 점이 핵심이에요. 훅이 Job이나 Pod면 완료될 때까지 기다리고, 훅이 실패하면 릴리스도 실패해요. 그 외 리소스 종류는 쿠버네티스가 로드(추가/갱신)만 하면 준비로 간주해요.

훅 리소스는 릴리스에 포함되지 않아요

훅이 만든 리소스는 릴리스의 일부로 추적·관리되지 않아요. Helm이 훅이 준비됐는지 확인하고 나면 그 리소스는 그대로 두죠. 그래서 릴리스를 지워도 훅 리소스는 자동으로 지워지지 않고요, 절대 지우면 안 되는 자원은 helm.sh/resource-policy: keep 애노테이션을 달아 보호해요.

훅 작성하기

훅은 특별한 애노테이션을 가진 쿠버네티스 매니페스트 파일일 뿐이에요. 템플릿이므로 .Values, .Release, .Template 등 일반 템플릿 기능을 전부 쓸 수 있어요. templates/post-install-job.yaml에 post-install로 실행될 Job을 선언한 예시를 볼게요.

apiVersion: batch/v1
kind: Job
metadata:
  name: "{{ .Release.Name }}"
  labels:
    app.kubernetes.io/managed-by: {{ .Release.Service | quote }}
    app.kubernetes.io/instance: {{ .Release.Name | quote }}
    helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
  annotations:
    "helm.sh/hook": post-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    metadata:
      name: "{{ .Release.Name }}"
    spec:
      restartPolicy: Never
      containers:
      - name: post-install-job
        image: "alpine:3.3"
        command: ["/bin/sleep", "{{ default "10" .Values.sleepyTime }}"]

이 템플릿을 훅으로 만드는 핵심은 이 한 줄이에요.

annotations:
  "helm.sh/hook": post-install

훅 순서와 삭제 정책

같은 종류의 훅이 여러 개면 **helm.sh/hook-weight**로 실행 순서를 정해요. 가중치는 문자열이어야 하고 음수·양수 모두 가능하며, Helm은 같은 종류의 훅을 가중치 오름차순으로 정렬해 실행해요. 하나의 리소스가 여러 훅을 처리할 수도 있어요("helm.sh/hook": post-install,post-upgrade).

훅 리소스가 언제 지워질지는 **helm.sh/hook-delete-policy**로 정해요.

before-hook-creation: 새 훅이 시작되기 전에 이전 리소스를 삭제 (기본값)
hook-succeeded: 훅이 성공적으로 끝난 뒤 삭제
hook-failed: 훅이 실패했을 때 삭제

정책을 지정하지 않으면 기본적으로 before-hook-creation 동작이 적용돼요.

차트 후크 (Chart Hooks)