Helm Hooks: Running Operations During a Release

WHY IT EXISTS A standard Helm chart deploys a set of resources. But sometimes you need to perform procedural tasks around that deployment, like backing up a database or waiting for an external dependency. Hooks solve this by letting you run imperative tasks within a declarative release process.

THE MENTAL MODEL Think of Helm Hooks as stagehands for your application's deployment. They run before the main act (pre-install), after the show (post-install), or during scene changes (pre-upgrade). They are regular Kubernetes resources, like a Job, with a special annotation telling Helm to treat them as part of the release machinery, not just the application itself.

HOW IT WORKS You add a special annotation, helm.sh/hook, to any resource in your chart's templates. For example, helm.sh/hook: pre-install. When Helm encounters this, it doesn't deploy it with the main resources. Instead, it runs it during the specified lifecycle phase. For resources like Jobs or Pods, Helm waits for them to complete successfully. If they fail, the entire release operation (install, upgrade, etc.) fails. For other resources like ConfigMaps, Helm just waits for Kubernetes to acknowledge their creation. You can control the execution order of multiple hooks using the helm.sh/hook-weight annotation, where lower weights run first.

WHEN TO USE IT Use hooks for operational tasks tied to a release. Common use cases include: first, running a database schema migration Job before an application upgrade (pre-upgrade); second, loading initial configuration or secrets before the main application starts (pre-install); third, performing a graceful shutdown or backup before deleting a release (pre-delete).

WHEN NOT TO USE IT Don't use hooks for resources that are a permanent part of your application. If a ConfigMap or Service needs to exist for the life of the application, it should be a regular chart resource, not a hook. Also, avoid long-running tasks in hooks if possible, as they are blocking operations that will delay the release process. For complex, multi-stage orchestration, a dedicated operator might be a better fit than a chain of hooks.

ONE CANONICAL EXAMPLE A common pattern is to use a pre-upgrade hook to run a database migration. You would define a Kubernetes Job in your chart that contains the migration container. You would annotate this Job with helm.sh/hook: pre-upgrade. When a user runs helm upgrade, Helm first runs your migration Job. It will wait for the Job to complete successfully before proceeding to update the main application Deployment. If the migration Job fails, the upgrade is aborted, leaving the existing release untouched.