helm dependencies called subcharts that also have their own values and templates weight 11 Interacting with a subchart s and global values To this point we have been working only with one chart But charts can have In this section we will create a subchart and see the different ways we can title Subcharts and Global Values access values from within templates

Answer:
---
title: "Subcharts and Global Values"
description: "Interacting with a subchart's and global values."
weight: 11
---

To this point we have been working only with one chart. But charts can have
dependencies, called _subcharts_, that also have their own values and templates.
In this section we will create a subchart and see the different ways we can
access values from within templates.

Before we dive into the code, there are a few important details to learn about application subcharts.

1. A subchart is considered "stand-alone", which means a subchart can never
   explicitly depend on its parent chart.
2. For that reason, a subchart cannot access the values of its parent.
3. A parent chart can override values for subcharts.
4. Helm has a concept of _global values_ that can be accessed by all charts.

> These limitations do not all necessarily apply to [library charts](), which are designed to provide standardized helper functionality.

As we walk through the examples in this section, many of these concepts will
become clearer.

## Creating a Subchart

For these exercises, we'll start with the `mychart/` chart we created at the
beginning of this guide, and we'll add a new chart inside of it.

```console
$ cd mychart/charts
$ helm create mysubchart
Creating mysubchart
$ rm -rf mysubchart/templates/*
```

Notice that just as before, we deleted all of the base templates so that we can
start from scratch. In this guide, we are focused on how templates work, not on
managing dependencies. But the [Charts Guide]()
has more information on how subcharts work.

## Adding Values and a Template to the Subchart

Next, let's create a simple template and values file for our `mysubchart` chart.
There should already be a `values.yaml` in `mychart/charts/mysubchart`. We'll
set it up like this:

```yaml
dessert: cake
```

Next, we'll create a new ConfigMap template in
`mychart/charts/mysubchart/templates/configmap.yaml`:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -cfgmap2
data:
  dessert:
```

Because every subchart is a _stand-alone chart_, we can test `mysubchart` on its
own:

```console
$ helm install --generate-name --dry-run --debug mychart/charts/mysubchart
SERVER: "localhost:44134"
CHART PATH: /Users/mattbutcher/Code/Go/src/helm.sh/helm/_scratch/mychart/charts/mysubchart
NAME:   newbie-elk
TARGET NAMESPACE:   default
CHART:  mysubchart 0.1.0
MANIFEST:
---
# Source: mysubchart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: newbie-elk-cfgmap2
data:
  dessert: cake
```

## Overriding Values from a Parent Chart

Our original chart, `mychart` is now the _parent_ chart of `mysubchart`. This
relationship is based entirely on the fact that `mysubchart` is within
`mychart/charts`.

Because `mychart` is a parent, we can specify configuration in `mychart` and
have that configuration pushed into `mysubchart`. For example, we can modify
`mychart/values.yaml` like this:

```yaml
favorite:
  drink: coffee
  food: pizza
pizzaToppings:
  - mushrooms
  - cheese
  - peppers
  - onions

mysubchart:
  dessert: ice cream
```

Note the last two lines. Any directives inside of the `mysubchart` section will
be sent to the `mysubchart` chart. So if we run `helm install --generate-name --dry-run --debug
mychart`, one of the things we will see is the `mysubchart` ConfigMap:

```yaml
# Source: mychart/charts/mysubchart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: unhinged-bee-cfgmap2
data:
  dessert: ice cream
```

The value at the top level has now overridden the value of the subchart.

There's an important detail to notice here. We didn't change the template of
`mychart/charts/mysubchart/templates/configmap.yaml` to point to
`.Values.mysubchart.dessert`. From that template's perspective, the value is
still located at `.Values.dessert`. As the template engine passes values along,
it sets the scope. So for the `mysubchart` templates, only values specifically
for `mysubchart` will be available in `.Values`.

Sometimes, though, you do want certain values to be available to all of the
templates. This is accomplished using global chart values.

## Global Chart Values

Global values are values that can be accessed from any chart or subchart by
exactly the same name. Globals require explicit declaration. You can't use an
existing non-global as if it were a global.

The Values data type has a reserved section called `Values.global` where global
values can be set. Let's set one in our `mychart/values.yaml` file.

```yaml
favorite:
  drink: coffee
  food: pizza
pizzaToppings:
  - mushrooms
  - cheese
  - peppers
  - onions

mysubchart:
  dessert: ice cream

global:
  salad: caesar
```

Because of the way globals work, both `mychart/templates/configmap.yaml` and
`mysubchart/templates/configmap.yaml` should be able to access that value as
``.

`mychart/templates/configmap.yaml`:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -configmap
data:
  salad:
```

`mysubchart/templates/configmap.yaml`:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -cfgmap2
data:
  dessert:
  salad:
```

Now if we run a dry run install, we'll see the same value in both outputs:

```yaml
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: silly-snake-configmap
data:
  salad: caesar

---
# Source: mychart/charts/mysubchart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: silly-snake-cfgmap2
data:
  dessert: ice cream
  salad: caesar
```

Globals are useful for passing information like this, though it does take some
planning to make sure the right templates are configured to use globals.

## Sharing Templates with Subcharts

Parent charts and subcharts can share templates. Any defined block in any chart
is available to other charts.

For example, we can define a simple template like this:

```yaml
from: mychart
```

Recall how the labels on templates are _globally shared_. Thus, the `labels`
chart can be included from any other chart.

While chart developers have a choice between `include` and `template`, one
advantage of using `include` is that `include` can dynamically reference
templates:

```yaml

```

The above will dereference `$mytemplate`. The `template` function, in contrast,
will only accept a string literal.

## Avoid Using Blocks

The Go template language provides a `block` keyword that allows developers to
provide a default implementation which is overridden later. In Helm charts,
blocks are not the best tool for overriding because if multiple implementations
of the same block are provided, the one selected is unpredictable.

The suggestion is to instead use `include`.

title   Subcharts and Global Values  description   Interacting with a subchart s and global values   weight  11      To this point we have been working only with one chart  But charts can have dependencies  called  subcharts   that also have their own values and templates  In this section we will create a subchart and see the different ways we can access values from within templates   Before we dive into the code  there are a few important details to learn about application subcharts   1  A subchart is considered  stand alone   which means a subchart can never    explicitly depend on its parent chart  2  For that reason  a subchart cannot access the values of its parent  3  A parent chart can override values for subcharts  4  Helm has a concept of  global values  that can be accessed by all charts     These limitations do not all necessarily apply to  library charts     which are designed to provide standardized helper functionality   As we walk through the examples in this section  many of these concepts will become clearer      Creating a Subchart  For these exercises  we ll start with the  mychart   chart we created at the beginning of this guide  and we ll add a new chart inside of it      console   cd mychart charts   helm create mysubchart Creating mysubchart   rm  rf mysubchart templates        Notice that just as before  we deleted all of the base templates so that we can start from scratch  In this guide  we are focused on how templates work  not on managing dependencies  But the  Charts Guide    has more information on how subcharts work      Adding Values and a Template to the Subchart  Next  let s create a simple template and values file for our  mysubchart  chart  There should already be a  values yaml  in  mychart charts mysubchart   We ll set it up like this      yaml dessert  cake      Next  we ll create a new ConfigMap template in  mychart charts mysubchart templates configmap yaml       yaml apiVersion  v1 kind  ConfigMap metadata    name   cfgmap2 data    dessert        Because every subchart is a  stand alone chart   we can test  mysubchart  on its own      console   helm install   generate name   dry run   debug mychart charts mysubchart SERVER   localhost 44134  CHART PATH   Users mattbutcher Code Go src helm sh helm  scratch mychart charts mysubchart NAME    newbie elk TARGET NAMESPACE    default CHART   mysubchart 0 1 0 MANIFEST        Source  mysubchart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  newbie elk cfgmap2 data    dessert  cake         Overriding Values from a Parent Chart  Our original chart   mychart  is now the  parent  chart of  mysubchart   This relationship is based entirely on the fact that  mysubchart  is within  mychart charts    Because  mychart  is a parent  we can specify configuration in  mychart  and have that configuration pushed into  mysubchart   For example  we can modify  mychart values yaml  like this      yaml favorite    drink  coffee   food  pizza pizzaToppings      mushrooms     cheese     peppers     onions  mysubchart    dessert  ice cream      Note the last two lines  Any directives inside of the  mysubchart  section will be sent to the  mysubchart  chart  So if we run  helm install   generate name   dry run   debug mychart   one of the things we will see is the  mysubchart  ConfigMap      yaml   Source  mychart charts mysubchart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  unhinged bee cfgmap2 data    dessert  ice cream      The value at the top level has now overridden the value of the subchart   There s an important detail to notice here  We didn t change the template of  mychart charts mysubchart templates configmap yaml  to point to   Values mysubchart dessert   From that template s perspective  the value is still located at   Values dessert   As the template engine passes values along  it sets the scope  So for the  mysubchart  templates  only values specifically for  mysubchart  will be available in   Values    Sometimes  though  you do want certain values to be available to all of the templates  This is accomplished using global chart values      Global Chart Values  Global values are values that can be accessed from any chart or subchart by exactly the same name  Globals require explicit declaration  You can t use an existing non global as if it were a global   The Values data type has a reserved section called  Values global  where global values can be set  Let s set one in our  mychart values yaml  file      yaml favorite    drink  coffee   food  pizza pizzaToppings      mushrooms     cheese     peppers     onions  mysubchart    dessert  ice cream  global    salad  caesar      Because of the way globals work  both  mychart templates configmap yaml  and  mysubchart templates configmap yaml  should be able to access that value as       mychart templates configmap yaml       yaml apiVersion  v1 kind  ConfigMap metadata    name   configmap data    salad         mysubchart templates configmap yaml       yaml apiVersion  v1 kind  ConfigMap metadata    name   cfgmap2 data    dessert     salad        Now if we run a dry run install  we ll see the same value in both outputs      yaml   Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  silly snake configmap data    salad  caesar        Source  mychart charts mysubchart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  silly snake cfgmap2 data    dessert  ice cream   salad  caesar      Globals are useful for passing information like this  though it does take some planning to make sure the right templates are configured to use globals      Sharing Templates with Subcharts  Parent charts and subcharts can share templates  Any defined block in any chart is available to other charts   For example  we can define a simple template like this      yaml from  mychart      Recall how the labels on templates are  globally shared   Thus  the  labels  chart can be included from any other chart   While chart developers have a choice between  include  and  template   one advantage of using  include  is that  include  can dynamically reference templates      yaml       The above will dereference   mytemplate   The  template  function  in contrast  will only accept a string literal      Avoid Using Blocks  The Go template language provides a  block  keyword that allows developers to provide a default implementation which is overridden later  In Helm charts  blocks are not the best tool for overriding because if multiple implementations of the same block are provided  the one selected is unpredictable   The suggestion is to instead use  include


helm aliases intro gettingstarted In this section of the guide we ll create a chart and then add a first guide weight 2 template The chart we created here will be used throughout the rest of the A quick guide on Chart templates title Getting Started

Answer:
---
title: "Getting Started"
weight: 2
description: "A quick guide on Chart templates."
aliases: ["/intro/getting_started/"]
---

In this section of the guide, we'll create a chart and then add a first
template. The chart we created here will be used throughout the rest of the
guide.

To get going, let's take a brief look at a Helm chart.

## Charts

As described in the [Charts Guide](../../topics/charts), Helm charts are
structured like this:

```
mychart/
  Chart.yaml
  values.yaml
  charts/
  templates/
  ...
```

The `templates/` directory is for template files. When Helm evaluates a chart,
it will send all of the files in the `templates/` directory through the template
rendering engine. It then collects the results of those templates and sends them
on to Kubernetes.

The `values.yaml` file is also important to templates. This file contains the
_default values_ for a chart. These values may be overridden by users during
`helm install` or `helm upgrade`.

The `Chart.yaml` file contains a description of the chart. You can access it
from within a template.

The `charts/` directory _may_ contain other charts
(which we call _subcharts_). Later in this guide we will see how those work when
it comes to template rendering.

## A Starter Chart

For this guide, we'll create a simple chart called `mychart`, and then we'll
create some templates inside of the chart.

```console
$ helm create mychart
Creating mychart
```

### A Quick Glimpse of `mychart/templates/`

If you take a look at the `mychart/templates/` directory, you'll notice a few
files already there.

- `NOTES.txt`: The "help text" for your chart. This will be displayed to your
  users when they run `helm install`.
- `deployment.yaml`: A basic manifest for creating a Kubernetes
  [deployment](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/)
- `service.yaml`: A basic manifest for creating a [service
  endpoint](https://kubernetes.io/docs/concepts/services-networking/service/) for your deployment
- `_helpers.tpl`: A place to put template helpers that you can re-use throughout
  the chart

And what we're going to do is... _remove them all!_ That way we can work through
our tutorial from scratch. We'll actually create our own `NOTES.txt` and
`_helpers.tpl` as we go.

```console
$ rm -rf mychart/templates/*
```

When you're writing production grade charts, having basic versions of these
charts can be really useful. So in your day-to-day chart authoring, you probably
won't want to remove them.

## A First Template

The first template we are going to create will be a `ConfigMap`. In Kubernetes,
a ConfigMap is simply an object for storing configuration data. Other things,
like pods, can access the data in a ConfigMap.

Because ConfigMaps are basic resources, they make a great starting point for us.

Let's begin by creating a file called `mychart/templates/configmap.yaml`:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: mychart-configmap
data:
  myvalue: "Hello World"
```

**TIP:** Template names do not follow a rigid naming pattern. However, we
recommend using the extension `.yaml` for YAML files and `.tpl` for helpers.

The YAML file above is a bare-bones ConfigMap, having the minimal necessary
fields. By virtue of the fact that this file is in the `mychart/templates/`
directory, it will be sent through the template engine.

It is just fine to put a plain YAML file like this in the `mychart/templates/`
directory. When Helm reads this template, it will simply send it to Kubernetes
as-is.

With this simple template, we now have an installable chart. And we can install
it like this:

```console
$ helm install full-coral ./mychart
NAME: full-coral
LAST DEPLOYED: Tue Nov  1 17:36:01 2016
NAMESPACE: default
STATUS: DEPLOYED
REVISION: 1
TEST SUITE: None
```

Using Helm, we can retrieve the release and see the actual template that was
loaded.

```console
$ helm get manifest full-coral

---
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: mychart-configmap
data:
  myvalue: "Hello World"
```

The `helm get manifest` command takes a release name (`full-coral`) and prints
out all of the Kubernetes resources that were uploaded to the server. Each file
begins with `---` to indicate the start of a YAML document, and then is followed
by an automatically generated comment line that tells us what template file
generated this YAML document.

From there on, we can see that the YAML data is exactly what we put in our
`configmap.yaml` file.

Now we can uninstall our release: `helm uninstall full-coral`.

### Adding a Simple Template Call

Hard-coding the `name:` into a resource is usually considered to be bad
practice. Names should be unique to a release. So we might want to generate a
name field by inserting the release name.

**TIP:** The `name:` field is limited to 63 characters because of limitations to
the DNS system. For that reason, release names are limited to 53 characters.
Kubernetes 1.3 and earlier limited to only 24 characters (thus 14 character
names).

Let's alter `configmap.yaml` accordingly.

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -configmap
data:
  myvalue: "Hello World"
```

The big change comes in the value of the `name:` field, which is now
`-configmap`.

> A template directive is enclosed in `` blocks.

The template directive `` injects the release name into the
template. The values that are passed into a template can be thought of as
_namespaced objects_, where a dot (`.`) separates each namespaced element.

The leading dot before `Release` indicates that we start with the top-most
namespace for this scope (we'll talk about scope in a bit). So we could read
`.Release.Name` as "start at the top namespace, find the `Release` object, then
look inside of it for an object called `Name`".

The `Release` object is one of the built-in objects for Helm, and we'll cover it
in more depth later. But for now, it is sufficient to say that this will display
the release name that the library assigns to our release.

Now when we install our resource, we'll immediately see the result of using this
template directive:

```console
$ helm install clunky-serval ./mychart
NAME: clunky-serval
LAST DEPLOYED: Tue Nov  1 17:45:37 2016
NAMESPACE: default
STATUS: DEPLOYED
REVISION: 1
TEST SUITE: None
```

You can run `helm get manifest clunky-serval` to see the entire generated YAML.

Note that the ConfigMap inside Kubernetes name is `clunky-serval-configmap`
instead of `mychart-configmap` previously.

At this point, we've seen templates at their most basic: YAML files that have
template directives embedded in ``. In the next part, we'll take a
deeper look into templates. But before moving on, there's one quick trick that
can make building templates faster: When you want to test the template
rendering, but not actually install anything, you can use `helm install --debug
--dry-run goodly-guppy ./mychart`. This will render the templates. But instead
of installing the chart, it will return the rendered template to you so you can
see the output:

```console
$ helm install --debug --dry-run goodly-guppy ./mychart
install.go:149: [debug] Original chart version: ""
install.go:166: [debug] CHART PATH: /Users/ninja/mychart

NAME: goodly-guppy
LAST DEPLOYED: Thu Dec 26 17:24:13 2019
NAMESPACE: default
STATUS: pending-install
REVISION: 1
TEST SUITE: None
USER-SUPPLIED VALUES:
{}

COMPUTED VALUES:
affinity: {}
fullnameOverride: ""
image:
  pullPolicy: IfNotPresent
  repository: nginx
imagePullSecrets: []
ingress:
  annotations: {}
  enabled: false
  hosts:
  - host: chart-example.local
    paths: []
  tls: []
nameOverride: ""
nodeSelector: {}
podSecurityContext: {}
replicaCount: 1
resources: {}
securityContext: {}
service:
  port: 80
  type: ClusterIP
serviceAccount:
  create: true
  name: null
tolerations: []

HOOKS:
MANIFEST:
---
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: goodly-guppy-configmap
data:
  myvalue: "Hello World"

```

Using `--dry-run` will make it easier to test your code, but it won't ensure
that Kubernetes itself will accept the templates you generate. It's best not to
assume that your chart will install just because `--dry-run` works.

In the [Chart Template Guide](_index.md), we take the basic chart we defined
here and explore the Helm template language in detail. And we'll get started
with built-in objects.

title   Getting Started  weight  2 description   A quick guide on Chart templates   aliases     intro getting started         In this section of the guide  we ll create a chart and then add a first template  The chart we created here will be used throughout the rest of the guide   To get going  let s take a brief look at a Helm chart      Charts  As described in the  Charts Guide        topics charts   Helm charts are structured like this       mychart    Chart yaml   values yaml   charts    templates             The  templates   directory is for template files  When Helm evaluates a chart  it will send all of the files in the  templates   directory through the template rendering engine  It then collects the results of those templates and sends them on to Kubernetes   The  values yaml  file is also important to templates  This file contains the  default values  for a chart  These values may be overridden by users during  helm install  or  helm upgrade    The  Chart yaml  file contains a description of the chart  You can access it from within a template   The  charts   directory  may  contain other charts  which we call  subcharts    Later in this guide we will see how those work when it comes to template rendering      A Starter Chart  For this guide  we ll create a simple chart called  mychart   and then we ll create some templates inside of the chart      console   helm create mychart Creating mychart          A Quick Glimpse of  mychart templates    If you take a look at the  mychart templates   directory  you ll notice a few files already there      NOTES txt   The  help text  for your chart  This will be displayed to your   users when they run  helm install      deployment yaml   A basic manifest for creating a Kubernetes    deployment  https   kubernetes io docs concepts workloads controllers deployment      service yaml   A basic manifest for creating a  service   endpoint  https   kubernetes io docs concepts services networking service   for your deployment     helpers tpl   A place to put template helpers that you can re use throughout   the chart  And what we re going to do is     remove them all   That way we can work through our tutorial from scratch  We ll actually create our own  NOTES txt  and   helpers tpl  as we go      console   rm  rf mychart templates        When you re writing production grade charts  having basic versions of these charts can be really useful  So in your day to day chart authoring  you probably won t want to remove them      A First Template  The first template we are going to create will be a  ConfigMap   In Kubernetes  a ConfigMap is simply an object for storing configuration data  Other things  like pods  can access the data in a ConfigMap   Because ConfigMaps are basic resources  they make a great starting point for us   Let s begin by creating a file called  mychart templates configmap yaml       yaml apiVersion  v1 kind  ConfigMap metadata    name  mychart configmap data    myvalue   Hello World         TIP    Template names do not follow a rigid naming pattern  However  we recommend using the extension   yaml  for YAML files and   tpl  for helpers   The YAML file above is a bare bones ConfigMap  having the minimal necessary fields  By virtue of the fact that this file is in the  mychart templates   directory  it will be sent through the template engine   It is just fine to put a plain YAML file like this in the  mychart templates   directory  When Helm reads this template  it will simply send it to Kubernetes as is   With this simple template  we now have an installable chart  And we can install it like this      console   helm install full coral   mychart NAME  full coral LAST DEPLOYED  Tue Nov  1 17 36 01 2016 NAMESPACE  default STATUS  DEPLOYED REVISION  1 TEST SUITE  None      Using Helm  we can retrieve the release and see the actual template that was loaded      console   helm get manifest full coral        Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  mychart configmap data    myvalue   Hello World       The  helm get manifest  command takes a release name   full coral   and prints out all of the Kubernetes resources that were uploaded to the server  Each file begins with       to indicate the start of a YAML document  and then is followed by an automatically generated comment line that tells us what template file generated this YAML document   From there on  we can see that the YAML data is exactly what we put in our  configmap yaml  file   Now we can uninstall our release   helm uninstall full coral        Adding a Simple Template Call  Hard coding the  name   into a resource is usually considered to be bad practice  Names should be unique to a release  So we might want to generate a name field by inserting the release name     TIP    The  name   field is limited to 63 characters because of limitations to the DNS system  For that reason  release names are limited to 53 characters  Kubernetes 1 3 and earlier limited to only 24 characters  thus 14 character names    Let s alter  configmap yaml  accordingly      yaml apiVersion  v1 kind  ConfigMap metadata    name   configmap data    myvalue   Hello World       The big change comes in the value of the  name   field  which is now   configmap      A template directive is enclosed in    blocks   The template directive    injects the release name into the template  The values that are passed into a template can be thought of as  namespaced objects   where a dot       separates each namespaced element   The leading dot before  Release  indicates that we start with the top most namespace for this scope  we ll talk about scope in a bit   So we could read   Release Name  as  start at the top namespace  find the  Release  object  then look inside of it for an object called  Name     The  Release  object is one of the built in objects for Helm  and we ll cover it in more depth later  But for now  it is sufficient to say that this will display the release name that the library assigns to our release   Now when we install our resource  we ll immediately see the result of using this template directive      console   helm install clunky serval   mychart NAME  clunky serval LAST DEPLOYED  Tue Nov  1 17 45 37 2016 NAMESPACE  default STATUS  DEPLOYED REVISION  1 TEST SUITE  None      You can run  helm get manifest clunky serval  to see the entire generated YAML   Note that the ConfigMap inside Kubernetes name is  clunky serval configmap  instead of  mychart configmap  previously   At this point  we ve seen templates at their most basic  YAML files that have template directives embedded in     In the next part  we ll take a deeper look into templates  But before moving on  there s one quick trick that can make building templates faster  When you want to test the template rendering  but not actually install anything  you can use  helm install   debug   dry run goodly guppy   mychart   This will render the templates  But instead of installing the chart  it will return the rendered template to you so you can see the output      console   helm install   debug   dry run goodly guppy   mychart install go 149   debug  Original chart version     install go 166   debug  CHART PATH   Users ninja mychart  NAME  goodly guppy LAST DEPLOYED  Thu Dec 26 17 24 13 2019 NAMESPACE  default STATUS  pending install REVISION  1 TEST SUITE  None USER SUPPLIED VALUES      COMPUTED VALUES  affinity     fullnameOverride     image    pullPolicy  IfNotPresent   repository  nginx imagePullSecrets     ingress    annotations       enabled  false   hosts      host  chart example local     paths       tls     nameOverride     nodeSelector     podSecurityContext     replicaCount  1 resources     securityContext     service    port  80   type  ClusterIP serviceAccount    create  true   name  null tolerations      HOOKS  MANIFEST        Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  goodly guppy configmap data    myvalue   Hello World        Using    dry run  will make it easier to test your code  but it won t ensure that Kubernetes itself will accept the templates you generate  It s best not to assume that your chart will install just because    dry run  works   In the  Chart Template Guide   index md   we take the basic chart we defined here and explore the Helm template language in detail  And we ll get started with built in objects


helm template authors can use to make our templates less error prone and easier to title Appendix YAML Techniques read Most of this guide has been focused on writing the template language Here we ll look at the YAML format YAML has some useful features that we as A closer look at the YAML specification and how it applies to Helm weight 15

Answer:
---
title: "Appendix: YAML Techniques"
description: "A closer look at the YAML specification and how it applies to Helm."
weight: 15
---

Most of this guide has been focused on writing the template language. Here,
we'll look at the YAML format. YAML has some useful features that we, as
template authors, can use to make our templates less error prone and easier to
read.

## Scalars and Collections

According to the [YAML spec](https://yaml.org/spec/1.2/spec.html), there are two
types of collections, and many scalar types.

The two types of collections are maps and sequences:

```yaml
map:
  one: 1
  two: 2
  three: 3

sequence:
  - one
  - two
  - three
```

Scalar values are individual values (as opposed to collections)

### Scalar Types in YAML

In Helm's dialect of YAML, the scalar data type of a value is determined by a
complex set of rules, including the Kubernetes schema for resource definitions.
But when inferring types, the following rules tend to hold true.

If an integer or float is an unquoted bare word, it is typically treated as a
numeric type:

```yaml
count: 1
size: 2.34
```

But if they are quoted, they are treated as strings:

```yaml
count: "1" # <-- string, not int
size: '2.34' # <-- string, not float
```

The same is true of booleans:

```yaml
isGood: true   # bool
answer: "true" # string
```

The word for an empty value is `null` (not `nil`).

Note that `port: "80"` is valid YAML, and will pass through both the template
engine and the YAML parser, but will fail if Kubernetes expects `port` to be an
integer.

In some cases, you can force a particular type inference using YAML node tags:

```yaml
coffee: "yes, please"
age: !!str 21
port: !!int "80"
```

In the above, `!!str` tells the parser that `age` is a string, even if it looks
like an int. And `port` is treated as an int, even though it is quoted.

## Strings in YAML

Much of the data that we place in YAML documents are strings. YAML has more than
one way to represent a string. This section explains the ways and demonstrates
how to use some of them.

There are three "inline" ways of declaring a string:

```yaml
way1: bare words
way2: "double-quoted strings"
way3: 'single-quoted strings'
```

All inline styles must be on one line.

- Bare words are unquoted, and are not escaped. For this reason, you have to be
  careful what characters you use.
- Double-quoted strings can have specific characters escaped with `\`. For
  example `"\"Hello\", she said"`. You can escape line breaks with `\n`.
- Single-quoted strings are "literal" strings, and do not use the `\` to escape
  characters. The only escape sequence is `''`, which is decoded as a single
  `'`.

In addition to the one-line strings, you can declare multi-line strings:

```yaml
coffee: |
  Latte
  Cappuccino
  Espresso
```

The above will treat the value of `coffee` as a single string equivalent to
`Latte\nCappuccino\nEspresso\n`.

Note that the first line after the `|` must be correctly indented. So we could
break the example above by doing this:

```yaml
coffee: |
         Latte
  Cappuccino
  Espresso

```

Because `Latte` is incorrectly indented, we'd get an error like this:

```
Error parsing file: error converting YAML to JSON: yaml: line 7: did not find expected key
```

In templates, it is sometimes safer to put a fake "first line" of content in a
multi-line document just for protection from the above error:

```yaml
coffee: |
  # Commented first line
         Latte
  Cappuccino
  Espresso

```

Note that whatever that first line is, it will be preserved in the output of the
string. So if you are, for example, using this technique to inject a file's
contents into a ConfigMap, the comment should be of the type expected by
whatever is reading that entry.

### Controlling Spaces in Multi-line Strings

In the example above, we used `|` to indicate a multi-line string. But notice
that the content of our string was followed with a trailing `\n`. If we want the
YAML processor to strip off the trailing newline, we can add a `-` after the
`|`:

```yaml
coffee: |-
  Latte
  Cappuccino
  Espresso
```

Now the `coffee` value will be: `Latte\nCappuccino\nEspresso` (with no trailing
`\n`).

Other times, we might want all trailing whitespace to be preserved. We can do
this with the `|+` notation:

```yaml
coffee: |+
  Latte
  Cappuccino
  Espresso

another: value
```

Now the value of `coffee` will be `Latte\nCappuccino\nEspresso\n\n\n`.

Indentation inside of a text block is preserved, and results in the preservation
of line breaks, too:

```yaml
coffee: |-
  Latte
    12 oz
    16 oz
  Cappuccino
  Espresso
```

In the above case, `coffee` will be `Latte\n  12 oz\n  16
oz\nCappuccino\nEspresso`.

### Indenting and Templates

When writing templates, you may find yourself wanting to inject the contents of
a file into the template. As we saw in previous chapters, there are two ways of
doing this:

- Use `` to get the contents of a file in the chart.
- Use `` to render a template and then place its
  contents into the chart.

When inserting files into YAML, it's good to understand the multi-line rules
above. Often times, the easiest way to insert a static file is to do something
like this:

```yaml
myfile: |

```

Note how we do the indentation above: `indent 2` tells the template engine to
indent every line in "myfile.txt" with two spaces. Note that we do not indent
that template line. That's because if we did, the file content of the first line
would be indented twice.

### Folded Multi-line Strings

Sometimes you want to represent a string in your YAML with multiple lines, but
want it to be treated as one long line when it is interpreted. This is called
"folding". To declare a folded block, use `>` instead of `|`:

```yaml
coffee: >
  Latte
  Cappuccino
  Espresso

```

The value of `coffee` above will be `Latte Cappuccino Espresso\n`. Note that all
but the last line feed will be converted to spaces. You can combine the
whitespace controls with the folded text marker, so `>-` will replace or trim
all newlines.

Note that in the folded syntax, indenting text will cause lines to be preserved.

```yaml
coffee: >-
  Latte
    12 oz
    16 oz
  Cappuccino
  Espresso
```

The above will produce `Latte\n  12 oz\n  16 oz\nCappuccino Espresso`. Note that
both the spacing and the newlines are still there.

## Embedding Multiple Documents in One File

It is possible to place more than one YAML document into a single file. This is
done by prefixing a new document with `---` and ending the document with
`...`

```yaml

---
document: 1
...
---
document: 2
...
```

In many cases, either the `---` or the `...` may be omitted.

Some files in Helm cannot contain more than one doc. If, for example, more than
one document is provided inside of a `values.yaml` file, only the first will be
used.

Template files, however, may have more than one document. When this happens, the
file (and all of its documents) is treated as one object during template
rendering. But then the resulting YAML is split into multiple documents before
it is fed to Kubernetes.

We recommend only using multiple documents per file when it is absolutely
necessary. Having multiple documents in a file can be difficult to debug.

## YAML is a Superset of JSON

Because YAML is a superset of JSON, any valid JSON document _should_ be valid
YAML.

```json
{
  "coffee": "yes, please",
  "coffees": [
    "Latte", "Cappuccino", "Espresso"
  ]
}
```

The above is another way of representing this:

```yaml
coffee: yes, please
coffees:
- Latte
- Cappuccino
- Espresso
```

And the two can be mixed (with care):

```yaml
coffee: "yes, please"
coffees: [ "Latte", "Cappuccino", "Espresso"]
```

All three of these should parse into the same internal representation.

While this means that files such as `values.yaml` may contain JSON data, Helm
does not treat the file extension `.json` as a valid suffix.

## YAML Anchors

The YAML spec provides a way to store a reference to a value, and later refer to
that value by reference. YAML refers to this as "anchoring":

```yaml
coffee: "yes, please"
favorite: &favoriteCoffee "Cappuccino"
coffees:
  - Latte
  - *favoriteCoffee
  - Espresso
```

In the above, `&favoriteCoffee` sets a reference to `Cappuccino`. Later, that
reference is used as `*favoriteCoffee`. So `coffees` becomes `Latte, Cappuccino,
Espresso`.

While there are a few cases where anchors are useful, there is one aspect of
them that can cause subtle bugs: The first time the YAML is consumed, the
reference is expanded and then discarded.

So if we were to decode and then re-encode the example above, the resulting YAML
would be:

```yaml
coffee: yes, please
favorite: Cappuccino
coffees:
- Latte
- Cappuccino
- Espresso
```

Because Helm and Kubernetes often read, modify, and then rewrite YAML files, the
anchors will be lost.

title   Appendix  YAML Techniques  description   A closer look at the YAML specification and how it applies to Helm   weight  15      Most of this guide has been focused on writing the template language  Here  we ll look at the YAML format  YAML has some useful features that we  as template authors  can use to make our templates less error prone and easier to read      Scalars and Collections  According to the  YAML spec  https   yaml org spec 1 2 spec html   there are two types of collections  and many scalar types   The two types of collections are maps and sequences      yaml map    one  1   two  2   three  3  sequence      one     two     three      Scalar values are individual values  as opposed to collections       Scalar Types in YAML  In Helm s dialect of YAML  the scalar data type of a value is determined by a complex set of rules  including the Kubernetes schema for resource definitions  But when inferring types  the following rules tend to hold true   If an integer or float is an unquoted bare word  it is typically treated as a numeric type      yaml count  1 size  2 34      But if they are quoted  they are treated as strings      yaml count   1        string  not int size   2 34        string  not float      The same is true of booleans      yaml isGood  true     bool answer   true    string      The word for an empty value is  null   not  nil     Note that  port   80   is valid YAML  and will pass through both the template engine and the YAML parser  but will fail if Kubernetes expects  port  to be an integer   In some cases  you can force a particular type inference using YAML node tags      yaml coffee   yes  please  age    str 21 port    int  80       In the above     str  tells the parser that  age  is a string  even if it looks like an int  And  port  is treated as an int  even though it is quoted       Strings in YAML  Much of the data that we place in YAML documents are strings  YAML has more than one way to represent a string  This section explains the ways and demonstrates how to use some of them   There are three  inline  ways of declaring a string      yaml way1  bare words way2   double quoted strings  way3   single quoted strings       All inline styles must be on one line     Bare words are unquoted  and are not escaped  For this reason  you have to be   careful what characters you use    Double quoted strings can have specific characters escaped with      For   example     Hello    she said    You can escape line breaks with   n     Single quoted strings are  literal  strings  and do not use the     to escape   characters  The only escape sequence is       which is decoded as a single         In addition to the one line strings  you can declare multi line strings      yaml coffee      Latte   Cappuccino   Espresso      The above will treat the value of  coffee  as a single string equivalent to  Latte nCappuccino nEspresso n    Note that the first line after the     must be correctly indented  So we could break the example above by doing this      yaml coffee             Latte   Cappuccino   Espresso       Because  Latte  is incorrectly indented  we d get an error like this       Error parsing file  error converting YAML to JSON  yaml  line 7  did not find expected key      In templates  it is sometimes safer to put a fake  first line  of content in a multi line document just for protection from the above error      yaml coffee        Commented first line          Latte   Cappuccino   Espresso       Note that whatever that first line is  it will be preserved in the output of the string  So if you are  for example  using this technique to inject a file s contents into a ConfigMap  the comment should be of the type expected by whatever is reading that entry       Controlling Spaces in Multi line Strings  In the example above  we used     to indicate a multi line string  But notice that the content of our string was followed with a trailing   n   If we want the YAML processor to strip off the trailing newline  we can add a     after the          yaml coffee       Latte   Cappuccino   Espresso      Now the  coffee  value will be   Latte nCappuccino nEspresso   with no trailing   n     Other times  we might want all trailing whitespace to be preserved  We can do this with the      notation      yaml coffee       Latte   Cappuccino   Espresso   another  value      Now the value of  coffee  will be  Latte nCappuccino nEspresso n n n    Indentation inside of a text block is preserved  and results in the preservation of line breaks  too      yaml coffee       Latte     12 oz     16 oz   Cappuccino   Espresso      In the above case   coffee  will be  Latte n  12 oz n  16 oz nCappuccino nEspresso        Indenting and Templates  When writing templates  you may find yourself wanting to inject the contents of a file into the template  As we saw in previous chapters  there are two ways of doing this     Use    to get the contents of a file in the chart    Use    to render a template and then place its   contents into the chart   When inserting files into YAML  it s good to understand the multi line rules above  Often times  the easiest way to insert a static file is to do something like this      yaml myfile          Note how we do the indentation above   indent 2  tells the template engine to indent every line in  myfile txt  with two spaces  Note that we do not indent that template line  That s because if we did  the file content of the first line would be indented twice       Folded Multi line Strings  Sometimes you want to represent a string in your YAML with multiple lines  but want it to be treated as one long line when it is interpreted  This is called  folding   To declare a folded block  use     instead of          yaml coffee      Latte   Cappuccino   Espresso        The value of  coffee  above will be  Latte Cappuccino Espresso n   Note that all but the last line feed will be converted to spaces  You can combine the whitespace controls with the folded text marker  so      will replace or trim all newlines   Note that in the folded syntax  indenting text will cause lines to be preserved      yaml coffee       Latte     12 oz     16 oz   Cappuccino   Espresso      The above will produce  Latte n  12 oz n  16 oz nCappuccino Espresso   Note that both the spacing and the newlines are still there      Embedding Multiple Documents in One File  It is possible to place more than one YAML document into a single file  This is done by prefixing a new document with       and ending the document with           yaml      document  1         document  2          In many cases  either the       or the       may be omitted   Some files in Helm cannot contain more than one doc  If  for example  more than one document is provided inside of a  values yaml  file  only the first will be used   Template files  however  may have more than one document  When this happens  the file  and all of its documents  is treated as one object during template rendering  But then the resulting YAML is split into multiple documents before it is fed to Kubernetes   We recommend only using multiple documents per file when it is absolutely necessary  Having multiple documents in a file can be difficult to debug      YAML is a Superset of JSON  Because YAML is a superset of JSON  any valid JSON document  should  be valid YAML      json      coffee    yes  please      coffees          Latte    Cappuccino    Espresso             The above is another way of representing this      yaml coffee  yes  please coffees    Latte   Cappuccino   Espresso      And the two can be mixed  with care       yaml coffee   yes  please  coffees     Latte    Cappuccino    Espresso        All three of these should parse into the same internal representation   While this means that files such as  values yaml  may contain JSON data  Helm does not treat the file extension   json  as a valid suffix      YAML Anchors  The YAML spec provides a way to store a reference to a value  and later refer to that value by reference  YAML refers to this as  anchoring       yaml coffee   yes  please  favorite   favoriteCoffee  Cappuccino  coffees      Latte      favoriteCoffee     Espresso      In the above    favoriteCoffee  sets a reference to  Cappuccino   Later  that reference is used as   favoriteCoffee   So  coffees  becomes  Latte  Cappuccino  Espresso    While there are a few cases where anchors are useful  there is one aspect of them that can cause subtle bugs  The first time the YAML is consumed  the reference is expanded and then discarded   So if we were to decode and then re encode the example above  the resulting YAML would be      yaml coffee  yes  please favorite  Cappuccino coffees    Latte   Cappuccino   Espresso      Because Helm and Kubernetes often read  modify  and then rewrite YAML files  the anchors will be lost


helm It is time to move beyond one template and begin to create others In this them elsewhere A named template sometimes called a partial or a How to define named templates subtemplate is simply a template defined inside of a file and given a name section we will see how to define named templates in one file and then use weight 9 title Named Templates

Answer:
---
title: "Named Templates"
description: "How to define named templates."
weight: 9
---

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.

In the [Flow Control](./control_structures.md) 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.

An 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_.

One popular naming convention is to prefix each defined template with the name
of the chart: ``. By using the specific chart name
as a prefix we can avoid any conflicts that may arise due to two different
charts that implement templates of the same name.

This behavior also applies to different versions of a chart. If you have
`mychart` version `1.0.0` that defines a template one way, and a `mychart`
version `2.0.0` that modifies the existing named template, it will use the one
that was loaded last. You can work around this issue by also adding a version
in the name of the chart: `` and
``.

## Partials and `_` files

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.

Before we get to the nuts-and-bolts of writing those templates, there is file
naming convention that deserves mention:

* Most files in `templates/` are treated as if they contain Kubernetes manifests
* The `NOTES.txt` is one exception
* 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.

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.

## Declaring and using templates with `define` and `template`

The `define` action allows us to create a named template inside of a template
file. Its syntax goes like this:

```yaml

  # body of template here

```

For example, we can define a template to encapsulate a Kubernetes block of
labels:

```yaml

  labels:
    generator: helm
    date:

```

Now we can embed this template inside of our existing ConfigMap, and then
include it with the `template` action:

```yaml

  labels:
    generator: helm
    date:

apiVersion: v1
kind: ConfigMap
metadata:
  name: -configmap

data:
  myvalue: "Hello World"

  :

```

When the template engine reads this file, it will store away the reference to
`mychart.labels` until `template "mychart.labels"` is called. Then it will
render that template inline. So the result will look like this:

```yaml
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: running-panda-configmap
  labels:
    generator: helm
    date: 2016-11-02
data:
  myvalue: "Hello World"
  drink: "coffee"
  food: "pizza"
```

Note: a `define` does not produce output unless it is called with a template,
as in this example.

Conventionally, Helm charts put these templates inside of a partials file,
usually `_helpers.tpl`. Let's move this function there:

```yaml

  labels:
    generator: helm
    date:

```

By convention, `define` functions should have a simple documentation block
(``) describing what they do.

Even though this definition is in `_helpers.tpl`, it can still be accessed in
`configmap.yaml`:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -configmap

data:
  myvalue: "Hello World"

  :

```

As mentioned above, **template names are global**. As a result of this, if two
templates are declared with the same name the last occurrence will be the one
that is used. Since templates in subcharts are compiled together with top-level
templates, it is best to name your templates with _chart specific names_. A
popular naming convention is to prefix each defined template with the name of
the chart: ``.

## Setting the scope of a template

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:

```yaml

  labels:
    generator: helm
    date:
    chart:
    version:

```

If we render this, we will get an error like this:

```console
$ helm install --dry-run moldy-jaguar ./mychart
Error: unable to build kubernetes objects from release manifest: error validating "": error validating data: [unknown object type "nil" in ConfigMap.metadata.labels.chart, unknown object type "nil" in ConfigMap.metadata.labels.version]
```

To see what rendered, re-run with `--disable-openapi-validation`:
`helm install --dry-run --disable-openapi-validation moldy-jaguar ./mychart`.
The result will not be what we expect:

```yaml
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: moldy-jaguar-configmap
  labels:
    generator: helm
    date: 2021-03-06
    chart:
    version:
```

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:

```yaml

```

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:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -configmap

```

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.

Now when we execute this template with `helm install --dry-run --debug
plinking-anaco ./mychart`, we get this:

```yaml
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: plinking-anaco-configmap
  labels:
    generator: helm
    date: 2021-03-06
    chart: mychart
    version: 0.1.0
```

Now `` resolves to `mychart`, and ``
resolves to `0.1.0`.

## The `include` function

Say we've defined a simple template that looks like this:

```yaml

app_name:
app_version: ""

```

Now say I want to insert this both into the `labels:` section of my template,
and also the `data:` section:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -configmap
  labels:

data:
  myvalue: "Hello World"

  :

```

If we render this, we will get an error like this:

```console
$ helm install --dry-run measly-whippet ./mychart
Error: unable to build kubernetes objects from release manifest: error validating "": error validating data: [ValidationError(ConfigMap): unknown field "app_name" in io.k8s.api.core.v1.ConfigMap, ValidationError(ConfigMap): unknown field "app_version" in io.k8s.api.core.v1.ConfigMap]
```

To see what rendered, re-run with `--disable-openapi-validation`:
`helm install --dry-run --disable-openapi-validation measly-whippet ./mychart`.
The output will not be what we expect:

```yaml
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: measly-whippet-configmap
  labels:
    app_name: mychart
app_version: "0.1.0"
data:
  myvalue: "Hello World"
  drink: "coffee"
  food: "pizza"
app_name: mychart
app_version: "0.1.0"
```

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 left. 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.

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.

Here's the example above, corrected to use `indent` to indent the `mychart.app`
template correctly:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -configmap
  labels:

data:
  myvalue: "Hello World"

  :

```

Now the produced YAML is correctly indented for each section:

```yaml
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: edgy-mole-configmap
  labels:
    app_name: mychart
    app_version: "0.1.0"
data:
  myvalue: "Hello World"
  drink: "coffee"
  food: "pizza"
  app_name: mychart
  app_version: "0.1.0"
```

> 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.

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.

title   Named Templates  description   How to define named templates   weight  9      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   In the  Flow Control    control structures md  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   An 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    One popular naming convention is to prefix each defined template with the name of the chart      By using the specific chart name as a prefix we can avoid any conflicts that may arise due to two different charts that implement templates of the same name   This behavior also applies to different versions of a chart  If you have  mychart  version  1 0 0  that defines a template one way  and a  mychart  version  2 0 0  that modifies the existing named template  it will use the one that was loaded last  You can work around this issue by also adding a version in the name of the chart     and         Partials and     files  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   Before we get to the nuts and bolts of writing those templates  there is file naming convention that deserves mention     Most files in  templates   are treated as if they contain Kubernetes manifests   The  NOTES txt  is one exception   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   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      Declaring and using templates with  define  and  template   The  define  action allows us to create a named template inside of a template file  Its syntax goes like this      yaml      body of template here       For example  we can define a template to encapsulate a Kubernetes block of labels      yaml    labels      generator  helm     date         Now we can embed this template inside of our existing ConfigMap  and then include it with the  template  action      yaml    labels      generator  helm     date    apiVersion  v1 kind  ConfigMap metadata    name   configmap    data    myvalue   Hello World                  When the template engine reads this file  it will store away the reference to  mychart labels  until  template  mychart labels   is called  Then it will render that template inline  So the result will look like this      yaml   Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  running panda configmap   labels      generator  helm     date  2016 11 02 data    myvalue   Hello World    drink   coffee    food   pizza       Note  a  define  does not produce output unless it is called with a template  as in this example   Conventionally  Helm charts put these templates inside of a partials file  usually   helpers tpl   Let s move this function there      yaml     labels      generator  helm     date         By convention   define  functions should have a simple documentation block      describing what they do   Even though this definition is in   helpers tpl   it can still be accessed in  configmap yaml       yaml apiVersion  v1 kind  ConfigMap metadata    name   configmap    data    myvalue   Hello World                  As mentioned above    template names are global    As a result of this  if two templates are declared with the same name the last occurrence will be the one that is used  Since templates in subcharts are compiled together with top level templates  it is best to name your templates with  chart specific names   A popular naming convention is to prefix each defined template with the name of the chart          Setting the scope of a template  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      yaml     labels      generator  helm     date       chart       version         If we render this  we will get an error like this      console   helm install   dry run moldy jaguar   mychart Error  unable to build kubernetes objects from release manifest  error validating     error validating data   unknown object type  nil  in ConfigMap metadata labels chart  unknown object type  nil  in ConfigMap metadata labels version       To see what rendered  re run with    disable openapi validation    helm install   dry run   disable openapi validation moldy jaguar   mychart   The result will not be what we expect      yaml   Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  moldy jaguar configmap   labels      generator  helm     date  2021 03 06     chart      version       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      yaml       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      yaml apiVersion  v1 kind  ConfigMap metadata    name   configmap         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   Now when we execute this template with  helm install   dry run   debug plinking anaco   mychart   we get this      yaml   Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  plinking anaco configmap   labels      generator  helm     date  2021 03 06     chart  mychart     version  0 1 0      Now    resolves to  mychart   and    resolves to  0 1 0       The  include  function  Say we ve defined a simple template that looks like this      yaml  app name   app version           Now say I want to insert this both into the  labels   section of my template  and also the  data   section      yaml apiVersion  v1 kind  ConfigMap metadata    name   configmap   labels       data    myvalue   Hello World                   If we render this  we will get an error like this      console   helm install   dry run measly whippet   mychart Error  unable to build kubernetes objects from release manifest  error validating     error validating data   ValidationError ConfigMap   unknown field  app name  in io k8s api core v1 ConfigMap  ValidationError ConfigMap   unknown field  app version  in io k8s api core v1 ConfigMap       To see what rendered  re run with    disable openapi validation    helm install   dry run   disable openapi validation measly whippet   mychart   The output will not be what we expect      yaml   Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  measly whippet configmap   labels      app name  mychart app version   0 1 0  data    myvalue   Hello World    drink   coffee    food   pizza  app name  mychart app version   0 1 0       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 left  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   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   Here s the example above  corrected to use  indent  to indent the  mychart app  template correctly      yaml apiVersion  v1 kind  ConfigMap metadata    name   configmap   labels   data    myvalue   Hello World                   Now the produced YAML is correctly indented for each section      yaml   Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  edgy mole configmap   labels      app name  mychart     app version   0 1 0  data    myvalue   Hello World    drink   coffee    food   pizza    app name  mychart   app version   0 1 0         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   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


helm In the previous section we looked at the built in objects that Helm templates Instructions on how to use the values flag title Values Files weight 4 offer One of the built in objects is This object provides access to values passed into the chart Its contents come from multiple sources

Answer:
---
title: "Values Files"
description: "Instructions on how to use the --values flag."
weight: 4
---

In the previous section we looked at the built-in objects that Helm templates
offer. One of the built-in objects is `Values`. This object provides access to
values passed into the chart. Its contents come from multiple sources:

- The `values.yaml` file in the chart
- If this is a subchart, the `values.yaml` file of a parent chart
- A values file is passed into `helm install` or `helm upgrade` with the `-f`
  flag (`helm install -f myvals.yaml ./mychart`)
- Individual parameters are passed with `--set` (such as `helm install --set foo=bar
  ./mychart`)

The list above is in order of specificity: `values.yaml` is the default, which
can be overridden by a parent chart's `values.yaml`, which can in turn be
overridden by a user-supplied values file, which can in turn be overridden by
`--set` parameters.

Values files are plain YAML files. Let's edit `mychart/values.yaml` and then
edit our ConfigMap template.

Removing the defaults in `values.yaml`, we'll set just one parameter:

```yaml
favoriteDrink: coffee
```

Now we can use this inside of a template:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -configmap
data:
  myvalue: "Hello World"
  drink:
```

Notice on the last line we access `favoriteDrink` as an attribute of `Values`:
``.

Let's see how this renders.

```console
$ helm install geared-marsupi ./mychart --dry-run --debug
install.go:158: [debug] Original chart version: ""
install.go:175: [debug] CHART PATH: /home/bagratte/src/playground/mychart

NAME: geared-marsupi
LAST DEPLOYED: Wed Feb 19 23:21:13 2020
NAMESPACE: default
STATUS: pending-install
REVISION: 1
TEST SUITE: None
USER-SUPPLIED VALUES:
{}

COMPUTED VALUES:
favoriteDrink: coffee

HOOKS:
MANIFEST:
---
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: geared-marsupi-configmap
data:
  myvalue: "Hello World"
  drink: coffee
```

Because `favoriteDrink` is set in the default `values.yaml` file to `coffee`,
that's the value displayed in the template. We can easily override that by
adding a `--set` flag in our call to `helm install`:

```console
$ helm install solid-vulture ./mychart --dry-run --debug --set favoriteDrink=slurm
install.go:158: [debug] Original chart version: ""
install.go:175: [debug] CHART PATH: /home/bagratte/src/playground/mychart

NAME: solid-vulture
LAST DEPLOYED: Wed Feb 19 23:25:54 2020
NAMESPACE: default
STATUS: pending-install
REVISION: 1
TEST SUITE: None
USER-SUPPLIED VALUES:
favoriteDrink: slurm

COMPUTED VALUES:
favoriteDrink: slurm

HOOKS:
MANIFEST:
---
# Source: mychart/templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: solid-vulture-configmap
data:
  myvalue: "Hello World"
  drink: slurm
```

Since `--set` has a higher precedence than the default `values.yaml` file, our
template generates `drink: slurm`.

Values files can contain more structured content, too. For example, we could
create a `favorite` section in our `values.yaml` file, and then add several keys
there:

```yaml
favorite:
  drink: coffee
  food: pizza
```

Now we would have to modify the template slightly:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: -configmap
data:
  myvalue: "Hello World"
  drink:
  food:
```

While structuring data this way is possible, the recommendation is that you keep
your values trees shallow, favoring flatness. When we look at assigning values
to subcharts, we'll see how values are named using a tree structure.

## Deleting a default key

If you need to delete a key from the default values, you may override the value
of the key to be `null`, in which case Helm will remove the key from the
overridden values merge.

For example, the stable Drupal chart allows configuring the liveness probe, in
case you configure a custom image. Here are the default values:
```yaml
livenessProbe:
  httpGet:
    path: /user/login
    port: http
  initialDelaySeconds: 120
```

If you try to override the livenessProbe handler to `exec` instead of `httpGet`
using `--set livenessProbe.exec.command=[cat,docroot/CHANGELOG.txt]`, Helm will
coalesce the default and overridden keys together, resulting in the following
YAML:
```yaml
livenessProbe:
  httpGet:
    path: /user/login
    port: http
  exec:
    command:
    - cat
    - docroot/CHANGELOG.txt
  initialDelaySeconds: 120
```

However, Kubernetes would then fail because you can not declare more than one
livenessProbe handler. To overcome this, you may instruct Helm to delete the
`livenessProbe.httpGet` by setting it to null:
```sh
helm install stable/drupal --set image=my-registry/drupal:0.1.0 --set livenessProbe.exec.command=[cat,docroot/CHANGELOG.txt] --set livenessProbe.httpGet=null
```

At this point, we've seen several built-in objects, and used them to inject
information into a template. Now we will take a look at another aspect of the
template engine: functions and pipelines.

title   Values Files  description   Instructions on how to use the   values flag   weight  4      In the previous section we looked at the built in objects that Helm templates offer  One of the built in objects is  Values   This object provides access to values passed into the chart  Its contents come from multiple sources     The  values yaml  file in the chart   If this is a subchart  the  values yaml  file of a parent chart   A values file is passed into  helm install  or  helm upgrade  with the   f    flag   helm install  f myvals yaml   mychart     Individual parameters are passed with    set   such as  helm install   set foo bar     mychart    The list above is in order of specificity   values yaml  is the default  which can be overridden by a parent chart s  values yaml   which can in turn be overridden by a user supplied values file  which can in turn be overridden by    set  parameters   Values files are plain YAML files  Let s edit  mychart values yaml  and then edit our ConfigMap template   Removing the defaults in  values yaml   we ll set just one parameter      yaml favoriteDrink  coffee      Now we can use this inside of a template      yaml apiVersion  v1 kind  ConfigMap metadata    name   configmap data    myvalue   Hello World    drink        Notice on the last line we access  favoriteDrink  as an attribute of  Values        Let s see how this renders      console   helm install geared marsupi   mychart   dry run   debug install go 158   debug  Original chart version     install go 175   debug  CHART PATH   home bagratte src playground mychart  NAME  geared marsupi LAST DEPLOYED  Wed Feb 19 23 21 13 2020 NAMESPACE  default STATUS  pending install REVISION  1 TEST SUITE  None USER SUPPLIED VALUES      COMPUTED VALUES  favoriteDrink  coffee  HOOKS  MANIFEST        Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  geared marsupi configmap data    myvalue   Hello World    drink  coffee      Because  favoriteDrink  is set in the default  values yaml  file to  coffee   that s the value displayed in the template  We can easily override that by adding a    set  flag in our call to  helm install       console   helm install solid vulture   mychart   dry run   debug   set favoriteDrink slurm install go 158   debug  Original chart version     install go 175   debug  CHART PATH   home bagratte src playground mychart  NAME  solid vulture LAST DEPLOYED  Wed Feb 19 23 25 54 2020 NAMESPACE  default STATUS  pending install REVISION  1 TEST SUITE  None USER SUPPLIED VALUES  favoriteDrink  slurm  COMPUTED VALUES  favoriteDrink  slurm  HOOKS  MANIFEST        Source  mychart templates configmap yaml apiVersion  v1 kind  ConfigMap metadata    name  solid vulture configmap data    myvalue   Hello World    drink  slurm      Since    set  has a higher precedence than the default  values yaml  file  our template generates  drink  slurm    Values files can contain more structured content  too  For example  we could create a  favorite  section in our  values yaml  file  and then add several keys there      yaml favorite    drink  coffee   food  pizza      Now we would have to modify the template slightly      yaml apiVersion  v1 kind  ConfigMap metadata    name   configmap data    myvalue   Hello World    drink     food        While structuring data this way is possible  the recommendation is that you keep your values trees shallow  favoring flatness  When we look at assigning values to subcharts  we ll see how values are named using a tree structure      Deleting a default key  If you need to delete a key from the default values  you may override the value of the key to be  null   in which case Helm will remove the key from the overridden values merge   For example  the stable Drupal chart allows configuring the liveness probe  in case you configure a custom image  Here are the default values     yaml livenessProbe    httpGet      path   user login     port  http   initialDelaySeconds  120      If you try to override the livenessProbe handler to  exec  instead of  httpGet  using    set livenessProbe exec command  cat docroot CHANGELOG txt    Helm will coalesce the default and overridden keys together  resulting in the following YAML     yaml livenessProbe    httpGet      path   user login     port  http   exec      command        cat       docroot CHANGELOG txt   initialDelaySeconds  120      However  Kubernetes would then fail because you can not declare more than one livenessProbe handler  To overcome this  you may instruct Helm to delete the  livenessProbe httpGet  by setting it to null     sh helm install stable drupal   set image my registry drupal 0 1 0   set livenessProbe exec command  cat docroot CHANGELOG txt    set livenessProbe httpGet null      At this point  we ve seen several built in objects  and used them to inject information into a template  Now we will take a look at another aspect of the template engine  functions and pipelines