github.com/cloudposse/helm@v2.2.3+incompatible/docs/charts_tips_and_tricks.md (about)

     1  # Chart Development Tips and Tricks
     2  
     3  This guide covers some of the tips and tricks Helm chart developers have
     4  learned while building production-quality charts.
     5  
     6  ## Know Your Template Functions
     7  
     8  Helm uses [Go templates](https://godoc.org/text/template) for templating
     9  your resource files. While Go ships several built-in functions, we have
    10  added many others.
    11  
    12  First, we added almost all of the functions in the
    13  [Sprig library](https://godoc.org/github.com/Masterminds/sprig). We removed two
    14  for security reasons: `env` and `expandenv` (which would have given chart authors
    15  access to Tiller's environment).
    16  
    17  We also added one special template function: `include`. The `include` function
    18  allows you to bring in another template, and then pass the results to other
    19  template functions.
    20  
    21  For example, this template snippet includes a template called `mytpl.tpl`, then
    22  lowercases the result, then wraps that in double quotes.
    23  
    24  ```yaml
    25  value: {{include "mytpl.tpl" . | lower | quote}}
    26  ```
    27  
    28  ## Quote Strings, Don't Quote Integers
    29  
    30  When you are working with string data, you are always safer quoting the
    31  strings than leaving them as bare words:
    32  
    33  ```
    34  name: {{.Values.MyName | quote }}
    35  ```
    36  
    37  But when working with integers _do not quote the values._ That can, in
    38  many cases, cause parsing errors inside of Kubernetes.
    39  
    40  ```
    41  port: {{ .Values.Port }}
    42  ```
    43  
    44  ## Using the 'include' Function
    45  
    46  Go provides a way of including one template in another using a built-in
    47  `template` directive. However, the built-in function cannot be used in
    48  Go template pipelines.
    49  
    50  To make it possible to include a template, and then perform an operation
    51  on that template's output, Helm has a special `include` function:
    52  
    53  ```
    54  {{ include "toYaml" $value | indent 2 }}
    55  ```
    56  
    57  The above includes a template called `toYaml`, passes it `$value`, and
    58  then passes the output of that template to the `indent` function.
    59  
    60  Because YAML ascribes significance to indentation levels and whitespace,
    61  this is one great way to include snippets of code, but handle
    62  indentation in a relevant context.
    63  
    64  ## Automatically Roll Deployments When ConfigMaps or Secrets change
    65  
    66  Often times configmaps or secrets are injected as configuration
    67  files in containers.
    68  Depending on the application a restart may be required should those
    69  be updated with a subsequent `helm upgrade`, but if the
    70  deployment spec itself didn't change the application keeps running
    71  with the old configuration resulting in an inconsistent deployment.
    72  
    73  The `sha256sum` function can be used together with the `include`
    74  function to ensure a deployments template section is updated if another
    75  spec changes: 
    76  
    77  ```yaml
    78  kind: Deployment
    79  spec:
    80    template:
    81      metadata:
    82        annotations:
    83          checksum/config: {{ include (print $.Chart.Name "/templates/secret.yaml") . | sha256sum }}
    84  [...]
    85  ```
    86  
    87  ## Tell Tiller Not To Delete a Resource
    88  
    89  Sometimes there are resources that should not be deleted when Helm runs a
    90  `helm delete`. Chart developers can add an annotation to a resource to prevent
    91  it from being deleted.
    92  
    93  ```yaml
    94  kind: Secret
    95  metadata:
    96    annotations:
    97      "helm.sh/resource-policy": keep
    98  [...]
    99  ```
   100  
   101  (Quotation marks are required)
   102  
   103  The annotation `"helm.sh/resource-policy": keep` instructs Tiller to skip this
   104  resource during a `helm delete` operation. _However_, this resource becomes
   105  orphaned. Helm will no longer manage it in any way. This can lead to problems
   106  if using `helm install --replace` on a release that has already been deleted, but
   107  has kept resources.
   108  
   109  ## Using "Partials" and Template Includes
   110  
   111  Sometimes you want to create some reusable parts in your chart, whether
   112  they're blocks or template partials. And often, it's cleaner to keep
   113  these in their own files.
   114  
   115  In the `templates/` directory, any file that begins with an
   116  underscore(`_`) is not expected to output a Kubernetes manifest file. So
   117  by convention, helper templates and partials are placed in a
   118  `_helpers.tpl` file.
   119  
   120  ## Complex Charts with Many Dependencies
   121  
   122  Many of the charts in the [official charts repository](https://github.com/kubernetes/charts)
   123  are "building blocks" for creating more advanced applications. But charts may be
   124  used to create instances of large-scale applications. In such cases, a single
   125  umbrella chart may have multiple subcharts, each of which functions as a piece
   126  of the whole.
   127  
   128  The current best practice for composing a complex application from discrete parts
   129  is to create a top-level umbrella chart that
   130  exposes the global configurations, and then use the `charts/` subdirectory to
   131  embed each of the components.
   132  
   133  Two strong design patterns are illustrated by these projects:
   134  
   135  **SAP's [OpenStack chart](https://github.com/sapcc/openstack-helm):** This chart
   136  installs a full OpenStack IaaS on Kubernetes. All of the charts are collected
   137  together in one GitHub repository.
   138  
   139  **Deis's [Workflow](https://github.com/deis/workflow/tree/master/charts/workflow):**
   140  This chart exposes the entire Deis PaaS system with one chart. But it's different
   141  from the SAP chart in that this master chart is built from each component, and
   142  each component is tracked in a different Git repository. Check out the
   143  `requirements.yaml` file to see how this chart is composed by their CI/CD
   144  pipeline.
   145  
   146  Both of these charts illustrate proven techniques for standing up complex environments
   147  using Helm.
   148  
   149  ## YAML is a Superset of JSON
   150  
   151  According to the YAML specification, YAML is a superset of JSON. That
   152  means that any valid JSON structure ought to be valid in YAML.
   153  
   154  This has an advantage: Sometimes template developers may find it easier
   155  to express a datastructure with a JSON-like syntax rather than deal with
   156  YAML's whitespace sensitivity.
   157  
   158  As a best practice, templates should follow a YAML-like syntax _unless_
   159  the JSON syntax substantially reduces the risk of a formatting issue.
   160  
   161  ## Be Careful with Generating Random Values
   162  
   163  There are functions in Helm that allow you to generate random data,
   164  cryptographic keys, and so on. These are fine to use. But be aware that
   165  during upgrades, templates are re-executed. When a template run
   166  generates data that differs from the last run, that will trigger an
   167  update of that resource.