Helm Chart Hooks Tutorial | Rafay

Helm Chart Hooks Tutorial

Helm chart hooks are a useful tool in your Kubernetes deployments and are used to perform certain actions at specific points in a release cycle. Helm supports a variety of hooks and this blog serves as a tutorial to help you quickly learn how and when you can use them to make your kubernetes management process as efficient and repeatable as possible.

What are Helm Chart Hooks?

Oftentimes a Helm chart developer may want to perform some auxiliary operations before installing the main service or upgrading the main service that are required for the main service to function in the correct manner. Typically, these operations are one time operations that are performed during a specific stage of the chart. Helm chart hooks provide the ability to perform these operations in a release lifecycle. Helm chart hooks get deployed onto the cluster as Kubernetes resources, but are cleaned up according to the hook cleanup policy. Helm chart hooks are simple Kubernetes manifest templates identified by an annotation whose value will determine when the hook should be rendered. These YAML files are bundled in the templates/ folder of a chart and are identified with helm.sh/hook(-*) annotations. In a Helm release, any manifest resource with hook annotation(s) can declare multiple stages where the hooks should be executed.

Helm Chart Hooks Use Cases

Helm chart hooks have many use cases in helping developers package complex applications. Some of the use cases include:

Loading of secrets to access a repository to pull an image before the main service is deployed
To perform DB migrations before updating the service
Cleaning up external resources after the service is deleted
Checking for the prerequisites of a service before the service is deployed

Types of Helm Chart Hooks

Helm chart hooks are categorized into the following types based on what stage of the chart life cycle they are triggered.

pre-install hooks run after templates are rendered and before any resources are created in a Kubernetes cluster
post-install hooks run after all Kubernetes resources have been loaded
pre-delete hooks run before any existing resources are deleted from Kubernetes
post-delete hooks run after all Kubernetes resources have been deleted
pre-upgrade hooks run after chart templates have been rendered and before any resources are loaded into Kubernetes
post-upgrade hooks run after all Kubernetes resources have been upgraded
pre-rollback hooks run after templates have been rendered and before any resources are rolled back
post-rollback hooks run after all resources have been modified
test hooks run when helm test subcommand is executed

How Helm Chart Hooks Are Executed

When a Helm chart containing hooks is executed, components like pods or jobs pertaining to hooks are not directly applied in a Kubernetes environment, instead when a hook is executed, a new pod is created corresponding to the hook. If successfully run, they will be in Completed state. Any resources created by a Helm hook are un-managed Kubernetes objects. In other words, uninstalling a Helm chart will not remove the underlying resources created by hooks. A separate deletion policy needs to be defined in the form of annotation if those resources need to be deleted. Three different deletion policies are supported which will decide when to delete the resources:

before-hook-creation: Delete the previous resource before a new hook is launched
hook-succeeded: Delete the resource after the hook is successfully executed
hook-failed: Delete the resource if the hook failed during execution

If no hook deletion policy annotation is specified, the before-hook-creation behavior is applied by default.

Example of a Pre-Install Helm Chart Hook (Pod)

apiVersion: v1
kind: Pod
metadata:
  name: hook-preinstall
  annotations:
    "helm.sh/hook": "pre-install"
    "helm.sh/hook-delete-policy": before-hook-creation
spec:
  containers:
  - name: hook1-container
    image: busybox
    imagePullPolicy: IfNotPresent
    command: ['sh', '-c', 'echo The pre-install hook Pod is running - hook-preinstall && sleep 15']
  restartPolicy: Never
  terminationGracePeriodSeconds: 0

Example of a Post-Install Helm Chart Hook (Pod)

apiVersion: v1
kind: Pod
metadata:
  name: hook-postinstall
  annotations:
    "helm.sh/hook": "post-install"
spec:
  containers:
  - name: hook2-container
    image: busybox
    imagePullPolicy: IfNotPresent
    command: ['sh', '-c', 'echo post-install hook Pod is running - hook-postinstall && sleep 10']
  restartPolicy: Never
  terminationGracePeriodSeconds: 0

Example of a Pre-Install Helm Chart Hook (Job)

apiVersion: batch/v1
kind: Job
metadata:
  name: job-hook-preinstall
  annotations:
    "helm.sh/hook": "pre-install"
spec:
  template:
    spec:
      containers:
      - name: pre-install
        image: busybox
        imagePullPolicy: IfNotPresent
        command: ['sh', '-c', 'echo pre-install Job Pod is Running ; sleep 5']
      restartPolicy: OnFailure
      terminationGracePeriodSeconds: 0
      backoffLimit: 3
      completions: 1
      parallelism: 1

Example of a Post-Install Helm Chart Hook (Job)

apiVersion: batch/v1
kind: Job
metadata:
  name: job-hook-postinstall
  annotations:
    "helm.sh/hook": "post-install"
spec:
  template:
    spec:
      containers:
      - name: post-install
        image: busybox
        imagePullPolicy: IfNotPresent
        command: ['sh', '-c', 'echo post-install Pod is Running ; sleep 10']
      restartPolicy: OnFailure
      terminationGracePeriodSeconds: 0
      backoffLimit: 3
      completions: 1
      parallelism: 1

Example of Pre-Install Helm Chart Hooks with Weight:

apiVersion: batch/v1
kind: Job
metadata:
  name: job-hook-1
  annotations:
    "helm.sh/hook": "pre-install"
    "helm.sh/hook-weight": "-2"

apiVersion: batch/v1
kind: Job
metadata:
  name: job-hook-2
  annotations:
    "helm.sh/hook": "pre-install"
    "helm.sh/hook-weight": "5"

apiVersion: batch/v1
kind: Job
metadata:
  name: job-hook-3
  annotations:
    "helm.sh/hook": "pre-install"
    "helm.sh/hook-weight": "10"

Tags:

Helm charts and helm chart hooks are incredibly useful tools to help you manage the definition and deployment of Kubernetes applications. And Rafay makes it easy to manage it all.