Hooks & release lifecycle

Run jobs at install/upgrade.

Intermediate12 min · lesson 8 of 12

Sometimes you need to run something at a point in a release’s life — migrate a database before an upgrade, seed data after install, back up before a change. Helm hooks are ordinary Kubernetes resources (usually Jobs) annotated to run at a lifecycle phase: pre-install, post-install, pre-upgrade, post-upgrade, pre-delete, post-delete. Helm runs the hook, waits for it, and then continues the release.

HELM HOOK LIFECYCLE PHASES

Install

pre-install

before manifests apply

post-install

after resources are up (e.g. seed data)

Upgrade

pre-upgrade

e.g. migrate DB before pods roll

post-upgrade

after new revision applies

Delete

pre-delete

e.g. back up before removal

post-delete

cleanup after uninstall

templates/migrate-job.yaml

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ .Release.Name }}-migrate
  annotations:
    "helm.sh/hook": pre-upgrade,pre-install
    "helm.sh/hook-weight": "0"                 # ordering among hooks
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - { name: migrate, image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}", command: ["/app/migrate"] }

Weights and delete policies

hook-weight orders multiple hooks in a phase (lower runs first); hook-delete-policy controls when the hook resource is cleaned up (before-hook-creation to clear a prior run, hook-succeeded to remove it on success). A failing hook aborts the release, which is what you want for a migration that must succeed before new pods roll — the upgrade stops rather than shipping code against an un-migrated schema.

Hooks are outside the release’s normal reconcile

Hook resources are not part of the release’s tracked manifests the way normal templates are, so they are not upgraded or rolled back with the app and, without a delete policy, can pile up. Set an explicit hook-delete-policy, keep hook Jobs idempotent (a re-run must be safe), and remember a hook failure blocks the whole release — design migrations to be safely retryable.

Subcharts & dependenciesLibrary charts & reuse