github.com/y-taka-23/helm@v2.8.0+incompatible/docs/chart_template_guide/named_templates.md (about)

     1  # Named Templates
     2  
     3  It is time to move beyond one template, and begin to create others. In this section, we will see how to define _named templates_ in one file, and then use them elsewhere. A _named template_ (sometimes called a _partial_ or a _subtemplate_) is simply a template defined inside of a file, and given a name. We'll see two ways to create them, and a few different ways to use them.
     4  
     5  In the "Flow Control" section we introduced three actions for declaring and managing templates: `define`, `template`, and `block`. In this section, we'll cover those three actions, and also introduce a special-purpose `include` function that works similarly to the `template` action.
     6  
     7  ## Partials and `_` files
     8  
     9  So far, we've used one file, and that one file has contained a single template. But Helm's template language allows you to create named embedded templates, that can be accessed by name elsewhere.
    10  
    11  Before we get to the nuts-and-bolts of writing those templates, there is file naming convention that deserves mention:
    12  
    13  - Most files in `templates/` are treated as if they contain Kubernetes manifests
    14  - The `NOTES.txt` is one exception
    15  - But files whose name begins with an underscore (`_`) are assumed to _not_ have a manifest inside. These files are not rendered to Kubernetes object definitions, but are available everywhere within other chart templates for use.
    16  
    17  These files are used to store partials and helpers. In fact, when we first created `mychart`, we saw a file called `_helpers.tpl`. That file is the default location for template partials.
    18  
    19  ## Declaring and using templates with `define` and `template`
    20  
    21  The `define` action allows us to create a named template inside of a template file. Its syntax goes like this:
    22  
    23  ```yaml
    24  {{ define "MY_NAME" }}
    25    # body of template here
    26  {{ end }}
    27  ```
    28  
    29  For example, we can define a template to encapsulate a Kubernetes block of labels:
    30  
    31  ```yaml
    32  {{- define "my_labels" }}
    33    labels:
    34      generator: helm
    35      date: {{ now | htmlDate }}
    36  {{- end }}
    37  ```
    38  
    39  Now we can embed this template inside of our existing ConfigMap, and then include it with the `template` action:
    40  
    41  ```yaml
    42  {{- define "my_labels" }}
    43    labels:
    44      generator: helm
    45      date: {{ now | htmlDate }}
    46  {{- end }}
    47  apiVersion: v1
    48  kind: ConfigMap
    49  metadata:
    50    name: {{ .Release.Name }}-configmap
    51    {{- template "my_labels" }}
    52  data:
    53    myvalue: "Hello World"
    54    {{- range $key, $val := .Values.favorite }}
    55    {{ $key }}: {{ $val | quote }}
    56    {{- end }}
    57  ```
    58  
    59  When the template engine reads this file, it will store away the reference to `my_labels` until `template "my_labels"` is called. Then it will render that template inline. So the result will look like this:
    60  
    61  ```yaml
    62  # Source: mychart/templates/configmap.yaml
    63  apiVersion: v1
    64  kind: ConfigMap
    65  metadata:
    66    name: running-panda-configmap
    67    labels:
    68      generator: helm
    69      date: 2016-11-02
    70  data:
    71    myvalue: "Hello World"
    72    drink: "coffee"
    73    food: "pizza"
    74  ```
    75  
    76  Conventionally, Helm charts put these templates inside of a partials file, usually `_helpers.tpl`. Let's move this function there:
    77  
    78  ```yaml
    79  {{/* Generate basic labels */}}
    80  {{- define "my_labels" }}
    81    labels:
    82      generator: helm
    83      date: {{ now | htmlDate }}
    84  {{- end }}
    85  ```
    86  
    87  By convention, `define` functions should have a simple documentation block (`{{/* ... */}}`) describing what they do.
    88  
    89  Even though this definition is in `_helpers.tpl`, it can still be accessed in `configmap.yaml`:
    90  
    91  ```yaml
    92  apiVersion: v1
    93  kind: ConfigMap
    94  metadata:
    95    name: {{ .Release.Name }}-configmap
    96    {{- template "my_labels" }}
    97  data:
    98    myvalue: "Hello World"
    99    {{- range $key, $val := .Values.favorite }}
   100    {{ $key }}: {{ $val | quote }}
   101    {{- end }}
   102  ```
   103  
   104  There is one _really important detail_ to keep in mind when naming templates: **template names are global**. If you declare two templates with the same name, whichever one is loaded last will be the one used. Because templates in subcharts are compiled together with top-level templates, you should be careful to name your templates with chart-specific names.
   105  
   106  One popular naming convention is to prefix each defined template with the name of the chart: `{{ define "mychart.labels" }}` or `{{ define "mychart_labels" }}`.
   107  
   108  ## Setting the scope of a template
   109  
   110  In the template we defined above, we did not use any objects. We just used functions. Let's modify our defined template to include the chart name and chart version:
   111  
   112  ```yaml
   113  {{/* Generate basic labels */}}
   114  {{- define "my_labels" }}
   115    labels:
   116      generator: helm
   117      date: {{ now | htmlDate }}
   118      chart: {{ .Chart.Name }}
   119      version: {{ .Chart.Version }}
   120  {{- end }}
   121  ```
   122  
   123  If we render this, the result will not be what we expect:
   124  
   125  ```yaml
   126  # Source: mychart/templates/configmap.yaml
   127  apiVersion: v1
   128  kind: ConfigMap
   129  metadata:
   130    name: moldy-jaguar-configmap
   131    labels:
   132      generator: helm
   133      date: 2016-11-02
   134      chart:
   135      version:
   136  ```
   137  
   138  What happened to the name and version? They weren't in the scope for our defined template. When a named template (created with `define`) is rendered, it will receive the scope passed in by the `template` call. In our example, we included the template like this:
   139  
   140  ```yaml
   141  {{- template "my_labels" }}
   142  ```
   143  
   144  No scope was passed in, so within the template we cannot access anything in `.`. This is easy enough to fix, though. We simply pass a scope to the template:
   145  
   146  ```yaml
   147  apiVersion: v1
   148  kind: ConfigMap
   149  metadata:
   150    name: {{ .Release.Name }}-configmap
   151    {{- template "my_labels" . }}
   152  ```
   153  
   154  Note that we pass `.` at the end of the `template` call. We could just as easily pass `.Values` or `.Values.favorite` or whatever scope we want. But what we want is the top-level scope.
   155  
   156  Now when we execute this template with `helm install --dry-run --debug ./mychart`, we get this:
   157  
   158  ```yaml
   159  # Source: mychart/templates/configmap.yaml
   160  apiVersion: v1
   161  kind: ConfigMap
   162  metadata:
   163    name: plinking-anaco-configmap
   164    labels:
   165      generator: helm
   166      date: 2016-11-02
   167      chart: mychart
   168      version: 0.1.0
   169  ```
   170  
   171  Now `{{ .Chart.Name }}` resolves to `mychart`, and `{{ .Chart.Version }}` resolves to `0.1.0`.
   172  
   173  ## The `include` function
   174  
   175  Say we've defined a simple template that looks like this:
   176  
   177  ```
   178  {{- define "mychart_app" -}}
   179  app_name: {{ .Chart.Name }}
   180  app_version: "{{ .Chart.Version }}+{{ .Release.Time.Seconds }}"
   181  {{- end -}}
   182  ```
   183  
   184  Now say I want to insert this both into the `labels:` section of my template, and also the `data:` section:
   185  
   186  ```yaml
   187  apiVersion: v1
   188  kind: ConfigMap
   189  metadata:
   190    name: {{ .Release.Name }}-configmap
   191    labels:
   192      {{ template "mychart_app" .}}
   193  data:
   194    myvalue: "Hello World"
   195    {{- range $key, $val := .Values.favorite }}
   196    {{ $key }}: {{ $val | quote }}
   197    {{- end }}
   198    {{ template "mychart_app" . }}
   199  
   200  ```
   201  
   202  The output will not be what we expect:
   203  
   204  ```yaml
   205  # Source: mychart/templates/configmap.yaml
   206  apiVersion: v1
   207  kind: ConfigMap
   208  metadata:
   209    name: measly-whippet-configmap
   210    labels:
   211      app_name: mychart
   212  app_version: "0.1.0+1478129847"
   213  data:
   214    myvalue: "Hello World"
   215    drink: "coffee"
   216    food: "pizza"
   217    app_name: mychart
   218  app_version: "0.1.0+1478129847"
   219  ```
   220  
   221  Note that the indentation on `app_version` is wrong in both places. Why? Because the template that is substituted in has the text aligned to the right. Because `template` is an action, and not a function, there is no way to pass the output of a `template` call to other functions; the data is simply inserted inline.
   222  
   223  To work around this case, Helm provides an alternative to `template` that will import the contents of a template into the present pipeline where it can be passed along to other functions in the pipeline.
   224  
   225  Here's the example above, corrected to use `indent` to indent the `mychart_app` template correctly:
   226  
   227  ```yaml
   228  apiVersion: v1
   229  kind: ConfigMap
   230  metadata:
   231    name: {{ .Release.Name }}-configmap
   232    labels:
   233  {{ include "mychart_app" . | indent 4 }}
   234  data:
   235    myvalue: "Hello World"
   236    {{- range $key, $val := .Values.favorite }}
   237    {{ $key }}: {{ $val | quote }}
   238    {{- end }}
   239  {{ include "mychart_app" . | indent 2 }}
   240  ```
   241  
   242  Now the produced YAML is correctly indented for each section:
   243  
   244  ```yaml
   245  # Source: mychart/templates/configmap.yaml
   246  apiVersion: v1
   247  kind: ConfigMap
   248  metadata:
   249    name: edgy-mole-configmap
   250    labels:
   251      app_name: mychart
   252      app_version: "0.1.0+1478129987"
   253  data:
   254    myvalue: "Hello World"
   255    drink: "coffee"
   256    food: "pizza"
   257    app_name: mychart
   258    app_version: "0.1.0+1478129987"
   259  ```
   260  
   261  > It is considered preferable to use `include` over `template` in Helm templates simply so that the output formatting can be handled better for YAML documents.
   262  
   263  Sometimes we want to import content, but not as templates. That is, we want to import files verbatim. We can achieve this by accessing files through the `.Files` object described in the next section.