Helm

---
name: helm
description: "Expert coverage of the Helm package manager (Helm 3 and Helm 4): chart development, Go templates, values, hooks, OCI registries, SSA, Helmfile, helm-secrets, and dependency management. Use for \"Helm\", \"Helm chart\", \"helm install\", \"helm template\", \"Helmfile\", \"helm-secrets\", \"Chart.yaml\", \"values.yaml\", \"OCI registry\". Do NOT use for GitOps continuous-delivery of Helm releases (auto-sync, drift detection, app-of-apps) -- that's the `argocd` or `flux` skill (in the `devops` plugin)."
license: MIT
---

# Helm

This skill covers Helm, the Kubernetes package manager, across Helm 3 and Helm 4 (current: 4.1.x, released KubeCon 2025).

Your knowledge covers:

- Chart structure, metadata, and packaging
- Go template language (sprig functions, named templates, control flow)
- Values files, schema validation, multi-document values
- Hooks (pre/post-install, pre/post-upgrade, tests)
- OCI registry support (default in Helm 4, push/pull/install by digest)
- Server-Side Apply (SSA) in Helm 4 (replacing client-side 3-way merge)
- Dependency management (sub-charts, conditions, aliases)
- Helmfile for multi-release orchestration
- helm-secrets with SOPS backends
- Library charts and chart reuse patterns
- Release management (install, upgrade, rollback, history)

## How to Approach Tasks

1. **Classify** the request:
   - **Chart development** -- Load `references/architecture.md` for chart structure, templates, hooks
   - **Best practices** -- Load `references/best-practices.md` for chart design, CI/CD, security
   - **Debugging** -- Template rendering issues, release failures, hook problems
   - **Migration** -- Helm 3 to Helm 4, Helm 2 to Helm 3/4
   - **Helmfile** -- Multi-release management, environment-specific values

2. **Identify Helm version** -- Helm 3 and 4 differ significantly (SSA vs 3-way merge, wasm plugins vs exec plugins, kstatus vs rollout). Ask if unclear.

3. **Load context** -- Read the relevant reference file for deep detail.

4. **Apply** -- Provide working template code, CLI commands, and configuration.

5. **Validate** -- Suggest `helm template`, `helm lint`, `helm install --dry-run` to verify.

## Helm 3 vs Helm 4

| Feature | Helm 3 | Helm 4 |
|---------|--------|--------|
| Apply strategy | Client-side 3-way merge | Server-Side Apply (SSA) |
| Plugin system | Exec-based | WebAssembly (wasm) |
| Resource readiness | Rollout status | kstatus |
| OCI support | Experimental → GA | Default recommended |
| Caching | None | Local content-based cache |
| Logging | Legacy | slog-based structured |
| Multi-doc values | No | Yes (YAML `---` delimiters) |
| Install by digest | No | Yes (`oci://...@sha256:abc`) |

**SSA impact**: Helm 4's server-side apply eliminates most "field conflict" errors that plagued Helm 3 when resources were modified outside Helm. SSA uses field ownership tracking -- Helm owns the fields it manages, and other tools (kubectl, operators) can own other fields without conflict.

**Migration**: Helm 4 can manage releases created by Helm 3. Run `helm upgrade` with Helm 4 binary to migrate a release. SSA is applied on the next upgrade.

## Chart Structure

```
mychart/
├── Chart.yaml             # Chart metadata (required)
├── values.yaml            # Default values (required)
├── values.schema.json     # JSON Schema for values validation (recommended)
├── charts/                # Dependency sub-charts
├── templates/             # Go template Kubernetes manifests
│   ├── _helpers.tpl       # Named templates / partials
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── NOTES.txt          # Post-install user instructions
│   └── tests/
│       └── test-connection.yaml
├── crds/                  # CRDs (applied first, never templated or upgraded)
└── .helmignore            # Exclude patterns from chart package
```

## Template Language

Helm uses Go templates with the Sprig function library. Key constructs:

```yaml
# Variable access
{{ .Values.image.repository }}
{{ .Release.Name }}
{{ .Release.Namespace }}
{{ .Chart.Name }}
{{ .Chart.Version }}

# Conditionals
{{- if .Values.ingress.enabled }}
  # render ingress
{{- end }}

# Loops
{{- range .Values.config.extraEnv }}
- name: {{ .name }}
  value: {{ .value | quote }}
{{- end }}

# Named templates (in _helpers.tpl)
{{- define "myapp.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
{{- end }}

# Include named template
{{ include "myapp.fullname" . }}

# With (set context)
{{- with .Values.nodeSelector }}
nodeSelector:
  {{- toYaml . | nindent 2 }}
{{- end }}

# Whitespace control
{{- /* dash trims leading whitespace */ -}}
```

**Common Sprig functions**: `default`, `quote`, `upper`, `lower`, `trim`, `nindent`, `toYaml`, `toJson`, `b64enc`, `sha256sum`, `lookup`, `required`, `fail`, `ternary`, `list`, `dict`, `merge`, `hasKey`.

**`required` function**: fail the template if a value is not set:
```yaml
image: {{ required "image.repository is required" .Values.image.repository }}
```

**`lookup` function**: query existing Kubernetes resources during template rendering:
```yaml
{{- $secret := lookup "v1" "Secret" .Release.Namespace "my-secret" -}}
{{- if $secret }}
# secret exists
{{- end }}
```

## Hooks

Hooks are resources annotated with `helm.sh/hook`. They execute at specific points in the release lifecycle:

| Hook | When |
|------|------|
| `pre-install` | Before any release resources are created |
| `post-install` | After all release resources are created |
| `pre-upgrade` | Before upgrade begins |
| `post-upgrade` | After upgrade completes |
| `pre-delete` | Before deletion begins |
| `post-delete` | After deletion completes |
| `pre-rollback` | Before rollback begins |
| `post-rollback` | After rollback completes |
| `test` | Executed by `helm test` |

**Hook weights**: control execution order (`-5` runs before `5`).

**Hook delete policies**: `before-hook-creation` (delete previous hook resource before creating new), `hook-succeeded` (delete after success), `hook-failed` (delete after failure).

**Common pattern -- database migration**:
```yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ include "myapp.fullname" . }}-migrate
  annotations:
    "helm.sh/hook": pre-upgrade,pre-install
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
```

## OCI Registries

OCI distribution is the default in Helm 4, replacing the legacy `helm repo add` + index.yaml model:

```bash
# Push chart
helm package ./mychart
helm push mychart-1.5.0.tgz oci://registry.example.com/charts

# Install from OCI
helm install myapp oci://registry.example.com/charts/mychart --version 1.5.0

# Install by digest (supply chain security, Helm 4)
helm install myapp oci://registry.example.com/charts/mychart@sha256:abc123...

# Login
helm registry login registry.example.com -u user -p token
```

Compatible registries: Docker Hub, GHCR, ECR, ACR, GCR, Harbor, Quay.

## Release Management

```bash
# Install
helm install <release-name> <chart> -n <namespace> --create-namespace -f values.yaml

# Upgrade
helm upgrade <release-name> <chart> -n <namespace> -f values.yaml

# Install or upgrade (idempotent)
helm upgrade --install <release-name> <chart> -n <namespace> -f values.yaml

# Rollback
helm rollback <release-name> <revision> -n <namespace>

# History
helm history <release-name> -n <namespace>

# Uninstall
helm uninstall <release-name> -n <namespace>

# Dry run (Helm 4: SSA dry-run on server)
helm install <release-name> <chart> --dry-run

# Template locally (no cluster needed)
helm template <release-name> <chart> -f values.yaml

# Lint
helm lint ./mychart -f values.yaml
```

## Debugging Template Issues

```bash
# Render templates locally and inspect output
helm template myrelease ./mychart -f values.yaml > rendered.yaml

# Render a specific template
helm template myrelease ./mychart -s templates/deployment.yaml

# Debug mode (shows computed values)
helm template myrelease ./mychart --debug

# Validate against cluster (Helm 4 uses SSA dry-run)
helm install myrelease ./mychart --dry-run --debug

# Check values resolution
helm show values ./mychart
```

## Dependency Management

```yaml
# Chart.yaml
dependencies:
  - name: postgresql
    version: "~13.0"                                    # SemVer range
    repository: "oci://registry-1.docker.io/bitnamicharts"
    condition: postgresql.enabled                         # toggle via values
  - name: redis
    version: "18.x.x"
    repository: "oci://registry-1.docker.io/bitnamicharts"
    alias: cache                                          # reference as .Values.cache
    tags:
      - backend                                           # enable/disable by tag group
```

```bash
helm dependency update ./mychart     # download dependencies to charts/
helm dependency build ./mychart      # rebuild from Chart.lock
helm dependency list ./mychart       # show dependencies and status
```

## Reference Files

Read these for implementation depth:

- `references/architecture.md` -- Chart structure, template engine internals, hooks lifecycle, OCI registry protocol, SSA mechanics. Read for "how does Helm work" questions.
- `references/best-practices.md` -- Chart design patterns, Helmfile orchestration, helm-secrets, dependency management, CI/CD integration, testing. Read for design and operations questions.