120 lines
4.2 KiB
Markdown
120 lines
4.2 KiB
Markdown
# Helm Chart Reference & Advanced Patterns
|
||
|
||
This document contains detailed explanations and advanced patterns for Helm chart development.
|
||
|
||
## 🏠 Resource Ownership
|
||
|
||
**Every Kubernetes resource must have exactly one owner. Never duplicate.**
|
||
|
||
- If a chart creates a resource (e.g. Traefik creates IngressClass), don't create it elsewhere
|
||
- Before adding a template for a resource, verify no other chart/subchart already manages it
|
||
|
||
```
|
||
❌ Wrong: subchart A creates IngressClass AND subchart B creates IngressClass
|
||
✅ Right: one chart owns IngressClass, others do not touch it
|
||
```
|
||
|
||
## 🧹 values.yaml — Keep It Short and Identical Across Installations
|
||
|
||
**values.yaml serves two purposes:**
|
||
|
||
1. **Static baseline** — identical for every installation.
|
||
2. **Umbrella glue** — wires subcharts into a coherent whole. Shared values like `global.domain` are defined once here.
|
||
|
||
Installation-specific values go exclusively in `values.<instance>.yaml` in the IaC/deployment repo. If a value varies between installations, it does not belong in the chart's `values.yaml`.
|
||
|
||
**Forbidden in values.yaml:**
|
||
- Empty string placeholders (`key: ""`)
|
||
- Defaults for values that are hardcoded in templates
|
||
- Installation-specific data of any kind (hostnames, credentials)
|
||
|
||
| File | Location | Content |
|
||
|---|---|---|
|
||
| `values.yaml` | chart repo | minimal static baseline |
|
||
| `values.<instance>.yaml` | IaC repo | everything that varies per installation |
|
||
|
||
## ✅ required vs defaults
|
||
|
||
When a template needs a value:
|
||
|
||
**1. Sensible default** — hardcode it directly in the template. Do not add it to values.yaml.
|
||
**2. Must come from deployer** — use `required`. Do not put any entry in values.yaml.
|
||
|
||
`| default` in templates is forbidden.
|
||
|
||
```yaml
|
||
# ✅ Sensible default
|
||
replicas: 1
|
||
|
||
# ✅ Must vary per installation
|
||
host: {{ required "global.domain is required" .Values.global.domain }}
|
||
|
||
# ❌ Forbidden — default in values.yaml adds noise
|
||
replicas: {{ .Values.replicas }} # values.yaml: replicas: 1
|
||
|
||
# ❌ Forbidden — hides missing config
|
||
host: {{ .Values.global.domain | default "" }}
|
||
```
|
||
|
||
## 📄 Configuration Files over values.yaml
|
||
|
||
**Prefer `files/` + ConfigMap over defining configuration in values.yaml.**
|
||
|
||
1. Put the config file in `files/`
|
||
2. Create a ConfigMap that reads it with `.AsConfig` + `tpl`
|
||
3. Use `{{ .Values.global.xxx }}` expressions inside the config file
|
||
|
||
```yaml
|
||
# templates/configmap.yaml
|
||
data: {{ (tpl (.Files.Glob "files/*").AsConfig . ) | nindent 2 }}
|
||
```
|
||
|
||
**Always use `.AsConfig` when the file contains template expressions or special characters.**
|
||
|
||
## 🎂 Umbrella Chart Pattern
|
||
|
||
The standard structure is an umbrella chart that integrates multiple component charts.
|
||
|
||
```
|
||
my-umbrella/
|
||
├── Chart.yaml ← declares component charts as dependencies
|
||
├── values.yaml ← static baseline: shared across all installations
|
||
├── templates/ ← only cross-cutting resources that no subchart owns
|
||
└── charts/ ← built by helm dependency update
|
||
```
|
||
|
||
## 🔗 Glue Configuration
|
||
|
||
When a subchart cannot use Helm templates in its values (e.g. it reads `values.<key>` directly without templating), the umbrella `values.yaml` must coordinate the literal names.
|
||
|
||
Example: Tempo reading MinIO host:
|
||
```yaml
|
||
minio:
|
||
fullnameOverride: "minio" # Forces service name to literal "minio"
|
||
tempo:
|
||
storage:
|
||
s3:
|
||
endpoint: "http://minio:9000" # Hardcoded literal match
|
||
```
|
||
|
||
## ⚡ KISS — Start Minimal
|
||
|
||
**Do not add knobs, flags, or options that aren’t needed right now.**
|
||
- Start with hardcoded values in the template.
|
||
- When parameterization is requested, expose it as `required` to `values.<instance>.yaml`, not `values.yaml`.
|
||
|
||
## 🧪 Testing Templates
|
||
|
||
Always test with at least two different release names and namespaces to verify independence.
|
||
|
||
```bash
|
||
helm template app1 . --namespace default
|
||
helm template app2 . --namespace production
|
||
```
|
||
|
||
## 🐛 Interactive Infrastructure Debugging
|
||
|
||
**When debugging live systems, act as an active operator:**
|
||
- ✅ **Request network access:** Ask for `kubectl port-forward` if needed.
|
||
- ✅ **Use read-only terminal tools:** Use `curl` to test endpoints, or `kubectl get/describe/logs` directly in the terminal.
|
||
- ❌ **Never modify via terminal:** Do not use the terminal to edit files or apply changes. |