Hooks

Helm provides a hook mechanism to allow chart developers to interveneat certain points in a release's life cycle. For example, you can usehooks to:

  • Load a ConfigMap or Secret during install before any other charts areloaded.
  • Execute a Job to back up a database before installing a new chart,and then execute a second job after the upgrade in order to restoredata.
  • Run a Job before deleting a release to gracefully take a service outof rotation before removing it.Hooks work like regular templates, but they have special annotationsthat cause Helm to utilize them differently. In this section, we coverthe basic usage pattern for hooks.

Hooks are declared as an annotation in the metadata section of a manifest:

  1. apiVersion: ...
  2. kind: ....
  3. metadata:
  4.   annotations:
  5.     "helm.sh/hook": "pre-install"
  6. # ...

The Available Hooks

The following hooks are defined:

  • pre-install: Executes after templates are rendered, but before anyresources are created in Kubernetes.
  • post-install: Executes after all resources are loaded into Kubernetes
  • pre-delete: Executes on a deletion request before any resources aredeleted from Kubernetes.
  • post-delete: Executes on a deletion request after all of the release'sresources have been deleted.
  • pre-upgrade: Executes on an upgrade request after templates arerendered, but before any resources are loaded into Kubernetes (e.g.before a Kubernetes apply operation).
  • post-upgrade: Executes on an upgrade after all resources have beenupgraded.
  • pre-rollback: Executes on a rollback request after templates arerendered, but before any resources have been rolled back.
  • post-rollback: Executes on a rollback request after all resourceshave been modified.
  • crd-install: Adds CRD resources before any other checks are run. This is usedonly on CRD definitions that are used by other manifests in the chart.
  • test-success: Executes when running helm test and expects the pod toreturn successfully (return code == 0).
  • test-failure: Executes when running helm test and expects the pod tofail (return code != 0).

Hooks and the Release Lifecycle

Hooks allow you, the chart developer, an opportunity to performoperations at strategic points in a release lifecycle. For example,consider the lifecycle for a helm install. By default, the lifecyclelooks like this:

  • User runs helm install foo
  • Chart is loaded into Tiller
  • After some verification, Tiller renders the foo templates
  • Tiller loads the resulting resources into Kubernetes
  • Tiller returns the release name (and other data) to the client

  • The client exitsHelm defines two hooks for the install lifecycle: pre-install andpost-install. If the developer of the foo chart implements bothhooks, the lifecycle is altered like this:

  • User runs helm install foo

  • Chart is loaded into Tiller
  • After some verification, Tiller renders the foo templates
  • Tiller prepares to execute the pre-install hooks (loading hook resources intoKubernetes)
  • Tiller sorts hooks by weight (assigning a weight of 0 by default) and by name for those hooks with the same weight in ascending order.
  • Tiller then loads the hook with the lowest weight first (negative to positive)
  • Tiller waits until the hook is "Ready" (except for CRDs)
  • Tiller loads the resulting resources into Kubernetes. Note that if the —waitflag is set, Tiller will wait until all resources are in a ready stateand will not run the post-install hook until they are ready.
  • Tiller executes the post-install hook (loading hook resources)
  • Tiller waits until the hook is "Ready"
  • Tiller returns the release name (and other data) to the client
  • The client exitsWhat does it mean to wait until a hook is ready? This depends on theresource declared in the hook. If the resources is a Job kind, Tillerwill wait until the job successfully runs to completion. And if the jobfails, the release will fail. This is a blocking operation, so theHelm client will pause while the Job is run.

For all other kinds, as soon as Kubernetes marks the resource as loaded(added or updated), the resource is considered "Ready". When manyresources are declared in a hook, the resources are executed serially. If theyhave hook weights (see below), they are executed in weighted order. Otherwise,ordering is not guaranteed. (In Helm 2.3.0 and after, they are sortedalphabetically. That behavior, though, is not considered binding and could changein the future.) It is considered good practice to add a hook weight, and set itto 0 if weight is not important.

Hook resources are not managed with corresponding releases

The resources that a hook creates are not tracked or managed as part of therelease. Once Tiller verifies that the hook has reached its ready state, itwill leave the hook resource alone.

Practically speaking, this means that if you create resources in a hook, youcannot rely upon helm delete to remove the resources. To destroy suchresources, you need to either write code to perform this operation in a pre-deleteor post-delete hook or add "helm.sh/hook-delete-policy" annotation to the hook template file.

Writing a Hook

Hooks are just Kubernetes manifest files with special annotations in themetadata section. Because they are template files, you can use all ofthe normal template features, including reading .Values, .Release,and .Template.

For example, this template, stored in templates/post-install-job.yaml,declares a job to be run on post-install:

  1. apiVersion: batch/v1
  2. kind: Job
  3. metadata:
  4.   name: "{{.Release.Name}}"
  5.   labels:
  6.     app.kubernetes.io/managed-by: {{.Release.Service | quote }}
  7.     app.kubernetes.io/instance: {{.Release.Name | quote }}
  8.     app.kubernetes.io/version: {{ .Chart.AppVersion }}
  9.     helm.sh/chart: "{{.Chart.Name}}-{{.Chart.Version}}"
  10.   annotations:
  11.     # This is what defines this resource as a hook. Without this line, the
  12.     # job is considered part of the release.
  13.     "helm.sh/hook": post-install
  14.     "helm.sh/hook-weight": "-5"
  15.     "helm.sh/hook-delete-policy": hook-succeeded
  16. spec:
  17.   template:
  18.     metadata:
  19.       name: "{{.Release.Name}}"
  20.       labels:
  21.         app.kubernetes.io/managed-by: {{.Release.Service | quote }}
  22.         app.kubernetes.io/instance: {{.Release.Name | quote }}
  23.         helm.sh/chart: "{{.Chart.Name}}-{{.Chart.Version}}"
  24.     spec:
  25.       restartPolicy: Never
  26.       containers:
  27.       - name: post-install-job
  28.         image: "alpine:3.3"
  29.         command: ["/bin/sleep","{{default "10" .Values.sleepyTime}}"]

What makes this template a hook is the annotation:

  1.   annotations:
  2.     "helm.sh/hook": post-install

One resource can implement multiple hooks:

  1.   annotations:
  2.     "helm.sh/hook": post-install,post-upgrade

Similarly, there is no limit to the number of different resources thatmay implement a given hook. For example, one could declare both a secretand a config map as a pre-install hook.

When subcharts declare hooks, those are also evaluated. There is no wayfor a top-level chart to disable the hooks declared by subcharts.

It is possible to define a weight for a hook which will help build adeterministic executing order. Weights are defined using the following annotation:

  1.   annotations:
  2.     "helm.sh/hook-weight": "5"

Hook weights can be positive or negative numbers but must be represented asstrings. When Tiller starts the execution cycle of hooks of a particular kind (ex. the pre-install hooks or post-install hooks, etc.) it will sort those hooks in ascending order.

It is also possible to define policies that determine when to delete corresponding hook resources. Hook deletion policies are defined using the following annotation:

  1.   annotations:
  2.     "helm.sh/hook-delete-policy": hook-succeeded

You can choose one or more defined annotation values:

  • "hook-succeeded" specifies Tiller should delete the hook after the hook is successfully executed.
  • "hook-failed" specifies Tiller should delete the hook if the hook failed during execution.
  • "before-hook-creation" specifies Tiller should delete the previous hook before the new hook is launched.By default Tiller will wait for 60 seconds for a deleted hook to no longer exist in the API server before timing out. Thisbehavior can be changed using the helm.sh/hook-delete-timeout annotation. The value is the number of seconds Tillershould wait for the hook to be fully deleted. A value of 0 means Tiller does not wait at all.

Defining a CRD with the crd-install Hook

Custom Resource Definitions (CRDs) are a special kind in Kubernetes. They providea way to define other kinds.

On occasion, a chart needs to both define a kind and then use it. This is donewith the crd-install hook.

The crd-install hook is executed very early during an installation, beforethe rest of the manifests are verified. CRDs can be annotated with this hook sothat they are installed before any instances of that CRD are referenced. In thisway, when verification happens later, the CRDs will be available.

Here is an example of defining a CRD with a hook, and an instance of the CRD:

  1. apiVersion: apiextensions.k8s.io/v1beta1
  2. kind: CustomResourceDefinition
  3. metadata:
  4.   name: crontabs.stable.example.com
  5.   annotations:
  6.     "helm.sh/hook": crd-install
  7. spec:
  8.   group: stable.example.com
  9.   version: v1
  10.   scope: Namespaced
  11.   names:
  12.     plural: crontabs
  13.     singular: crontab
  14.     kind: CronTab
  15.     shortNames:
  16.     - ct

And:

  1. apiVersion: stable.example.com/v1
  2. kind: CronTab
  3. metadata:
  4.   name: {{ .Release.Name }}-inst

Both of these can now be in the same chart, provided that the CRD is correctlyannotated.

Automatically delete hook from previous release

When a helm release, that uses a hook, is being updated, it is possible that the hook resource might already exist in the cluster. In such circumstances, by default, helm will fail trying to install the hook resource with an "… already exists" error.

A common reason why the hook resource might already exist is that it was not deleted following use on a previous install/upgrade. There are, in fact, good reasons why one might want to keep the hook: for example, to aid manual debugging in case something went wrong. In this case, the recommended way of ensuring subsequent attempts to create the hook do not fail is to define a "hook-delete-policy" that can handle this: "helm.sh/hook-delete-policy": "before-hook-creation". This hook annotation causes any existing hook to be removed, before the new hook is installed.

If it is preferred to actually delete the hook after each use (rather than have to handle it on a subsequent use, as shown above), then this can be achieved using a delete policy of "helm.sh/hook-delete-policy": "hook-succeeded,hook-failed".