Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 38 ยท Template Functions and Pipelines

Required, Default and Validation: required, fail and values.schema.json

Make charts fail early and clearly: use required, fail and default, safe nested access with dig, and validate values with a JSON Schema in values.schema.json.

Because Helm templates silently print nothing for a missing key, a typo in a values file can deploy a broken application without any warning. Good charts do the opposite: they refuse to render when something essential is missing or wrong, and say why in plain words. This lesson covers the tools for that: required, fail, defaults, safe access to nested keys, and a JSON Schema that checks every value before any template runs.

default: be forgiving where it is safe

default supplies a fallback when a value is empty. It makes sense for optional settings that have an obvious value:

YAML
replicas: {{ .Values.replicaCount | default 1 }}
pullPolicy: {{ .Values.image.pullPolicy | default "IfNotPresent" }}

Prefer putting defaults in values.yaml, where users can see them. Use default in templates for derived fallbacks (the tag falling back to appVersion) rather than as the only source of a default, because helm show values cannot reveal a default hidden in a template.

required: be strict where it matters

required "message" value returns the value, or aborts the render with the message if the value is empty:

YAML
env:
  - name: DATABASE_HOST
    value: {{ required "database.host is required: set it with --set database.host=..." .Values.database.host | quote }}

Running without the value gives a clear error instead of a broken Deployment:

TEXT
Error: execution error at (webapp/templates/deployment.yaml:21:24): database.host is required: set it with --set database.host=...

Write messages that name the exact key and how to set it. In values.yaml, leave required keys empty (host: "") with a comment so they appear in helm show values. Remember that required treats false, 0 and empty collections as missing as well.

fail: your own checks

fail "message" aborts unconditionally; combine it with if for rules that involve several values:

YAML
{{- if and .Values.ingress.enabled (not .Values.ingress.hosts) }}
{{- fail "ingress.enabled is true but ingress.hosts is empty" }}
{{- end }}
{{- if and .Values.autoscaling.enabled (lt (int .Values.autoscaling.maxReplicas) (int .Values.autoscaling.minReplicas)) }}
{{- fail "autoscaling.maxReplicas must be >= autoscaling.minReplicas" }}
{{- end }}

Many charts collect these checks in one named template such as webapp.validate and call it from a single place (for example at the top of the Deployment) so all rules are easy to find. A single check can also use eq/has against allowed values: {{ if not (has .Values.service.type (list "ClusterIP" "NodePort" "LoadBalancer")) }}.

Safe access to nested keys

If a parent key is missing, reading a child of it fails with a nil-pointer error:

TEXT
nil pointer evaluating interface {}.tag

This happens with .Values.image.tag when image is not defined. Three remedies:

  1. Provide the parent in values.yaml so it always exists (the usual fix).
  2. Parenthesize: (.Values.image).tag evaluates to empty when image is nil instead of failing. Use it only where absence is legitimate.
  3. dig: dig "image" "tag" "latest" .Values.AsMap walks a path and returns a default (it needs a map, hence .AsMap).

The stand-in shows the difference between a strict lookup, a safe lookup and required.

Python Stand-in: safe lookup, default and required

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

values.schema.json: validate everything up front

Put a JSON Schema file named values.schema.json next to values.yaml. Helm validates the final merged values against it during install, upgrade, lint and template, before rendering anything. Type mistakes, unknown keys, bad enum values and missing required keys are caught with a precise path:

JSON
{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image", "service"],
  "additionalProperties": false,
  "properties": {
    "replicaCount": { "type": "integer", "minimum": 0 },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": {
        "repository": { "type": "string", "minLength": 1 },
        "tag": { "type": "string" },
        "pullPolicy": { "type": "string", "enum": ["Always", "IfNotPresent", "Never"] }
      }
    },
    "service": {
      "type": "object",
      "properties": {
        "type": { "type": "string", "enum": ["ClusterIP", "NodePort", "LoadBalancer"] },
        "port": { "type": "integer", "minimum": 1, "maximum": 65535 }
      }
    }
  }
}

A mistake produces an error like:

TEXT
Error: values don't meet the specifications of the schema(s) in the following chart(s):
webapp:
- replicaCount: Invalid type. Expected: integer, given: string
- image.pullPolicy: image.pullPolicy must be one of the following: "Always", "IfNotPresent", "Never"

Schema tips:

  • "additionalProperties": false rejects misspelled keys, which is the cheapest typo detector. Use it at levels where users should not add arbitrary keys, and allow free-form maps (env, podAnnotations, nodeSelector) with "type": "object" only.
  • Subcharts may have their own schema; the parent's schema should allow the subchart key ("redis": {"type": "object"}).
  • Remember that --set a=1 produces an integer while --set-string produces text; the schema decides which is acceptable.
  • You can generate a first draft with the helm-schema tools and then tighten it by hand.
Python Stand-in: a mini JSON Schema validator

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The last key replicas (a typo of replicaCount) is caught only because additional properties are forbidden. Without that rule a typo would pass and be ignored.

Layers of defense

flowchart TB
  A["values.schema.json: types, enums, unknown keys"] --> B["required / fail in templates: cross-field rules"]
  B --> C["helm lint and helm template in CI"]
  C --> D["helm install --dry-run=server: API schema"]
  D --> E["Tests after install (helm test)"]

Catch mistakes as early and as cheaply as possible.

Keep the schema in sync with values.yaml by running helm lint in CI with several values files, including one that deliberately violates the schema (a negative test), so you notice if the schema stops catching it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does required "msg" .Values.x do when x is empty?

    required stops rendering with your message when the value is empty.
  2. 2. How do you prevent a nil-pointer error when image might be missing?

    Parentheses make a nil parent yield empty; defining the parent in values.yaml avoids the problem entirely.
  3. 3. Where does Helm look for value validation rules written in JSON Schema?

    values.schema.json is validated on install, upgrade, lint and template.
  4. 4. Which schema setting rejects misspelled keys?

    With additionalProperties false any key not listed in properties is an error.

Summary

  • Use default for harmless fallbacks, required for essential values and fail for cross-field rules; write messages naming the key.
  • Avoid nil-pointer errors by defining parents in values.yaml, using (.Values.x).y or dig.
  • values.schema.json validates types, ranges, enums and unknown keys before rendering; forbid additional properties where typos matter.
  • Combine schema, template checks, lint in CI and server-side dry runs for layered protection.

Next: tpl, lookup and Other Advanced Functions