Working with Values Files
1. Creating values.yaml Default Values
Example: Layered defaults
replicaCount: 1
image:
repository: nginx
tag: ""
pullPolicy: IfNotPresent
serviceAccount:
create: true
name: ""
podAnnotations: {}
podSecurityContext: {}
securityContext: {}
nodeSelector: {}
tolerations: []
affinity: {}
| Convention | Why |
|---|
Empty {} / [] placeholders | Documents structure for users without forcing values |
| Lowercase camelCase | Helm community standard |
| Comment every field | Self-documenting chart |
2. Understanding Values Hierarchy
| Source (low → high precedence) | Notes |
|---|
Subchart values.yaml | Loaded first |
Parent values.yaml | Overrides subchart defaults via key matching subchart name |
-f file.yaml (left-to-right) | Each subsequent file overrides previous |
--set / --set-string / --set-file / --set-json | Highest precedence |
3. Using Custom Values Files
Example: Stack multiple files
helm install api ./chart \
-f values.yaml \
-f values-prod.yaml \
-f values-prod-eu.yaml
4. Setting Individual Values
| Pattern | Result |
|---|
--set key=value | Scalar assignment |
--set a.b.c=v | Nested map |
--set a[0].b=v | Indexed list assignment |
--set 'tags={a,b,c}' | List literal |
--set 'nodeSelector.kubernetes\.io/role=worker' | Escape dots in keys |
5. Using String Values
Example: Force string interpretation
# numbers/booleans become strings
helm install x ./chart --set-string image.tag=1.2.0 --set-string flag=true
| Flag | Why |
|---|
--set-string | Prevents YAML type coercion (e.g. tag 1.10 → 1.1) |
6. Setting File Content Values
Example: Load TLS cert from disk
helm install api ./chart \
--set-file tls.cert=./certs/tls.crt \
--set-file tls.key=./certs/tls.key
7. Setting JSON Values
| Flag | Use case |
|---|
--set-json 3.10+ | Inject complex structures (lists of maps, nested objects) |
Example: Complex list of objects
helm install api ./chart \
--set-json 'env=[{"name":"LOG_LEVEL","value":"debug"},{"name":"REGION","value":"us-east"}]'
8. Merging Multiple Values Files
| Type | Merge behavior |
|---|
| Map / object | Deep merge — keys combine recursively |
| List / array | Full replacement — last value wins entirely |
| Scalar | Last value wins |
Warning: Lists do NOT merge. To append, use Helm template logic or split into map of named items.
9. Creating Environment-Specific Values
Example: Layout
environments/
├── base.yaml
├── dev.yaml
├── staging.yaml
└── prod.yaml
# Usage
helm upgrade --install api ./chart -f environments/base.yaml -f environments/prod.yaml
10. Documenting Values
| Tool | Purpose |
|---|
helm-docs | Generate README.md from YAML comments |
values.schema.json | Machine-readable schema + descriptions |
| Annotation comments | # -- description (text) picked up by helm-docs |
11. Using Global Values
Example: Shared across parent + subcharts
# parent values.yaml
global:
imageRegistry: ghcr.io
domain: acme.io
postgresql:
enabled: true # subchart-specific value
| Rule | Behavior |
|---|
global key | Propagates to every subchart automatically |
| Access in template | {{ .Values.global.imageRegistry }} |