Chart Hooks

Hooks let a chart run resources at defined points in a release lifecycle, such as a pre-install job.

Syntaxannotations: "helm.sh/hook": pre-install

Hooks let you run Kubernetes resources at specific moments during a release — before installing, after upgrading, before deleting, and so on. They are perfect for database migrations or setup jobs.

Declaring a hook

Add the annotation helm.sh/hook to any resource (commonly a Job). The value is the lifecycle event.

Common hook points

  • pre-install / post-install
  • pre-upgrade / post-upgrade
  • pre-delete / post-delete
  • test — run by helm test.

Weights and deletion

helm.sh/hook-weight orders multiple hooks; helm.sh/hook-delete-policy controls when the hook resource is cleaned up.

Example

Example · yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ .Release.Name }}-migrate
  annotations:
    "helm.sh/hook": pre-upgrade
    "helm.sh/hook-weight": "0"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: "myapp:{{ .Values.image.tag }}"
          command: ["./migrate.sh"]

When to use it

  • A chart author adds a pre-install Job hook that creates the database schema before any application Pod starts, ensuring the schema is ready on first deploy.
  • A developer uses a pre-upgrade hook to back up a ConfigMap containing critical runtime configuration before an upgrade replaces it.
  • A platform team uses a post-delete hook to clean up Persistent Volume Claims that Kubernetes does not remove automatically when a release is uninstalled.

More examples

pre-install migration Job

Defines a Job that runs before install and upgrade to apply database migrations; deleted automatically on success.

Example · yaml
# templates/migrate-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ .Release.Name }}-migrate
  annotations:
    "helm.sh/hook": pre-install,pre-upgrade
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: {{ .Values.image.repository }}:{{ .Values.image.tag }}
          command: ["./migrate"]

post-install test hook

Creates a smoke-test Pod after install that curls the health endpoint to confirm the service started correctly.

Example · yaml
# templates/smoke-test.yaml
apiVersion: v1
kind: Pod
metadata:
  name: {{ .Release.Name }}-smoke-test
  annotations:
    "helm.sh/hook": post-install
    "helm.sh/hook-delete-policy": before-hook-creation
spec:
  restartPolicy: Never
  containers:
    - name: test
      image: curlimages/curl:latest
      command: ["curl", "-f", "http://{{ include \"myapp.fullname\" . }}/health"]

View hooks for a release

Lists all hook resources associated with a release along with their hook annotations and current status.

Example · bash
helm get hooks my-release -n production

Related

helm testshelm best practices

Discussion

  • Be the first to comment on this lesson.