feat(helm/v2-alpha): add extra volumes support

Support manager.extraVolumes and manager.extraVolumeMounts: extract from
kustomize (excluding webhook-certs/metrics-certs), inject into values when
present, and template in manager deployment (including when volumes: []).
Document in Helm v2-alpha plugin page.

Generated-by: Cursor/Claude

Author: camilamacedo86

docs/book/src/cronjob-tutorial/testdata/project/dist/chart/templates/manager/manager.yaml

@@ -87,6 +87,9 @@ spec:
           {}
           {{- end }}
         volumeMounts:
+          {{- if .Values.manager.extraVolumeMounts }}
+          {{- toYaml .Values.manager.extraVolumeMounts | nindent 10 }}
+          {{- end }}
         {{- if and .Values.certManager.enable .Values.metrics.enable }}
         - mountPath: /tmp/k8s-metrics-server/metrics-certs
           name: metrics-certs
@@ -106,6 +109,9 @@ spec:
       serviceAccountName: {{ include "project.resourceName" (dict "suffix" "controller-manager" "context" $) }}
       terminationGracePeriodSeconds: 10
       volumes:
+        {{- if .Values.manager.extraVolumes }}
+        {{- toYaml .Values.manager.extraVolumes | nindent 8 }}
+        {{- end }}
       {{- if and .Values.certManager.enable .Values.metrics.enable }}
       - name: metrics-certs
         secret:

docs/book/src/getting-started/testdata/project/dist/chart/templates/manager/manager.yaml

@@ -77,7 +77,12 @@ spec:
           {{- else }}
           {}
           {{- end }}
-        volumeMounts: []
+        volumeMounts:
+          {{- if .Values.manager.extraVolumeMounts }}
+          {{- toYaml .Values.manager.extraVolumeMounts | nindent 10 }}
+          {{- else }}
+          []
+          {{- end }}
       securityContext:
         {{- if .Values.manager.podSecurityContext }}
         {{- toYaml .Values.manager.podSecurityContext | nindent 8 }}
@@ -86,4 +91,9 @@ spec:
         {{- end }}
       serviceAccountName: {{ include "project.resourceName" (dict "suffix" "controller-manager" "context" $) }}
       terminationGracePeriodSeconds: 10
-      volumes: []
+      volumes:
+        {{- if .Values.manager.extraVolumes }}
+        {{- toYaml .Values.manager.extraVolumes | nindent 8 }}
+        {{- else }}
+        []
+        {{- end }}

docs/book/src/multiversion-tutorial/testdata/project/dist/chart/templates/manager/manager.yaml

@@ -87,6 +87,9 @@ spec:
           {}
           {{- end }}
         volumeMounts:
+          {{- if .Values.manager.extraVolumeMounts }}
+          {{- toYaml .Values.manager.extraVolumeMounts | nindent 10 }}
+          {{- end }}
         {{- if and .Values.certManager.enable .Values.metrics.enable }}
         - mountPath: /tmp/k8s-metrics-server/metrics-certs
           name: metrics-certs
@@ -106,6 +109,9 @@ spec:
       serviceAccountName: {{ include "project.resourceName" (dict "suffix" "controller-manager" "context" $) }}
       terminationGracePeriodSeconds: 10
       volumes:
+        {{- if .Values.manager.extraVolumes }}
+        {{- toYaml .Values.manager.extraVolumes | nindent 8 }}
+        {{- end }}
       {{- if and .Values.certManager.enable .Values.metrics.enable }}
       - name: metrics-certs
         secret:

docs/book/src/plugins/available/helm-v2-alpha.md

@@ -318,6 +318,15 @@ prometheus:
   enable: false
 ```
 
+### Extra volumes
+
+The chart supports extra volumes and volume mounts for the manager (e.g. secrets, config files) in addition to the built-in webhook and metrics cert volumes.
+
+- **From kustomize**: If your deployment in `dist/install.yaml` includes volumes other than the default `webhook-certs` and `metrics-certs` (from the scaffolded patches), the plugin adds them to `values.yaml` as `manager.extraVolumes` and `manager.extraVolumeMounts`. The manager template merges them into the deployment.
+- **Manual**: You can add `manager.extraVolumes` and `manager.extraVolumeMounts` in `values.yaml` yourself; the template will use them. Use the same structure as in a Pod spec (list of volume and volumeMount entries). Mount names in `extraVolumeMounts` must match names in `extraVolumes`.
+
+Default webhook and metrics volumes (names `webhook-certs` and `metrics-certs`) are always handled by the chart and are not part of the extra lists.
+
 ### Installation
 
 The first time you run the plugin, it adds convenient Helm deployment targets to your `Makefile`:

pkg/plugins/optional/helm/v2alpha/scaffolds/internal/kustomize/chart_converter.go

@@ -134,6 +134,10 @@ func (c *ChartConverter) ExtractDeploymentConfig() map[string]any {
 	extractContainerResources(container, config)
 	extractContainerSecurityContext(container, config)
 
+	// Extra volumes/mounts from input (exclude default webhook/metrics volumes; those are templated separately)
+	extractExtraVolumes(specMap, config)
+	extractExtraVolumeMounts(container, config)
+
 	return config
 }
 
@@ -416,3 +420,68 @@ func extractContainerSecurityContext(container map[string]any, config map[string
 
 	config["securityContext"] = securityContext
 }
+
+// Default volume names from the Kustomize scaffold (manager_webhook_patch.yaml and
+// cert_metrics_manager_patch.yaml). These match what main.go's --webhook-cert-path and
+// --metrics-cert-path are used with. Volumes with these names are never considered "extra".
+var defaultWebhookMetricsVolumeNames = map[string]struct{}{
+	"webhook-certs": {}, // manager_webhook_patch.yaml
+	"metrics-certs": {}, // cert_metrics_manager_patch.yaml
+}
+
+// extractExtraVolumes copies pod volumes into config["extraVolumes"], excluding volumes
+// whose name is one of the default webhook/metrics names from the Kustomize scaffold.
+// Only set when there is at least one extra volume.
+func extractExtraVolumes(specMap map[string]any, config map[string]any) {
+	volumes, found, err := unstructured.NestedFieldNoCopy(specMap, "volumes")
+	if !found || err != nil {
+		return
+	}
+	volumesList, ok := volumes.([]any)
+	if !ok || len(volumesList) == 0 {
+		return
+	}
+	extra := make([]any, 0, len(volumesList))
+	for _, v := range volumesList {
+		vm, ok := v.(map[string]any)
+		if !ok {
+			continue
+		}
+		name, _ := vm["name"].(string)
+		if _, isDefault := defaultWebhookMetricsVolumeNames[name]; isDefault {
+			continue
+		}
+		extra = append(extra, v)
+	}
+	if len(extra) > 0 {
+		config["extraVolumes"] = extra
+	}
+}
+
+// extractExtraVolumeMounts copies container volumeMounts into config["extraVolumeMounts"],
+// excluding mounts that reference the default webhook/metrics volume names. Only set when there is at least one extra.
+func extractExtraVolumeMounts(container map[string]any, config map[string]any) {
+	mounts, found, err := unstructured.NestedFieldNoCopy(container, "volumeMounts")
+	if !found || err != nil {
+		return
+	}
+	mountsList, ok := mounts.([]any)
+	if !ok || len(mountsList) == 0 {
+		return
+	}
+	extra := make([]any, 0, len(mountsList))
+	for _, m := range mountsList {
+		mm, ok := m.(map[string]any)
+		if !ok {
+			continue
+		}
+		name, _ := mm["name"].(string)
+		if _, isDefault := defaultWebhookMetricsVolumeNames[name]; isDefault {
+			continue
+		}
+		extra = append(extra, m)
+	}
+	if len(extra) > 0 {
+		config["extraVolumeMounts"] = extra
+	}
+}

pkg/plugins/optional/helm/v2alpha/scaffolds/internal/kustomize/chart_converter_test.go

@@ -311,6 +311,64 @@ var _ = Describe("ChartConverter", func() {
 			config := converter.ExtractDeploymentConfig()
 			Expect(config).To(BeEmpty())
 		})
+
+		It("should extract extraVolumes and extraVolumeMounts excluding webhook and metrics", func() {
+			volumes := []any{
+				map[string]any{
+					"name":   "webhook-certs",
+					"secret": map[string]any{"secretName": "webhook-server-cert"},
+				},
+				map[string]any{
+					"name":   "custom-volume",
+					"secret": map[string]any{"secretName": "my-secret"},
+				},
+			}
+			volumeMounts := []any{
+				map[string]any{
+					"name":      "webhook-certs",
+					"mountPath": "/tmp/k8s-webhook-server/serving-certs",
+					"readOnly":  true,
+				},
+				map[string]any{
+					"name":      "custom-volume",
+					"mountPath": "/etc/my-secrets",
+					"readOnly":  true,
+				},
+			}
+			containers := []any{
+				map[string]any{
+					"name":         "manager",
+					"image":        "controller:latest",
+					"volumeMounts": volumeMounts,
+				},
+			}
+			err := unstructured.SetNestedSlice(
+				resources.Deployment.Object,
+				volumes,
+				"spec", "template", "spec", "volumes",
+			)
+			Expect(err).NotTo(HaveOccurred())
+			err = unstructured.SetNestedSlice(
+				resources.Deployment.Object,
+				containers,
+				"spec", "template", "spec", "containers",
+			)
+			Expect(err).NotTo(HaveOccurred())
+
+			config := converter.ExtractDeploymentConfig()
+
+			Expect(config).To(HaveKey("extraVolumes"))
+			extraVols, ok := config["extraVolumes"].([]any)
+			Expect(ok).To(BeTrue())
+			Expect(extraVols).To(HaveLen(1))
+			Expect(extraVols[0]).To(HaveKeyWithValue("name", "custom-volume"))
+
+			Expect(config).To(HaveKey("extraVolumeMounts"))
+			extraMounts, ok := config["extraVolumeMounts"].([]any)
+			Expect(ok).To(BeTrue())
+			Expect(extraMounts).To(HaveLen(1))
+			Expect(extraMounts[0]).To(HaveKeyWithValue("mountPath", "/etc/my-secrets"))
+		})
 	})
 
 	Context("extractPortFromArg", func() {

pkg/plugins/optional/helm/v2alpha/scaffolds/internal/kustomize/helm_templater.go

@@ -737,17 +737,78 @@ func (t *HelmTemplater) templateSecurityContexts(yamlContent string) string {
 	return yamlContent
 }
 
-// templateVolumeMounts converts volumeMounts sections to keep them as-is since they're webhook-specific
+// templateVolumeMounts injects .Values.manager.extraVolumeMounts (append or replace empty list).
 func (t *HelmTemplater) templateVolumeMounts(yamlContent string) string {
-	// For webhook volumeMounts, we keep them as-is since they're required for webhook functionality
-	// They will be conditionally included based on webhook configuration
-	return yamlContent
+	return t.appendToListFromValues(yamlContent, "volumeMounts:", ".Values.manager.extraVolumeMounts")
 }
 
-// templateVolumes converts volumes sections to keep them as-is since they're webhook-specific
+// templateVolumes injects .Values.manager.extraVolumes (append or replace empty list).
 func (t *HelmTemplater) templateVolumes(yamlContent string) string {
-	// For webhook volumes, we keep them as-is since they're required for webhook functionality
-	// They will be conditionally included based on webhook configuration
+	return t.appendToListFromValues(yamlContent, "volumes:", ".Values.manager.extraVolumes")
+}
+
+// appendToListFromValues finds "key:" or "key: []", and either appends values path to an existing list
+// or replaces "key: []" with a template that outputs the values path when set. Idempotent if already present.
+func (t *HelmTemplater) appendToListFromValues(yamlContent string, keyColon string, valuesPath string) string {
+	if !strings.Contains(yamlContent, keyColon) {
+		return yamlContent
+	}
+	if strings.Contains(yamlContent, valuesPath) {
+		return yamlContent
+	}
+
+	lines := strings.Split(yamlContent, "\n")
+	keyEmpty := keyColon + " []"
+
+	for i := range lines {
+		trimmed := strings.TrimSpace(lines[i])
+		indentStr, indentLen := leadingWhitespace(lines[i])
+		childIndent := indentStr + "  "
+		childIndentWidth := strconv.Itoa(len(childIndent))
+
+		// Case 1: "key: []" (Kustomize default) — replace with template so extra* values are used
+		if trimmed == keyEmpty {
+			block := []string{
+				indentStr + keyColon,
+				childIndent + "{{- if " + valuesPath + " }}",
+				childIndent + "{{- toYaml " + valuesPath + " | nindent " + childIndentWidth + " }}",
+				childIndent + "{{- else }}",
+				childIndent + "[]",
+				childIndent + "{{- end }}",
+			}
+			newLines := append([]string{}, lines[:i]...)
+			newLines = append(newLines, block...)
+			newLines = append(newLines, lines[i+1:]...)
+			return strings.Join(newLines, "\n")
+		}
+
+		// Case 2: "key:" with multi-line list — append values path after list
+		if trimmed != keyColon {
+			continue
+		}
+
+		end := i + 1
+		for ; end < len(lines); end++ {
+			tLine := strings.TrimSpace(lines[end])
+			if tLine == "" {
+				break
+			}
+			lineIndent := len(lines[end]) - len(strings.TrimLeft(lines[end], " \t"))
+			if lineIndent <= indentLen {
+				break
+			}
+		}
+
+		block := []string{
+			childIndent + "{{- if " + valuesPath + " }}",
+			childIndent + "{{- toYaml " + valuesPath + " | nindent " + childIndentWidth + " }}",
+			childIndent + "{{- end }}",
+		}
+		newLines := append([]string{}, lines[:end]...)
+		newLines = append(newLines, block...)
+		newLines = append(newLines, lines[end:]...)
+		return strings.Join(newLines, "\n")
+	}
 	return yamlContent
 }
 

pkg/plugins/optional/helm/v2alpha/scaffolds/internal/kustomize/helm_templater_test.go

@@ -2100,6 +2100,65 @@ spec:
 			Expect(result).To(ContainSubstring("name: controller-test"))
 		})
 
+		It("should append extraVolumes and extraVolumeMounts when lists are present", func() {
+			deployment := &unstructured.Unstructured{}
+			deployment.SetAPIVersion("apps/v1")
+			deployment.SetKind("Deployment")
+			deployment.SetName("test-project-controller-manager")
+
+			content := `apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: test-project-controller-manager
+spec:
+  template:
+    spec:
+      volumes:
+      - name: webhook-certs
+        secret:
+          secretName: webhook-server-cert
+      containers:
+      - name: manager
+        image: controller:latest
+        volumeMounts:
+        - name: webhook-certs
+          mountPath: /tmp/k8s-webhook-server/serving-certs
+          readOnly: true
+`
+
+			result := templater.ApplyHelmSubstitutions(content, deployment)
+
+			Expect(result).To(ContainSubstring(".Values.manager.extraVolumes"))
+			Expect(result).To(ContainSubstring(".Values.manager.extraVolumeMounts"))
+		})
+
+		It("should inject extraVolumes/extraVolumeMounts when Kustomize has volumeMounts: [] and volumes: []", func() {
+			deployment := &unstructured.Unstructured{}
+			deployment.SetAPIVersion("apps/v1")
+			deployment.SetKind("Deployment")
+			deployment.SetName("test-project-controller-manager")
+
+			// Default Kustomize output: single-line empty lists (no webhook/metrics patches)
+			content := `apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: test-project-controller-manager
+spec:
+  template:
+    spec:
+      containers:
+      - name: manager
+        image: controller:latest
+        volumeMounts: []
+      volumes: []`
+
+			result := templater.ApplyHelmSubstitutions(content, deployment)
+
+			// Plugin must inject template so values work without manual manager.yaml edits
+			Expect(result).To(ContainSubstring(".Values.manager.extraVolumes"))
+			Expect(result).To(ContainSubstring(".Values.manager.extraVolumeMounts"))
+		})
+
 		It("should fall back to 'manager' when default-container annotation is missing", func() {
 			deployment := &unstructured.Unstructured{}
 			deployment.SetAPIVersion("apps/v1")