---
name: helm
description: Helm chart guidelines focusing on explicit resource naming over complex umbrellas. Use when creating, modifying, or reviewing Helm charts and Kubernetes manifests.
category: infra
impact: medium
---

# Helm Chart Development Guidelines

## 🎯 Purpose
Provide strict boundaries for Helm chart development, prioritizing IaC principles, explicit naming, and minimal configurations.

**🚨 CRITICAL: If the task involves creating a ConfigMap, wiring subchart dependencies, defining values.yaml architecture, or debugging live cluster infrastructure, YOU MUST use the `read_file` tool to read `.ai/skills/helm/REFERENCE.md` BEFORE generating any code.**

## 🚨 Prohibitions (Thou Shalt Not)

- **NEVER hardcode `namespace:` in templates.** Only use `{{ .Release.Namespace }}` or a required value.
- **NEVER hardcode release names.** Only use `{{ .Release.Name }}`.
- **NEVER template `values.yaml`.** It is static and does not evaluate `{{ .Release.Namespace }}` or any function.
- **NEVER use `| default` in templates.** Use hardcoded fallbacks or `required` with a descriptive message.
- **NEVER put `required` defaults in `values.yaml`.** If it's required by the deployer, it has no baseline in `values.yaml`.
- **NEVER preemptively parameterize everything.** Start hardcoded; only extract to values when explicitly requested.
- **NEVER hide resource names** using complex `{{ include "fullname" . }}` helpers in umbrella charts.

## Workflows (Audit Checklist)

When reviewing or building a Helm project, actively check these:
1. `grep -r "namespace:" templates/` — Flag anything not `.Release.Namespace` or a `required` value.
2. `grep -r "required" templates/` — Verify that `values.yaml` does NOT contain these keys.
3. Compare `.Values.*` usages vs `values.yaml` keys — Flag unused keys.
4. Verify subchart dependencies use `condition:` booleans, not nested `.enabled`.
5. Check hooks for `helm.sh/hook-weight` (e.g. `"10"` for prereqs, `"15"` for components).

## ✅ / ❌ Examples

### Explicit Resource Naming
```yaml
# ❌ FORBIDDEN: Obfuscated by helpers
name: {{ include "mychart.fullname" . }}

# ✅ REQUIRED: Explicit and readable
name: {{ .Release.Name }}-keycloak
```

### Namespace Injection
```yaml
# ❌ FORBIDDEN: Hardcoded environment
metadata:
  namespace: production

# ✅ REQUIRED: Defer to deployer
metadata:
  namespace: {{ .Release.Namespace }}
```

### Required vs Defaults
```yaml
# ❌ FORBIDDEN: Default in template masks missing config
host: {{ .Values.global.domain | default "" }}

# ✅ REQUIRED: Fails fast and tells deployer exactly what file to edit
host: {{ required "global.domain is required in values.<env>.yaml" .Values.global.domain }}
```