github.com/zoumo/helm@v2.5.0+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 unmanaged
    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 write code to perform this operation in a `pre-delete`
    99  or `post-delete` hook.
   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  spec:
   126    template:
   127      metadata:
   128        name: "{{.Release.Name}}"
   129        labels:
   130          heritage: {{.Release.Service | quote }}
   131          release: {{.Release.Name | quote }}
   132          chart: "{{.Chart.Name}}-{{.Chart.Version}}"
   133      spec:
   134        restartPolicy: Never
   135        containers:
   136        - name: post-install-job
   137          image: "alpine:3.3"
   138          command: ["/bin/sleep","{{default "10" .Values.sleepyTime}}"]
   139  
   140  ```
   141  
   142  What makes this template a hook is the annotation:
   143  
   144  ```
   145    annotations:
   146      "helm.sh/hook": post-install
   147  ```
   148  
   149  One resource can implement multiple hooks:
   150  
   151  ```
   152    annotations:
   153      "helm.sh/hook": post-install,post-upgrade
   154  ```
   155  
   156  Similarly, there is no limit to the number of different resources that
   157  may implement a given hook. For example, one could declare both a secret
   158  and a config map as a pre-install hook.
   159  
   160  When subcharts declare hooks, those are also evaluated. There is no way
   161  for a top-level chart to disable the hooks declared by subcharts.
   162  
   163  It is also possible to define a weight for a hook which will help build a
   164  deterministic executing order. Weights are defined using the following annotation:
   165  
   166  ```
   167    annotations:
   168      "helm.sh/hook-weight": "5"
   169  ```
   170  
   171  Hook weights can be positive or negative numbers but must be represented as
   172  strings. When Tiller starts the execution cycle of hooks of a particular Kind it
   173  will sort those hooks in ascending order. 
   174