Understanding Helm Hooks: A Guide to Using Hooks in Your Helm Charts

Helm, the package manager for Kubernetes, is a powerful tool for managing complex Kubernetes applications. One of its advanced features is Helm hooks. Hooks allow you to intervene at different points of a Helm operation, such as before or after an install, upgrade, or delete. In this article, we’ll dive into the available hooks, explore how to define them in your Helm charts, and provide use cases for each.

What Are Helm Hooks?

Helm hooks are special annotations that can be added to resources in a Helm chart. These hooks trigger specific actions during the release lifecycle of a Helm chart. They enable developers to perform tasks like setting up prerequisites, cleaning up after an operation, or validating a deployment.

Available Helm Hooks and Use Cases

Helm provides several hooks that can be used at different stages of a Helm operation. Here’s a breakdown of the available hooks:

1. pre-install

Execution Timing: After templates are rendered but before any resources are created in Kubernetes.
Use Case: Imagine you need to create a ConfigMap or secret that your application relies on but isn’t part of the main chart. The pre-install hook can create this resource before the rest of the chart is deployed.

apiVersion: v1
kind: Job
metadata:
  name: setup-config
  annotations:
"helm.sh/hook": pre-install
spec:
  template:
spec:
  containers:
    - name: config-creator
      image: busybox
      command: ['sh', '-c', 'echo "config data" > /config/config.txt']

2. post-install

Execution Timing: After all resources are created in Kubernetes.
Use Case: If your application requires some initial data to be loaded into a database after it’s up and running, a post-install hook could be used to run a job that populates this data.

apiVersion: batch/v1
kind: Job
metadata:
  name: init-database
  annotations:
"helm.sh/hook": post-install
spec:
  template:
spec:
  containers:
    - name: db-init
      image: busybox
      command: ['sh', '-c', 'init-db-command']

3. pre-delete

Execution Timing: On a deletion request, before any resources are deleted from Kubernetes.
Use Case: Use a pre-delete hook to gracefully shut down services or to back up important data before deleting a Helm release.

apiVersion: batch/v1
kind: Job
metadata:
  name: backup-before-delete
  annotations:
"helm.sh/hook": pre-delete
spec:
  template:
spec:
  containers:
    - name: backup
      image: busybox
      command: ['sh', '-c', 'backup-command']

4. post-delete

Execution Timing: After all the release’s resources have been deleted.
Use Case: A post-delete hook could be used to clean up resources external to Kubernetes that were created by the Helm chart, such as cloud resources or database entries.

apiVersion: batch/v1
kind: Job
metadata:
  name: cleanup
  annotations:
"helm.sh/hook": post-delete
spec:
  template:
spec:
  containers:
    - name: cleanup
      image: busybox
      command: ['sh', '-c', 'cleanup-command']

5. pre-upgrade

Execution Timing: On an upgrade request, after templates are rendered, but before any resources are updated.
Use Case: Suppose you need to validate some preconditions before applying an upgrade. A pre-upgrade hook can run a job to check the environment or validate the new configuration.

apiVersion: batch/v1
kind: Job
metadata:
  name: pre-upgrade-check
  annotations:
"helm.sh/hook": pre-upgrade
spec:
  template:
spec:
  containers:
    - name: upgrade-check
      image: busybox
      command: ['sh', '-c', 'upgrade-check-command']

6. post-upgrade

Execution Timing: After all resources have been upgraded.
Use Case: After a successful upgrade, a post-upgrade hook might be used to trigger a job that verifies the application’s functionality or migrates data to a new schema.

apiVersion: batch/v1
kind: Job
metadata:
  name: post-upgrade-verify
  annotations:
"helm.sh/hook": post-upgrade
spec:
  template:
spec:
  containers:
    - name: verification
      image: busybox
      command: ['sh', '-c', 'verify-upgrade']

7. pre-rollback

Execution Timing: On a rollback request, after templates are rendered, but before any resources are rolled back.
Use Case: This hook can be used to prepare the system for rollback, such as backing up data or notifying other systems of the impending rollback.

apiVersion: batch/v1
kind: Job
metadata:
  name: pre-rollback-backup
  annotations:
"helm.sh/hook": pre-rollback
spec:
  template:
spec:
  containers:
    - name: backup
      image: busybox
      command: ['sh', '-c', 'rollback-backup']

8. post-rollback

Execution Timing: After all resources have been modified by the rollback.
Use Case: Use a post-rollback hook to verify the state of the application after a rollback or to notify external systems of the rollback’s completion.

apiVersion: batch/v1
kind: Job
metadata:
  name: post-rollback-verify
  annotations:
"helm.sh/hook": post-rollback
spec:
  template:
spec:
  containers:
    - name: verify
      image: busybox
      command: ['sh', '-c', 'verify-rollback']

9. test

Execution Timing: Executes when the helm test subcommand is invoked.
Use Case: This hook is ideal for running tests against a Helm release to verify that it is functioning as expected.

apiVersion: batch/v1
kind: Job
metadata:
  name: test-application
  annotations:
"helm.sh/hook": test
spec:
  template:
spec:
  containers:
    - name: test
      image: busybox
      command: ['sh', '-c', 'run-tests']

Annotations in Helm Hooks

In addition to defining hooks, Helm allows you to control hook execution using annotations:

• helm.sh/resource-policy: Prevents resources from being deleted after the hook is executed. Possible value:
• keep: Keeps the resource after the hook is executed, useful for debugging or retaining logs.
  
• helm.sh/hook-weight: Specifies the order in which hooks should be executed. Hooks with lower weights are executed before those with higher weights.
  
• helm.sh/hook-delete-policy: Controls when the hook resources should be deleted. Possible values include:
• hook-succeeded: Deletes the resource if the hook execution is successful.
• hook-failed: Deletes the resource if the hook execution fails.
• before-hook-creation: Deletes previous hook resources before creating new ones, ensuring only one instance of the hook is active.
  

Conclusion

Helm hooks are powerful tools that provide fine-grained control over the deployment lifecycle of your applications in Kubernetes. By understanding and leveraging these hooks, you can ensure that your Helm deployments are both robust and reliable. Make sure to use the appropriate annotations to further fine-tune the behavior of your hooks, optimizing them for your specific use case.