From 7ba8056ce9fb94f9da92f8596d1405531b541099 Mon Sep 17 00:00:00 2001
From: moilanik <niko.moilanen@tietoevry.com>
Date: Tue, 10 Mar 2026 10:58:04 +0200
Subject: [PATCH] docs(helm): add guidance for multiple files in ConfigMap data

New subsection "Multiple Files in ConfigMap data":
- start with inline range for few files (readable in template)
- shift to files/ + .AsConfig + tpl when >3 files (readability suffers)
- explains threshold for when to switch patterns
- shows both inline and file-based examples
- enables template variables in file-based approach
---
 .ai/instructions/skills/helm.instructions.md | 37 ++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/.ai/instructions/skills/helm.instructions.md b/.ai/instructions/skills/helm.instructions.md
index 1b51394..4c81256 100644
--- a/.ai/instructions/skills/helm.instructions.md
+++ b/.ai/instructions/skills/helm.instructions.md
@@ -274,6 +274,43 @@ server:
 **Why:** Config files are readable, diffable, and version-controlled as real files.
 Large configs in values.yaml become unmaintainable and hard to review.
 
+### Multiple Files in ConfigMap data
+
+When a ConfigMap needs multiple files as separate keys (e.g. dashboards, rules):
+
+**Start with inline range:**
+
+```yaml
+# Few files — use inline range
+data:
+  {{- range $path, $_ := .Files.Glob "files/dashboards/*.json" }}
+  {{ base $path }}: {{ $.Files.Get $path | quote }}
+  {{- end }}
+```
+
+**Shift to files + tpl when:**
+- You have many files (>3) — readability suffers in the template
+- Files need Helm variables — `{{ .Values.xxx }}` expressions must be processed
+
+When you cross this threshold, move the files to a directory and use `.AsConfig` + `tpl` to process them:
+
+```yaml
+# templates/configmap.yaml
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: dashboards
+data: {{ (tpl (.Files.Glob "files/dashboards/*").AsConfig . ) | nindent 2 }}
+```
+
+```json
+# files/dashboards/dashboard.json — can now contain {{ .Values.xxx }} expressions
+{
+  "namespace": "{{ .Release.Namespace }}",
+  "alertmanager": "{{ .Values.alertmanager.host }}"
+}
+```
+
 **When `.AsConfig` + `tpl` is required:**
 - Config file contains `{{ }}` template expressions → always use `.AsConfig` + `tpl`
 - Config file contains special characters (`*`, `{`, `}`) → `.AsConfig` handles escaping safely