github.com/flant/helm@v2.8.1+incompatible/docs/charts_hooks.md (about) 1 # Hooks 2 3 Helm provides a _hook_ mechanism to allow chart developers to intervene 4 at certain points in a release's life cycle. For example, you can use 5 hooks to: 6 7 - Load a ConfigMap or Secret during install before any other charts are 8 loaded. 9 - Execute a Job to back up a database before installing a new chart, 10 and then execute a second job after the upgrade in order to restore 11 data. 12 - Run a Job before deleting a release to gracefully take a service out 13 of rotation before removing it. 14 15 Hooks work like regular templates, but they have special annotations 16 that cause Helm to utilize them differently. In this section, we cover 17 the basic usage pattern for hooks. 18 19 ## The Available Hooks 20 21 The following hooks are defined: 22 23 - pre-install: Executes after templates are rendered, but before any 24 resources are created in Kubernetes. 25 - post-install: Executes after all resources are loaded into Kubernetes 26 - pre-delete: Executes on a deletion request before any resources are 27 deleted from Kubernetes. 28 - post-delete: Executes on a deletion request after all of the release's 29 resources have been deleted. 30 - pre-upgrade: Executes on an upgrade request after templates are 31 rendered, but before any resources are loaded into Kubernetes (e.g. 32 before a Kubernetes apply operation). 33 - post-upgrade: Executes on an upgrade after all resources have been 34 upgraded. 35 - pre-rollback: Executes on a rollback request after templates are 36 rendered, but before any resources have been rolled back. 37 - post-rollback: Executes on a rollback request after all resources 38 have been modified. 39 40 ## Hooks and the Release Lifecycle 41 42 Hooks allow you, the chart developer, an opportunity to perform 43 operations at strategic points in a release lifecycle. For example, 44 consider the lifecycle for a `helm install`. By default, the lifecycle 45 looks like this: 46 47 1. User runs `helm install foo` 48 2. Chart is loaded into Tiller 49 3. After some verification, Tiller renders the `foo` templates 50 4. Tiller loads the resulting resources into Kubernetes 51 5. Tiller returns the release name (and other data) to the client 52 6. The client exits 53 54 Helm defines two hooks for the `install` lifecycle: `pre-install` and 55 `post-install`. If the developer of the `foo` chart implements both 56 hooks, the lifecycle is altered like this: 57 58 1. User runs `helm install foo` 59 2. Chart is loaded into Tiller 60 3. After some verification, Tiller renders the `foo` templates 61 4. Tiller prepares to execute the `pre-install` hooks (loading hook resources into 62 Kubernetes) 63 5. 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. 64 6. Tiller then loads the hook with the lowest weight first (negative to positive) 65 7. Tiller waits until the hook is "Ready" 66 8. Tiller loads the resulting resources into Kubernetes. Note that if the `--wait` 67 flag is set, Tiller will wait until all resources are in a ready state 68 and will not run the `post-install` hook until they are ready. 69 9. Tiller executes the `post-install` hook (loading hook resources) 70 10. Tiller waits until the hook is "Ready" 71 11. Tiller returns the release name (and other data) to the client 72 12. The client exits 73 74 What does it mean to wait until a hook is ready? This depends on the 75 resource declared in the hook. If the resources is a `Job` kind, Tiller 76 will wait until the job successfully runs to completion. And if the job 77 fails, the release will fail. This is a _blocking operation_, so the 78 Helm client will pause while the Job is run. 79 80 For all other kinds, as soon as Kubernetes marks the resource as loaded 81 (added or updated), the resource is considered "Ready". When many 82 resources are declared in a hook, the resources are executed serially. If they 83 have hook weights (see below), they are executed in weighted order. Otherwise, 84 ordering is not guaranteed. (In Helm 2.3.0 and after, they are sorted 85 alphabetically. That behavior, though, is not considered binding and could change 86 in the future.) It is considered good practice to add a hook weight, and set it 87 to `0` if weight is not important. 88 89 90 ### Hook resources are not managed with corresponding releases 91 92 The resources that a hook creates are not tracked or managed as part of the 93 release. Once Tiller verifies that the hook has reached its ready state, it 94 will leave the hook resource alone. 95 96 Practically speaking, this means that if you create resources in a hook, you 97 cannot rely upon `helm delete` to remove the resources. To destroy such 98 resources, you need to either write code to perform this operation in a `pre-delete` 99 or `post-delete` hook or add `"helm.sh/hook-delete-policy"` annotation to the hook template file. 100 101 ## Writing a Hook 102 103 Hooks are just Kubernetes manifest files with special annotations in the 104 `metadata` section. Because they are template files, you can use all of 105 the normal template features, including reading `.Values`, `.Release`, 106 and `.Template`. 107 108 For example, this template, stored in `templates/post-install-job.yaml`, 109 declares a job to be run on `post-install`: 110 111 ```yaml 112 apiVersion: batch/v1 113 kind: Job 114 metadata: 115 name: "{{.Release.Name}}" 116 labels: 117 heritage: {{.Release.Service | quote }} 118 release: {{.Release.Name | quote }} 119 chart: "{{.Chart.Name}}-{{.Chart.Version}}" 120 annotations: 121 # This is what defines this resource as a hook. Without this line, the 122 # job is considered part of the release. 123 "helm.sh/hook": post-install 124 "helm.sh/hook-weight": "-5" 125 "helm.sh/hook-delete-policy": hook-succeeded 126 spec: 127 template: 128 metadata: 129 name: "{{.Release.Name}}" 130 labels: 131 heritage: {{.Release.Service | quote }} 132 release: {{.Release.Name | quote }} 133 chart: "{{.Chart.Name}}-{{.Chart.Version}}" 134 spec: 135 restartPolicy: Never 136 containers: 137 - name: post-install-job 138 image: "alpine:3.3" 139 command: ["/bin/sleep","{{default "10" .Values.sleepyTime}}"] 140 141 ``` 142 143 What makes this template a hook is the annotation: 144 145 ``` 146 annotations: 147 "helm.sh/hook": post-install 148 ``` 149 150 One resource can implement multiple hooks: 151 152 ``` 153 annotations: 154 "helm.sh/hook": post-install,post-upgrade 155 ``` 156 157 Similarly, there is no limit to the number of different resources that 158 may implement a given hook. For example, one could declare both a secret 159 and a config map as a pre-install hook. 160 161 When subcharts declare hooks, those are also evaluated. There is no way 162 for a top-level chart to disable the hooks declared by subcharts. 163 164 It is possible to define a weight for a hook which will help build a 165 deterministic executing order. Weights are defined using the following annotation: 166 167 ``` 168 annotations: 169 "helm.sh/hook-weight": "5" 170 ``` 171 172 Hook weights can be positive or negative numbers but must be represented as 173 strings. When Tiller starts the execution cycle of hooks of a particular Kind it 174 will sort those hooks in ascending order. 175 176 It is also possible to define policies that determine when to delete corresponding hook resources. Hook deletion policies are defined using the following annotation: 177 178 ``` 179 annotations: 180 "helm.sh/hook-delete-policy": hook-succeeded 181 ``` 182 183 When using `"helm.sh/hook-delete-policy"` annotation, you can choose its value from `"hook-succeeded"` and `"hook-failed"`. The value `"hook-succeeded"` specifies Tiller should delete the hook after the hook is successfully executed, while the value `"hook-failed"`specifies Tiller should delete the hook if the hook failed during execution.