github.com/felipejfc/helm@v2.1.2+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  ```
    78  kind: Deployment
    79  spec:
    80    template:
    81      metadata:
    82        annotations:
    83          checksum/config: {{ include "mychart/templates/configmap.yaml" . | sha256sum }}
    84  [...]    
    85  ```
    86  
    87  ## Using "Partials" and Template Includes
    88  
    89  Sometimes you want to create some reusable parts in your chart, whether
    90  they're blocks or template partials. And often, it's cleaner to keep
    91  these in their own files.
    92  
    93  In the `templates/` directory, any file that begins with an
    94  underscore(`_`) is not expected to output a Kubernetes manifest file. So
    95  by convention, helper templates and partials are placed in a
    96  `_helpers.tpl` file.
    97  
    98  ## Complex Charts with Many Dependencies
    99  
   100  Many of the charts in the [official charts repository](https://github.com/kubernetes/charts)
   101  are "building blocks" for creating more advanced applications. But charts may be
   102  used to create instances of large-scale applications. In such cases, a single
   103  umbrella chart may have multiple subcharts, each of which functions as a piece
   104  of the whole.
   105  
   106  The current best practice for composing a complex application from discrete parts
   107  is to create a top-level umbrella chart that
   108  exposes the global configurations, and then use the `charts/` subdirectory to
   109  embed each of the components.
   110  
   111  Two strong design patterns are illustrated by these projects:
   112  
   113  **SAP's [OpenStack chart](https://github.com/sapcc/openstack-helm):** This chart
   114  installs a full OpenStack IaaS on Kubernetes. All of the charts are collected
   115  together in one GitHub repository.
   116  
   117  **Deis's [Workflow](https://github.com/deis/workflow/tree/master/charts/workflow):**
   118  This chart exposes the entire Deis PaaS system with one chart. But it's different
   119  from the SAP chart in that this master chart is built from each component, and
   120  each component is tracked in a different Git repository. Check out the
   121  `requirements.yaml` file to see how this chart is composed by their CI/CD
   122  pipeline.
   123  
   124  Both of these charts illustrate proven techniques for standing up complex environments
   125  using Helm.
   126  
   127  ## YAML is a Superset of JSON
   128  
   129  According to the YAML specification, YAML is a superset of JSON. That
   130  means that any valid JSON structure ought to be valid in YAML.
   131  
   132  This has an advantage: Sometimes template developers may find it easier
   133  to express a datastructure with a JSON-like syntax rather than deal with
   134  YAML's whitespace sensitivity.
   135  
   136  As a best practice, templates should follow a YAML-like syntax _unless_
   137  the JSON syntax substantially reduces the risk of a formatting issue.
   138  
   139  ## Be Careful with Generating Random Values
   140  
   141  There are functions in Helm that allow you to generate random data,
   142  cryptographic keys, and so on. These are fine to use. But be aware that
   143  during upgrades, templates are re-executed. When a template run
   144  generates data that differs from the last run, that will trigger an
   145  update of that resource.