Chart Hooks

Chart Hooks are special annotations within Helm charts that allow users to intervene at specific points during the lifecycle of a chart installation, upgrade, or deletion. These hooks enable the execution of Kubernetes resources or jobs at predefined moments, offering fine-grained control over resource management beyond the default Helm behavior. By defining hooks, chart authors can orchestrate complex workflows such as database migrations, pre-install validations, or cleanup tasks.

Hook Definition and Annotation

Chart Hooks are implemented by adding a specific annotation to Kubernetes resource manifests inside a Helm chart. This annotation is placed under the metadata.annotations field and follows the key format:

"helm.sh/hook": <hook-event>

The <hook-event> value specifies the lifecycle event at which the resource will be executed. A resource annotated with this key is not treated as a normal Kubernetes resource managed by Helm but rather as a hook resource triggered at the designated time.

Multiple hook events can be specified by separating them with commas.

Example snippet of a hook annotation:

metadata:
  annotations:
    "helm.sh/hook": pre-install,pre-upgrade

Supported Hook Events

Helm supports several hook lifecycle events that define when the hook resource is executed relative to chart operations:

• pre-install: Runs before any resources are installed during a fresh install.
• post-install: Runs after all resources are installed during a fresh install.
• pre-delete: Runs before resources are deleted during a helm delete operation.
• post-delete: Runs after resources are deleted during a helm delete operation.
• pre-upgrade: Runs before any resources are upgraded during a helm upgrade.
• post-upgrade: Runs after all resources are upgraded during a helm upgrade.
• pre-rollback: Runs before a rollback operation is executed.
• post-rollback: Runs after a rollback operation is completed.
• test: Runs when helm test is executed.

These hook events allow chart authors to inject custom logic at critical points in the deployment lifecycle.

Hook Execution Behavior

When Helm encounters a resource with a hook annotation during chart installation, upgrade, or deletion, it executes the resource according to the hook event timing. Hook resources are applied like regular Kubernetes manifests but are managed separately from the main release manifest. This separation means:

• Hook resources are not included in the release’s manifest history.
• Hook resources are cleaned up automatically based on configured policies.
• Helm waits for the successful completion of hook resources, respecting Kubernetes readiness and job completion semantics before proceeding.

Hook Weight and Ordering

When multiple hooks are assigned to the same event, Helm determines their execution order using the helm.sh/hook-weight annotation. This annotation allows chart developers to specify the relative priority of hooks:

• Hooks with lower weight values run before those with higher weights.
• If no weight is specified, the default is zero.
• Weights can be negative or positive integers.

Example:

metadata:
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "-5"

This mechanism is crucial for coordinating complex sequences where certain tasks must precede others within the same lifecycle phase.

Hook Deletion Policies

Hooks can specify deletion policies that control whether hook resources are retained or removed after execution. This is achieved using the helm.sh/hook-delete-policy annotation, which can include one or more of the following values:

• hook-succeeded: Delete the hook resource after successful completion.
• hook-failed: Delete the hook resource if it fails.
• before-hook-creation: Delete existing hook resources before creating new ones in the same lifecycle event.

Example:

metadata:
  annotations:
    "helm.sh/hook": post-install
    "helm.sh/hook-delete-policy": hook-succeeded

These policies help avoid resource clutter and ensure that temporary hook jobs or pods do not persist unnecessarily.

Common Use Cases for Chart Hooks

• Database Migrations: Running a job to migrate database schemas before an upgrade or install.
• Pre-Installation Checks: Validating environment conditions or prerequisites.
• Cleanup Tasks: Removing temporary resources or performing cleanup after uninstall.
• Testing: Running integration or smoke tests post-installation using the test hook.
• Custom Rollback Logic: Executing specific commands or cleanup during rollback phases.

Best Practices and Considerations

• Hooks should be idempotent and safe to run multiple times where possible.
• Because hooks execute asynchronously, ensure proper readiness or completion semantics to avoid Helm proceeding prematurely.
• Use hook weights and delete policies to avoid race conditions and orphaned resources.
• Avoid complex logic in hooks that could delay or block Helm operations indefinitely.
• Test hooks thoroughly to ensure they behave correctly in all lifecycle scenarios.

Example of a Pre-Install Hook Job

apiVersion: batch/v1
kind: Job
metadata:
  name: migrate-job
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "0"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: migrate
        image: myapp/migration:latest
        command: ["./migrate.sh"]
      restartPolicy: Never

In this example, the job runs before the main resources are installed, performing necessary migrations and is deleted automatically after it succeeds.

Summary

Chart Hooks are a powerful Helm feature that enables insertion of custom Kubernetes resources at specific points of the chart lifecycle. By leveraging annotations for hook events, weights, and deletion policies, chart authors can extend Helm’s deployment process to handle complex workflows, validations, and cleanup with precision and control. Proper use of hooks improves chart flexibility and robustness in dynamic deployment environments.