Templates and Values

Helm Chart templates are written in theGo template language, with theaddition of 50 or so add-on templatefunctions from the Sprig library and afew other specialized functions.

All template files are stored in a chart’s templates/ folder. WhenHelm renders the charts, it will pass every file in that directorythrough the template engine.

Values for the templates are supplied two ways:

  • Chart developers may supply a file called values.yaml inside of achart. This file can contain default values.
  • Chart users may supply a YAML file that contains values. This can beprovided on the command line with helm install.When a user supplies custom values, these values will override thevalues in the chart’s values.yaml file.

Template Files

Template files follow the standard conventions for writing Go templates(see the text/template Go package documentationfor details).An example template file might look something like this:

  1. apiVersion: v1
  2. kind: ReplicationController
  3. metadata:
  4.   name: deis-database
  5.   namespace: deis
  6.   labels:
  7.     app.kubernetes.io/managed-by: deis
  8. spec:
  9.   replicas: 1
  10.   selector:
  11.     app.kubernetes.io/name: deis-database
  12.   template:
  13.     metadata:
  14.       labels:
  15.         app.kubernetes.io/name: deis-database
  16.     spec:
  17.       serviceAccount: deis-database
  18.       containers:
  19.         - name: deis-database
  20.           image: {{.Values.imageRegistry}}/postgres:{{.Values.dockerTag}}
  21.           imagePullPolicy: {{.Values.pullPolicy}}
  22.           ports:
  23.             - containerPort: 5432
  24.           env:
  25.             - name: DATABASE_STORAGE
  26.               value: {{default "minio" .Values.storage}}

The above example, based loosely on https://github.com/deis/charts, is a template for a Kubernetes replication controller.It can use the following four template values (usually defined in avalues.yaml file):

  • imageRegistry: The source registry for the Docker image.
  • dockerTag: The tag for the docker image.
  • pullPolicy: The Kubernetes pull policy.
  • storage: The storage backend, whose default is set to "minio"All of these values are defined by the template author. Helm does notrequire or dictate parameters.

To see many working charts, check out the Helm Chartsproject

Predefined Values

Values that are supplied via a values.yaml file (or via the —setflag) are accessible from the .Values object in a template. But thereare other pre-defined pieces of data you can access in your templates.

The following values are pre-defined, are available to every template, andcannot be overridden. As with all values, the names are casesensitive.

  • Release.Name: The name of the release (not the chart)
  • Release.Time: The time the chart release was last updated. This willmatch the Last Released time on a Release object.
  • Release.Namespace: The namespace the chart was released to.
  • Release.Service: The service that conducted the release. Usuallythis is Tiller.
  • Release.IsUpgrade: This is set to true if the current operation is an upgrade or rollback.
  • Release.IsInstall: This is set to true if the current operation is aninstall.
  • Release.Revision: The revision number. It begins at 1, and increments witheach helm upgrade.
  • Chart: The contents of the Chart.yaml. Thus, the chart version isobtainable as Chart.Version and the maintainers are inChart.Maintainers.
  • Files: A map-like object containing all non-special files in the chart. Thiswill not give you access to templates, but will give you access to additionalfiles that are present (unless they are excluded using .helmignore). Files can beaccessed using {{index .Files "file.name"}} or using the {{.Files.Get name}} or{{.Files.GetString name}} functions. You can also access the contents of the fileas []byte using {{.Files.GetBytes}}
  • Capabilities: A map-like object that contains information about the versionsof Kubernetes ({{.Capabilities.KubeVersion}}, Tiller({{.Capabilities.TillerVersion}}, and the supported Kubernetes API versions({{.Capabilities.APIVersions.Has "batch/v1")NOTE: Any unknown Chart.yaml fields will be dropped. They will notbe accessible inside of the Chart object. Thus, Chart.yaml cannot beused to pass arbitrarily structured data into the template. The valuesfile can be used for that, though.

Values files

Considering the template in the previous section, a values.yaml filethat supplies the necessary values would look like this:

  1. imageRegistry: "quay.io/deis"
  2. dockerTag: "latest"
  3. pullPolicy: "Always"
  4. storage: "s3"

A values file is formatted in YAML. A chart may include a defaultvalues.yaml file. The Helm install command allows a user to overridevalues by supplying additional YAML values:

  1. $ helm install --values=myvals.yaml wordpress

When values are passed in this way, they will be merged into the defaultvalues file. For example, consider a myvals.yaml file that looks likethis:

  1. storage: "gcs"

When this is merged with the values.yaml in the chart, the resultinggenerated content will be:

  1. imageRegistry: "quay.io/deis"
  2. dockerTag: "latest"
  3. pullPolicy: "Always"
  4. storage: "gcs"

Note that only the last field was overridden.

NOTE: The default values file included inside of a chart must be namedvalues.yaml. But files specified on the command line can be namedanything.

NOTE: If the —set flag is used on helm install or helm upgrade, thosevalues are simply converted to YAML on the client side.

NOTE: If any required entries in the values file exist, they can be declaredas required in the chart template by using the ‘required’ function

Any of these values are then accessible inside of templates using the.Values object:

  1. apiVersion: v1
  2. kind: ReplicationController
  3. metadata:
  4.   name: deis-database
  5.   namespace: deis
  6.   labels:
  7.     app.kubernetes.io/managed-by: deis
  8. spec:
  9.   replicas: 1
  10.   selector:
  11.     app.kubernetes.io/name: deis-database
  12.   template:
  13.     metadata:
  14.       labels:
  15.         app.kubernetes.io/name: deis-database
  16.     spec:
  17.       serviceAccount: deis-database
  18.       containers:
  19.         - name: deis-database
  20.           image: {{.Values.imageRegistry}}/postgres:{{.Values.dockerTag}}
  21.           imagePullPolicy: {{.Values.pullPolicy}}
  22.           ports:
  23.             - containerPort: 5432
  24.           env:
  25.             - name: DATABASE_STORAGE
  26.               value: {{default "minio" .Values.storage}}

Scope, Dependencies, and Values

Values files can declare values for the top-level chart, as well as forany of the charts that are included in that chart’s charts/ directory.Or, to phrase it differently, a values file can supply values to thechart as well as to any of its dependencies. For example, thedemonstration WordPress chart above has both mysql and apache asdependencies. The values file could supply values to all of thesecomponents:

  1. title: "My WordPress Site" # Sent to the WordPress template
  3. mysql:
  4.   max_connections: 100 # Sent to MySQL
  5.   password: "secret"
  7. apache:
  8.   port: 8080 # Passed to Apache

Charts at a higher level have access to all of the variables definedbeneath. So the WordPress chart can access the MySQL password as.Values.mysql.password. But lower level charts cannot access things inparent charts, so MySQL will not be able to access the title property. Nor,for that matter, can it access apache.port.

Values are namespaced, but namespaces are pruned. So for the WordPresschart, it can access the MySQL password field as .Values.mysql.password. Butfor the MySQL chart, the scope of the values has been reduced and thenamespace prefix removed, so it will see the password field simply as.Values.password.

Global Values

As of 2.0.0-Alpha.2, Helm supports special “global” value. Considerthis modified version of the previous example:

  1. title: "My WordPress Site" # Sent to the WordPress template
  3. global:
  4.   app: MyWordPress
  6. mysql:
  7.   max_connections: 100 # Sent to MySQL
  8.   password: "secret"
  10. apache:
  11.   port: 8080 # Passed to Apache

The above adds a global section with the value app: MyWordPress.This value is available to all charts as .Values.global.app.

For example, the mysql templates may access app as {{.Values.global.app}}, andso can the apache chart. Effectively, the values file above isregenerated like this:

  1. title: "My WordPress Site" # Sent to the WordPress template
  3. global:
  4.   app: MyWordPress
  6. mysql:
  7.   global:
  8.     app: MyWordPress
  9.   max_connections: 100 # Sent to MySQL
  10.   password: "secret"
  12. apache:
  13.   global:
  14.     app: MyWordPress
  15.   port: 8080 # Passed to Apache

This provides a way of sharing one top-level variable with allsubcharts, which is useful for things like setting metadata propertieslike labels.

If a subchart declares a global variable, that global will be passeddownward (to the subchart’s subcharts), but not upward to the parentchart. There is no way for a subchart to influence the values of theparent chart.

Also, global variables of parent charts take precedence over the global variables from subcharts.

References

When it comes to writing templates and values files, there are severalstandard references that will help you out.