Values / Configuration / Helm / Advanced

The Values is an arbitrary YAML file filled with parameters that you can use in templates. All values passed to the chart can be divided by following categories:

User-defined regular values.
User-defined secret values.
Service values.

User-defined regular values

You can (optionally) place user-defined regular values into the .helm/values.yaml chart file. For example:

global:
  names:
    - alpha
    - beta
    - gamma
  mysql:
    staging:
      user: mysql-staging
    production:
      user: mysql-production
    _default:
      user: mysql-dev
      password: mysql-dev

Values placed under the global key will be available both in the current chart and in all subcharts.

Values placed under the arbitrary SOMEKEY key will be available in the current chart and in the SOMEKEY subchart.

The .helm/values.yaml file is the default place to store values. You can also pass additional user-defined regular values via:

Separate value files by specifying --values=PATH_TO_FILE (you can use it repeatedly to pass multiple files) as a werf option.
Options --set key1.key2.key3.array[0]=one, --set key1.key2.key3.array[1]=two (can be used multiple times, see also --set-string key=forced_string_value, and --set-file key1.data.notes=notes.txt).

NOTE All values files, including default .helm/values.yaml or any custom values file passed with --values option — all of these should be stored in the git repo of the project. More info in the giterminism article.

User-defined secret values

Secret values are perfect to store passwords and other sensitive data directly in the project repository.

You can (optionally) place user-defined secret values into the default .helm/secret-values.yaml chart file or any number of files with an arbitrary name (--secret-values). For example:

global:
  mysql:
    production:
      password: 100024fe29e45bf00665d3399f7545f4af63f09cc39790c239e16b1d597842161123
    staging:
      password: 100024fe29e45bf00665d3399f7545f4af63f09cc39790c239e16b1d597842161123

Each value (like 100024fe29e45bf00665d3399f7545f4af63f09cc39790c239e16b1d597842161123) in the secret value map is encoded by werf. The structure of the secret value map is the same as that of a regular value map (for example, in values.yaml). See more info about secret value generation and working with secrets.

The .helm/secret-values.yaml file is the default place for storing secret values. You can also pass additional user-defined secret values via separate secret value files by specifying --secret-values=PATH_TO_FILE (can be used repeatedly to pass multiple files). All such files should be stored in the git repo of the project due to giterminism.

Set parameters

There is an ability to redefine or pass new values using cli params:

--set KEY=VALUE;
--set-string KEY=VALUE;
--set-file=PATH;
--set-docker-config-json-value=true|false.

NOTE All files, specified with --set-file option should be stored in the git repo of the project. More info in the giterminism article.

set-docker-config-json-value

When --set-docker-config-json-value has been specified werf will set special value .Values.dockerconfigjson using current docker config from the environment where werf running (DOCKER_CONFIG is supported).

This value .Values.dockerconfigjson contains base64 encoded docker config, which is ready to use for example to create a secret to access a container registry:

{{- if .Values.dockerconfigjson -}}
apiVersion: v1
kind: Secret
metadata:
  name: regsecret
type: kubernetes.io/dockerconfigjson
data:
  .dockerconfigjson: {{ .Values.dockerconfigjson }}
{{- end -}}

IMPORTANT Current docker config may contain temporal login credentials created using temporal short-lived token (CI_JOB_TOKEN in GitLab for example) and in such case should not be used as imagePullSecrets, because registry will stop being available from inside Kubernetes as soon as the token is terminated.

Service values

Service values are set by the werf to pass additional data when rendering chart templates.

Here is an example of service data:

werf:
  name: myapp
  namespace: myapp-production
  env: production
  repo: registry.domain.com/apps/myapp
  image:
    assets: registry.domain.com/apps/myapp:a243949601ddc3d4133c4d5269ba23ed58cb8b18bf2b64047f35abd2-1598024377816
    rails: registry.domain.com/apps/myapp:e760e9311f938e3d92681e93da3a81e176aa7f7e684ee06d092ec199-1598269478292
  tag:
    assets: a243949601ddc3d4133c4d5269ba23ed58cb8b18bf2b64047f35abd2-1598024377816
    rails: e760e9311f938e3d92681e93da3a81e176aa7f7e684ee06d092ec199-1598269478292
  commit:
    date:
      human: 2022-01-21 18:51:39 +0300 +0300
      unix: 1642780299
    hash: 1b28e6843a963c5bdb3579f6fc93317cc028051c

global:
  werf:
    name: myapp
    version: v1.2.7

There are following service values:

The name of the werf project: .Values.werf.name.
Version of the werf cli util: .Values.werf.version.
Resources will be deployed in .Values.werf.namespace namespace.
Name of a CI/CD environment used during the current deploy process: .Values.werf.env.
Container registry repo used during the current deploy process: .Values.werf.repo.
Full images names used during the current deploy process: .Values.werf.image.NAME. More info about using this available in the templates article.
Only tags of built images. Usually used in combination with .Values.werf.repo to pass image repos and image tags separately.
Info about commit from which werf was executed: .Values.werf.commit.hash, .Values.werf.commit.date.human, .Values.werf.commit.date.unix.

Service values in the subcharts

If you are using subcharts and you want to use regular werf service values (those that defined outside of global scope) in subchart, you need to explicitly export these parent-scoped service values from the parent to the subchart:

# .helm/Chart.yaml
apiVersion: v2
dependencies:
  - name: rails
    version: 1.0.0
    export-values:
    - parent: werf
      child: werf

Now the service values initially available only at .Values.werf of the parent chart will be also available on the same path .Values.werf in the subchart named “rails”. Refer to these service values in the subchart like this:

# .helm/charts/rails/app.yaml
...
spec:
  template:
    spec:
      containers:
      - name: rails
        image: {{ .Values.werf.image.rails }}  # Will result in: `image: registry.domain.com/apps/myapp/rails:e760e931...`

Path to where you want to export service values can be changed:

    export-values:
    - parent: werf
      child: definitely.not.werf  # Service values will become available on `.Values.definitely.not.werf` in the subchart.

Or pass service values one by one to the subchart:

# .helm/Chart.yaml
apiVersion: v2
dependencies:
  - name: postgresql
    version: "10.9.4"
    repository: "https://charts.bitnami.com/bitnami"
    export-values:
    - parent: werf.repo
      child: image.repository
    - parent: werf.tag.my-postgresql
      child: image.tag

More info about export-values can be found here.

Merging the resulting values

During the deployment process, werf merges all user-defined regular, secret, and service values into the single value map, which is then passed to the template rendering engine to be used in the templates (see how to use values in the templates). Values are merged in the following order of priority (the more recent value overwrites the previous one):

User-defined regular values from the .helm/values.yaml.
User-defined regular values from all cli options --values=PATH_TO_FILE in the order specified.
User-defined secret values from .helm/secret-values.yaml.
User-defined secret values from all cli options --secret-values=PATH_TO_FILE in the order specified.
User-defined values passed with the --set* params.
Service values.

Using values in the templates

werf uses the following syntax for accessing values contained in the chart templates:

{{ .Values.key.key.arraykey[INDEX].key }}

The .Values object contains the merged map of resulting values map.