Working with Chart Hooks

1. Defining Hook Annotations

Annotation	Value	Description
helm.sh/hook	`pre-install`, `post-install`, `pre-upgrade`, `post-upgrade`, `pre-delete`, `post-delete`, `pre-rollback`, `post-rollback`, `crd-install`, `job-template`	Defines the type of hook. Determines when the hook runs during chart lifecycle events.
helm.sh/hook-weight	`-10` to `10`	Controls the order of execution for hooks of the same type. Lower values execute first.
helm.sh/hook-delete-policy	`before-hook-creation`, `hook-succeeded`, `hook-failed`	Determines when the hook resource is deleted. `before-hook-creation` deletes before each run; `hook-succeeded` deletes after success; `hook-failed` deletes after failure.

Example: Defining a Pre-Install Hook

apiVersion: v1
kind: ConfigMap
metadata:
  name: example-config
  annotations:
    helm.sh/hook: pre-install
    helm.sh/hook-weight: -5
    helm.sh/hook-delete-policy: hook-succeeded
data:
  key: value

2. Using pre-install Hook

Property	Description	Values
name	Unique name for the hook	`pre-install`
type	Hook type to execute	`pre-install`
weight	Execution order priority (lower numbers execute first)	`0`
failurePolicy	Behavior if hook fails	`ignore`, `fail`

Example: pre-install hook in values.yaml

hooks:
  - name: pre-install
    type: pre-install
    weight: 0
    failurePolicy: ignore

Example: pre-install hook in chart template

apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "myapp.fullname" . }}-pre-install
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "-1"
spec:
  template:
    spec:
      containers:
      - name: pre-install
        image: busybox:1.35
        command: ['sh', '-c', 'echo "Running pre-install hook"']
      restartPolicy: Never

3. Using post-install Hook

Field	Description	Values
post-install	Defines the hook type	`post-install`
metadata.annotations.helm.sh/hook	Hook annotation to specify the hook type	`post-install`
metadata.annotations.helm.sh/hook-weight	Defines the order of execution for hooks	`-10` to `10`
metadata.annotations.helm.sh/hook-delete-policy	Defines when the hook resource is deleted	`before-hook-creation`, `hook-succeeded`, `hook-failed`

Example: post-install Hook in a Chart

apiVersion: batch/v1
kind: Job
metadata:
  name: post-install-job
  annotations:
    helm.sh/hook: post-install
    helm.sh/hook-weight: "1"
    helm.sh/hook-delete-policy: hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: post-install-container
        image: alpine:latest
        command: [&#34;echo&#34;, &#34;Post-install job executed&#34;]
      restartPolicy: Never

Note: The post-install hook runs after all resources in the chart are installed. It is useful for tasks like initializing a database or running a one-time job.

4. Using pre-upgrade Hook

The pre-upgrade hook is executed before a Helm release upgrade operation begins. It runs in the same context as other hooks and can be used to prepare the environment or perform necessary setup tasks before the upgrade process starts.

Property	Values	Description
hook	`pre-upgrade`	Defines the hook type to execute before an upgrade.
weight	`0`	Defines the order in which hooks are executed. Lower values run first.
annotations	`{}`	Metadata to attach to the hook, useful for identifying or filtering hooks.

Example: pre-upgrade Hook Configuration

apiVersion: batch/v1
kind: Job
metadata:
  name: pre-upgrade-job
  annotations:
    "helm.sh/hook": "pre-upgrade"
    "helm.sh/hook-weight": "-5"
spec:
  template:
    spec:
      containers:
      - name: pre-upgrade-container
        image: busybox:1.35
        command:
        - /bin/sh
        - -c
        - echo "Running pre-upgrade tasks..."
      restartPolicy: Never

Note: The pre-upgrade hook runs only during upgrade operations and does not execute on install or rollback actions.

5. Using post-upgrade Hook

Field	Description	Values
post-upgrade	Hook type that runs after a release upgrade	`post-upgrade`

Example: post-upgrade Hook Configuration

hooks:
  - name: post-upgrade-job
    type: post-upgrade
    path: templates/post-upgrade-hook.yaml

Note: The post-upgrade hook runs after the upgrade process completes, ensuring any necessary cleanup or post-processing steps are executed.

6. Using pre-delete Hook

Field	Description	Values
name	Name of the hook	`string`
type	Hook type (e.g., pre-delete)	`pre-delete`
weight	Execution order (lower runs first)	`integer`
annotations	Metadata for hook	`map[string]string`

Example: pre-delete hook in values.yaml

hooks:
  - name: cleanup
    type: pre-delete
    weight: -10
    annotations:
      "helm.sh/hook-delete-policy": hook-succeeded

Note: The pre-delete hook runs before a release is deleted.

Warning: Ensure cleanup logic does not interfere with release deletion.

7. Using post-delete Hook

The post-delete hook is executed after a release's resources have been deleted. It is useful for cleanup operations or sending notifications.

Field	Description	Values
name	Unique name for the hook	`post-delete-hook`
type	Hook type (must be `pre-install`, `post-install`, etc.)	`post-delete`
weight	Execution order within the same hook type (lower numbers execute first)	`-1`

Example: post-delete Hook in a Chart

hooks:
  - name: post-delete-hook
    type: post-delete
    weight: -1
    events:
      - delete

Note: The post-delete hook runs after the release is deleted and cannot be used to prevent deletion.

8. Using pre-rollback Hook

The pre-rollback hook is executed before a rollback operation begins. It allows you to perform any necessary cleanup or preparation steps before the rollback is applied.

Hook Type	Description	Execution Context	Use Case
pre-rollback	Executed before a rollback operation begins	Before rollback starts	Prepare for rollback, backup data

Example: pre-rollback Hook Configuration

hooks:
  - name: pre-rollback-hook
    type: pre-rollback
    path: scripts/pre-rollback.sh
    weight: -5

Note: The pre-rollback hook runs in the same context as the rollback operation and can be used to ensure that any necessary state is preserved or restored before the rollback proceeds.

9. Using post-rollback Hook

Field	Description	Values
post-rollback	Defines the hook to run after a rollback operation completes	`release-hook`

Example: post-rollback Hook Definition

hooks:
  - name: post-rollback-example
    type: release-hook
    event: post-rollback
    path: templates/post-rollback-job.yaml

Note: The post-rollback hook runs after the rollback operation completes and can be used to perform cleanup or notifications.

10. Setting Hook Weight

Property	Values	Description
hook.weight	`0`	Defines the order of execution for hooks. Lower values execute first.

Example: Setting Hook Weight in Chart.yaml

apiVersion: v2
name: my-app
version: 1.0.0
hooks:
  - name: pre-install-hook
    weight: -10
    events:
      - pre-install
  - name: post-install-hook
    weight: 10
    events:
      - post-install

Note: Hook weights can be positive or negative integers. Hooks with lower weight values execute before hooks with higher values.

11. Setting Hook Deletion Policy

Policy	Description	Usage
hook-delete-policy	Defines when a hook resource is deleted after it has run	`hook-delete-policy: HookSucceeded`
hook-delete-policy	Deletes the hook resource only if it failed to run	`hook-delete-policy: HookFailed`

Example: Hook Deletion Policy Configuration

apiVersion: batch/v1
kind: Job
metadata:
  name: example-job
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-delete-policy": HookSucceeded
spec:
  template:
    spec:
      containers:
      - name: example
        image: busybox
        command: ["echo", "Hello World"]
      restartPolicy: Never

12. Using test Hook

Property	Description	Values
hook	Defines the type of hook	`test`
annotations	Metadata annotations for the hook	`helm.sh/hook: test`
weight	Execution order priority (higher number = later)	`0` to `100`

Example: Test Hook in Chart

apiVersion: batch/v1
kind: Job
metadata:
  name: test-job
  annotations:
    helm.sh/hook: test
    helm.sh/hook-delete-policy: hook-succeeded
spec:
  template:
    spec:
      containers:
      - name: test-container
        image: busybox
        command: ["sh", "-c", "echo 'Running tests'"]
      restartPolicy: Never

Note: Test hooks run as Kubernetes Jobs and are deleted after completion.

Test Hook Usage

Used to run tests for the chart
Executed as Kubernetes Jobs
Deleted after successful completion