Helm in Practice

Helm Release Lifecycle and Hooks

Once charts and their dependencies are prepared, Helm orchestrates a series of steps to install or modify the Kubernetes resources. Throughout these operations, hooks provide a way for chart developers to inject custom logic at key points. Helm defines a variety of hooks that charts can implement by adding special annotations to their template resources.

The Available Hooks

The available hooks include:

• pre-install and post-install: These hooks run before any resources are created, or after all resources are created, on a fresh install (helm install)

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

• pre-upgrade and post-upgrade: These hooks run before upgrading any resources, or after all have been updated, during a Helm upgrade (helm upgrade).

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

• pre-delete and post-delete: These hooks run before deleting resources, or after all resources are removed, during uninstall (helm uninstall).

annotations:
    "helm.sh/hook": pre-delete

• pre-rollback and post-rollback: These hooks run before and after performing a rollback operation (helm rollback).

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

• test: The test hook runs when the user invokes helm test to validate that a release is working as expected (helm test).

annotations:
  "helm.sh/hook": test

Hooks are simply template files with an annotation like helm.sh/hook: pre-install (and similarly for other hook points). They can be any Kubernetes resource (often Jobs, but also ConfigMaps, etc.) and are not included in the normal installation manifest. Instead, Helm will execute them at the specified point in the lifecycle.

By default, multiple hooks of the same type are executed in alphabetical order, but you can assign a numeric weight to control ordering if needed.

ℹ️ Hooks are sorted by weight, then by kind, then by name.

Helm will also typically wait for hook resources to complete if they are Jobs/Pods (treating completion as Ready), or consider them ready immediately once created if they are other kinds. If a hook Job fails, the entire release action fails. Hook resources are not persisted in the release's state, so by default, Helm won't manage or delete them after they run. You can, however, specify a hook deletion policy to clean them up - for example, helm.sh/hook-delete-policy: hook-succeeded to remove a Job after it succeeds (otherwise it might remain in the cluster; nothing harmful, but it could clutter things up).

By default, Helm will remove prior hook jobs before a new run (before-hook-creation) to avoid conflicts.

annotations:
  "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded

Here is a full example of a job that runs as a pre-install hook to initialize a database schema before the main application is deployed:

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 }}
    app.kubernetes.io/version: {{ .Chart.AppVersion }}
    helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}"
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "1"
    "helm.sh/hook-delete-policy": hook-succeeded,before-hook-creation
spec:
  template:
    spec:
      containers:
        - name: {{ .Chart.Name }}-init-db-container
          image: "alpine:3.14"
          imagePullPolicy: IfNotPresent
          env:
            - name: DB_HOST
              value: "{{ .Values.database.host }}"
            - name: DB_USER
              value: "{{ .Values.database.user }}"
            - name: DB_PASSWORD