64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
---
|
|
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 }}
|
|
```
|