Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 43 additions & 49 deletions docs/howto/charts_tips_and_tricks.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,18 +18,56 @@ library](https://masterminds.github.io/sprig/), except `env` and `expandenv`, fo

We also added two special template functions: `include` and `required`. The
`include` function allows you to bring in another template, and then pass the
results to other template functions.
results to other template functions. The `required` function allows you to declare
a particular values entry as required for template rendering. If the value is empty,
the template rendering will fail with a user submitted error message.

For example, this template snippet includes a template called `mytpl`, then
### Using the 'include' Function

Go provides a way of including one template in another using a built-in
`template` directive. However, the built-in function cannot be used in Go
template pipelines.

To make it possible to include a template, and then perform an operation on that
template's output, Helm has a special `include` function:

```
{{ include "toYaml" $value | indent 2 }}
```

The above includes a template called `toYaml`, passes it `$value`, and then
passes the output of that template to the `indent` function.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In general I think folks prefer nindent over indent now, for readability reasons.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But this can be updated in a follow-up PR. I realize you didn't really change this, just moved it higher up in the doc. In a follow-up PR, I would like to see us check all of the docs pages for indent examples and update them to nindent equivalents.


Because YAML ascribes significance to indentation levels and whitespace, this is
one great way to include snippets of code, but handle indentation in a relevant
context.

This template snippet includes a template called `mytpl`, then
lowercases the result, then wraps that in double quotes.

```yaml
value: {{ include "mytpl" . | lower | quote }}
```

The `required` function allows you to declare a particular values entry as
required for template rendering. If the value is empty, the template rendering
will fail with a user submitted error message.
### Using the 'required' function

Go provides a `missingkey` template option to control behavior when a map is indexed
with a key that's not present in the map. There may be situations where a chart
developer wants to enforce this behavior for select values in the `values.yaml` file.

The `required` function gives developers the ability to declare a value entry as
required for template rendering. If the entry is empty in `values.yaml`, the
template will not render and will return an error message supplied by the
developer.

For example:

```
{{ required "A valid foo is required!" .Values.foo }}
```

The above will render the template when `.Values.foo` is defined, but will fail
to render and exit when `.Values.foo` is undefined.

The following example of the `required` function declares an entry for
`.Values.who` is required, and will print an error message when that entry is
Expand Down Expand Up @@ -66,50 +104,6 @@ env:
value: "1234"
```

## Using the 'include' Function

Go provides a way of including one template in another using a built-in
`template` directive. However, the built-in function cannot be used in Go
template pipelines.

To make it possible to include a template, and then perform an operation on that
template's output, Helm has a special `include` function:

```
{{ include "toYaml" $value | indent 2 }}
```

The above includes a template called `toYaml`, passes it `$value`, and then
passes the output of that template to the `indent` function.

Because YAML ascribes significance to indentation levels and whitespace, this is
one great way to include snippets of code, but handle indentation in a relevant
context.

## Using the 'required' function

Go provides a way for setting template options to control behavior when a map is
indexed with a key that's not present in the map. This is typically set with
`template.Options("missingkey=option")`, where `option` can be `default`,
`zero`, or `error`. While setting this option to error will stop execution with
an error, this would apply to every missing key in the map. There may be
situations where a chart developer wants to enforce this behavior for select
values in the `values.yaml` file.

The `required` function gives developers the ability to declare a value entry as
required for template rendering. If the entry is empty in `values.yaml`, the
template will not render and will return an error message supplied by the
developer.

For example:

```
{{ required "A valid foo is required!" .Values.foo }}
```

The above will render the template when `.Values.foo` is defined, but will fail
to render and exit when `.Values.foo` is undefined.

## Using the 'tpl' Function

The `tpl` function allows developers to evaluate strings as templates inside a
Expand Down