Lifecycle Hooks and Tests

Running ordered actions at specific lifecycle phases with hook annotations, controlling execution order with weights, cleaning up hooks with deletion policies, and validating deployments with helm test.

Overview

Lifecycle control with hooks

Helm hooks run ordered actions before or after specific events in a release lifecycle: install, upgrade, delete and rollback. Without hooks, all resources are applied in Helm's fixed sort order, with no way to coordinate stateful operations like database migrations.

> [!IMPORTANT] Hooks turn Helm's fixed apply order into a lifecycle you control: migrate first, deploy second, verify last.

The nine hook phases

Hooks are Kubernetes resources, usually Jobs or Pods, with a helm.sh/hook annotation that says when they run.

Install — pre-install — post-install
Upgrade — pre-upgrade — post-upgrade
Delete — pre-delete — post-delete
Rollback — pre-rollback — post-rollback
Explicit invocation — test (only on helm test)

The migration pattern

The most production-critical hook is pre-upgrade with a database migration Job. The migration tool (Flyway, Liquibase, Django migrate, Rails db:migrate) runs as a Job, and Helm waits for it to succeed before applying the updated Deployment.

> [!TIP] A failed migration is a safe failure mode: the old version never stops serving.

Weights and deletion policies

helm.sh/hook-weight — Execution order when several hooks share a phase; negative weights run first
helm.sh/hook-delete-policy — Automatic cleanup on success, while failed hook artifacts can be kept for debugging

Test hooks

The test hook enables helm test, which runs validation Pods against a deployed release. Unlike pre and post hooks, test hooks fire only when explicitly invoked, typically in CI after deployment.

Key concepts

helm.sh/hook annotation: The Kubernetes annotation that marks a resource as a hook and specifies its lifecycle phase(s). Multiple phases can be comma-separated: "helm.sh/hook": "pre-upgrade,pre-rollback". Resources with this annotation are not applied as part of the normal resource lifecycle — only at the specified phases.
Hook weight (helm.sh/hook-weight): String integer controlling hook execution order within a phase. Lower values execute first. Default is 0. Negative values are valid. Hooks with the same weight at the same phase execute in parallel (for Jobs) or alphabetically.
Hook deletion policies: before-hook-creation deletes the resource before launching the hook (default — prevents "resource already exists" errors on re-run). hook-succeeded deletes after successful completion. hook-failed deletes after failure. Combine: before-hook-creation,hook-succeeded retains failed hooks for debugging while cleaning up successful ones.
Pre-upgrade migration pattern: A pre-upgrade Job that runs the migration tool (Flyway, Liquibase, Django migrate). Helm waits for Job completion before updating the Deployment. On Job failure, Helm aborts the upgrade — the old application version keeps running against the old schema. Safe failure mode for stateful upgrades.
helm test: Explicitly invoked command (helm test ) that runs test hook resources. Test hooks are Pods that run validation logic and exit 0 on success. Helm reports pass/fail per test Pod. Used for smoke tests, connectivity checks, and integration validation in CI.
--no-hooks flag: Skips all hook execution for the current command. Useful for emergency operations when a hook is broken and blocking progress. helm upgrade --no-hooks is the escape hatch for "the pre-upgrade hook is hanging and the release is stuck in PENDING_UPGRADE."

When to use it

Pre-upgrade database migrations: run migration Job before Deployment update
Post-install initialization: seed a database, create an admin user, or notify a monitoring system after first install
Pre-delete cleanup: remove data or deregister from a service catalog before resources are deleted
helm test: connectivity smoke tests after every deployment in CI (curl the health endpoint, run an integration test suite)

Interview questions

How do you implement a safe database migration pattern using Helm hooks?
Explain hook execution order with weights and what happens when a hook fails.
How does helm test work and how do you write effective test hooks?
What are the hook deletion policies and which combination should you use in production?
How do you handle a situation where a pre-upgrade hook is hanging and blocking the upgrade?