helm

Package Kubernetes applications as Helm charts, configure values and dependencies, and inspect release upgrades or rollbacks.

SKILL.md

GitHub

Helm Chart Packaging AI Skill Guide (Claude)

Overview & Engine Architecture

Helm packages Kubernetes manifests as charts: Chart.yaml, values.yaml, and Go templates in templates/. A release is an installed instance with revision history; helm upgrade --install renders templates and applies via the Kubernetes API. Agents enforce local render before cluster, secrets outside values.yaml, and understanding Helm’s render-time lookup semantics— a common production footgun.

┌─────────────────────────────────────────────────────────────┐
│                 Helm release lifecycle                    │
│                                                             │
│  Chart + values (+ values.prod.yaml)                        │
│       ↓ helm lint / template / schema                       │
│  Rendered manifest batch → API server                       │
│  Hooks (pre/post install/upgrade) run weighted jobs         │
│  Revision N stored → rollback to N-1                        │
└─────────────────────────────────────────────────────────────┘

When to use / when not to

Use when

  • Templating repeated K8s YAML; promoting same chart across envs with value files.
  • Debugging failed hooks, schema validation, or subchart dependency drift.
  • Publishing charts to OCI registries or vendoring dependencies.

Do not use when

  • GitOps sync semantics and drift—pair with @argocd (Helm is render engine, not policy loop).
  • Secret management—use External Secrets / Vault (@vault), not committed prod passwords in values.yaml.

Operational Capabilities & Agent Directives

  1. helm lint + helm template on every change before install/upgrade; pipe to kubeconform in CI.
  2. Pin dependency versions in Chart.yaml; commit Chart.lock; run helm dependency build in CI.
  3. Secrets: --set-file, SOPS, or external operators—defaults in values.yaml are public.
  4. lookup caution: all templates render before anything is applied—lookup cannot see resources created earlier in the same chart on fresh install; conditional templates vanish on upgrade → Helm deletes resources. Split charts or use operators/CRDs instead of install-time lookup gates.
  5. Hooks: set weights; debug with hook pod logs; understand helm.sh/hook-delete-policy.
  6. Idempotent upgrades: explicit --namespace; --atomic for auto-rollback on failure when appropriate.
  7. Post-renderers: must fail closed (set -euo pipefail)—empty stdout deletes resources (known incident class).

Production Example: chart layout + command loop

api/
  Chart.yaml
  values.yaml
  values.schema.json
  templates/
    _helpers.tpl
    deployment.yaml
    service.yaml
    ingress.yaml
  charts/
  Chart.lock

Chart.yaml dependencies:

apiVersion: v2
name: api
version: 0.4.0
appVersion: "1.5.0"
dependencies:
  - name: redis
    version: 19.0.2
    repository: oci://registry.example.com/charts
    condition: redis.enabled
helm dependency update ./api
helm lint ./api
helm template api ./api -f values.prod.yaml > /tmp/render.yaml
helm upgrade --install api ./api -n apps --create-namespace -f values.prod.yaml --atomic --timeout 10m
helm history api -n apps
helm rollback api 3 -n apps

Deployment template excerpt (labels/helpers):

metadata:
  labels:
    {{- include "api.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: api
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"

Technical Troubleshooting Matrix

Symptom Likely cause Fix
YAML parse error at line N Template indent helm template and inspect line
Hook job never completes Failed migration job kubectl logs hook pod; fix command
Values “ignored” Wrong -f or typo in key helm get values; schema validate
Subchart missing Skipped dependency build CI must run helm dependency build
Resources deleted on upgrade lookup conditional dropped manifest Remove lookup pattern; split chart
All resources deleted Post-renderer returned empty set -euo pipefail in renderer
upgrade --install hook on first install Misread .Release.IsUpgrade Test revision; upgrade Helm if bug on old patch

Best Practices

  1. values.schema.json for required keys in large teams.
  2. Library charts for shared labels (_helpers.tpl)—no copy-paste label blocks.
  3. Keep CRD/operator installs as separate release when ordering matters.
  4. Document non-obvious values in comments or VALUES.md.
  5. OCI: pin chart version digest in GitOps repo consumed by @argocd.

Limitations

  • Helm does not build container images—CI updates tags/digests in values.
  • lookup makes charts cluster-dependent and hard to test offline.
  • Stop and ask if target cluster version, namespace policy, or CRD ownership is unclear.

Related Skills

  • @kubernetes — raw manifests and pod debugging
  • @argocd — GitOps delivery of Helm releases
  • @docker — image build and digest promotion
  • @github-actions — lint/template in CI

Agent Operational Directive

MANDATORY: Never ship chart changes without helm lint and helm template output reviewed. Do not use lookup to conditionally omit resources unless ownership and upgrade behavior are explicitly designed—prefer two-chart sequential install. Keep production secrets out of Git values. Fail CI if post-render scripts can emit empty manifests.


Source anchors (research)