Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 38 ยท Dependencies and Hooks

Hook Weights, Delete Policies and CRDs

Control hook order with hook-weight, clean up hook Jobs with hook-delete-policy, and manage CustomResourceDefinitions with the crds directory, with runnable stand-ins.

Basic hooks are easy. Production hooks need three more skills: ordering several hooks, cleaning up after them, and handling the odd case of CustomResourceDefinitions, which Helm treats specially.

Ordering with hook-weight

The annotation helm.sh/hook-weight is a number written as a string. Lower weights run first; the default is "0". Negative weights are allowed:

YAML
# 1: create schema
annotations:
  "helm.sh/hook": pre-upgrade
  "helm.sh/hook-weight": "-10"
---
# 2: run migrations
annotations:
  "helm.sh/hook": pre-upgrade
  "helm.sh/hook-weight": "0"
---
# 3: seed reference data
annotations:
  "helm.sh/hook": pre-upgrade
  "helm.sh/hook-weight": "10"

Helm waits for each hook to become ready (for a Job: to complete) before starting the next weight. Use steps of 5 or 10 so you can insert hooks later, just as this site numbers lessons.

Weights apply per hook type. A pre-upgrade weight of -10 is never compared with a post-upgrade weight.

Cleaning up with hook-delete-policy

Hook objects outlive the release operation. If a migrate Job still exists when the next upgrade tries to create it, Kubernetes refuses with "already exists". The helm.sh/hook-delete-policy annotation says when to delete the hook object:

Policy Deletes the object
before-hook-creation Before a new hook of the same name is launched (the default if you set nothing)
hook-succeeded After the hook succeeded
hook-failed After the hook failed

You can combine values with commas. The most common production choice is:

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

That removes finished Jobs immediately (no clutter in kubectl get jobs) and still replaces a stale object if a previous attempt left one behind.

A trade-off: hook-succeeded deletes the Pod too, so its logs vanish. For hooks you want to debug, use only before-hook-creation, and let a separate TTL clean up. Jobs also support ttlSecondsAfterFinished, a Kubernetes feature that deletes a finished Job after some seconds regardless of Helm:

YAML
spec:
  ttlSecondsAfterFinished: 600
Python Stand-in: weights and delete policies across two upgrades

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The second upgrade fails on seed because it has no policy: exactly the "already exists" error teams hit in real clusters.

Hook resources beyond Jobs

Any manifest can be a hook, not only Jobs. A common pattern is a ConfigMap or Secret that a hook Job needs:

YAML
apiVersion: v1
kind: ConfigMap
metadata:
  name: migrate-config
  annotations:
    "helm.sh/hook": pre-install,pre-upgrade
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation
data:
  DB_HOST: {{ .Values.db.host | quote }}

Weight -5 makes it exist before the Job at weight 0. Helm considers a non-Job resource ready when it is created.

CRDs: the crds/ directory

CustomResourceDefinitions teach Kubernetes new resource types, such as Certificate or ServiceMonitor. They are tricky because the API must exist before any custom resource that uses it, and because deleting a CRD deletes every object of that type in the cluster.

Helm 3 handles this with a special directory:

TEXT
mychart/
  crds/
    certificate-crd.yaml
  templates/
    certificate.yaml

Rules for crds/:

  • Files here are plain YAML, not templated (no {{ }}).
  • They are installed first, before templates, and Helm waits for them to be available.
  • On helm upgrade they are not upgraded, and on helm uninstall they are not deleted. Helm refuses both on purpose, to protect your data.
  • helm install --skip-crds skips them.

Because CRDs are never upgraded, charts with evolving CRDs usually choose one of these strategies:

  1. A separate CRD chart that you upgrade deliberately (my-operator-crds).
  2. Instructions to kubectl apply -f crds/ before the upgrade.
  3. CRDs under templates/ with the annotation helm.sh/resource-policy: keep and a pre-upgrade hook, accepting the templating and ordering caveats.

The first is the cleanest and what most large operators do.

Python Stand-in: how Helm treats crds/ on each operation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Other resource annotations

  • helm.sh/resource-policy: keep stops Helm from deleting a resource on uninstall or upgrade removal. Use it for PersistentVolumeClaims and for data you cannot recreate.
  • helm.sh/hook-weight can also order non-hook resources only indirectly. Regular resources are installed in a fixed kind order (Namespaces, then ConfigMaps and Secrets, then Services, then Deployments, and so on), not by weight.

helm.sh/resource-policy: keep leaves objects behind after helm uninstall. Reinstalling the same name later can then fail with ownership errors. Clean up deliberately.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A hook with weight -10 and another with weight 5 share the pre-upgrade type. Which runs first?

    Ascending order: -10 before 5.
  2. 2. Which delete policy removes a stale hook object right before the new one is created?

    before-hook-creation prevents already-exists errors on repeat runs.
  3. 3. What does Helm do with files in crds/ during helm upgrade?

    To protect existing custom resources, Helm installs CRDs once and never changes or removes them.
  4. 4. Which annotation keeps a PVC after helm uninstall?

    resource-policy: keep tells Helm not to delete the resource.

Summary

  • hook-weight orders hooks of the same type; use steps of 5 or 10.
  • before-hook-creation,hook-succeeded is the usual cleanup policy.
  • crds/ is installed first, not templated, never upgraded or deleted; use a CRD chart for lifecycle control.
  • resource-policy: keep protects data from uninstall.

Next: Chart Repositories