feat(helm): support extra volumes/mounts; add external API key mount-path validation

helm/README.md

@@ -255,6 +255,14 @@ kubectl create secret -n example-namespace generic example-secret-name --from-li
 
 The secret can then be used with `existingSecretName`.
 
+For advanced integrations, you can also use component-scoped `extraVolumes` and `extraVolumeMounts` to attach additional volumes such as CSI-backed secrets to specific workloads:
+
+- `components.agent.extraVolumes` / `components.agent.extraVolumeMounts`
+- `components.aggregator.extraVolumes` / `components.aggregator.extraVolumeMounts`
+- `components.webhookServer.extraVolumes` / `components.webhookServer.extraVolumeMounts`
+- `components.webhookServer.backfill.extraVolumes` / `components.webhookServer.backfill.extraVolumeMounts`
+- `components.miscellaneous.configLoader.extraVolumes` / `components.miscellaneous.configLoader.extraVolumeMounts`
+
 ### Update Helm Chart
 
 If you are updating an existing installation, pull the latest chart information:

helm/templates/NOTES.txt

@@ -11,6 +11,21 @@ it is likely you will not receive the required metrics and data in the CloudZero
 
 Please refer to the documentation for guidance on `kubeStateMetrics` settings.
 
+***************
+{{- end }}
+{{- if and (not .Values.apiKey) (not .Values.existingSecretName) }}
+***************
+
+
+****WARNING****
+
+This release is configured with both `apiKey` and `existingSecretName` unset.
+No CloudZero API key Secret volume will be mounted by the chart.
+
+If you are using an external secret mount pattern, ensure each enabled workload
+that needs the key has matching `components.*.extraVolumes` and
+`components.*.extraVolumeMounts` configured.
+
 ***************
 {{- end }}
 

helm/templates/_helpers.tpl

@@ -783,6 +783,33 @@ Volume mount for the API key
 {{- end }}
 {{- end }}
 
+{{/*
+Additional volume mounts for user-provided extensions.
+*/}}
+{{- define "cloudzero-agent.extraVolumeMounts" -}}
+{{- with (.volumeMounts | default (list)) -}}
+{{ toYaml . }}
+{{- end -}}
+{{- end }}
+
+{{/*
+Additional volumes for user-provided extensions.
+*/}}
+{{- define "cloudzero-agent.extraVolumes" -}}
+{{- with (.volumes | default (list)) -}}
+{{ toYaml . }}
+{{- end -}}
+{{- end }}
+
+{{/*
+Returns true if resource-scoped extra volumes are configured.
+*/}}
+{{- define "cloudzero-agent.hasExtraVolumes" -}}
+{{- if gt (len (.volumes | default (list))) 0 -}}
+true
+{{- end -}}
+{{- end }}
+
 {{/*
 Return the URL for the agent and insights controller to send metrics to.
 

helm/templates/agent-daemonset.yaml

@@ -183,7 +183,8 @@ spec:
             - name: cloudzero-agent-storage-volume
               mountPath: /data
               subPath: ""
-            {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}  
+            {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}
+            {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" .Values.components.agent.extraVolumeMounts) | nindent 12 }}
       {{- include "cloudzero-agent.generatePodSecurityContext" (mergeOverwrite
           (.Values.defaults.securityContext | default (dict))
           (.Values.components.agent.federatedNode.securityContext | default (dict))
@@ -206,6 +207,7 @@ spec:
           secret:
             secretName: {{ include "cloudzero-agent.secretName" . }}
         {{- end }}
+        {{- include "cloudzero-agent.extraVolumes" (dict "volumes" .Values.components.agent.extraVolumes) | nindent 8 }}
         - name: cloudzero-agent-storage-volume
           emptyDir:
           {{- if .Values.server.emptyDir.sizeLimit }}

helm/templates/agent-deploy.yaml

@@ -78,6 +78,7 @@ spec:
             ) | nindent 10 }}
           volumeMounts:
           {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}
+          {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" .Values.components.agent.extraVolumeMounts) | nindent 12 }}
             - name: lifecycle-volume
               mountPath: /checks/bin/
             - name: validator-config-volume
@@ -102,6 +103,7 @@ spec:
             ) | nindent 10 }}
           volumeMounts:
           {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}
+          {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" .Values.components.agent.extraVolumeMounts) | nindent 12 }}
             - name: lifecycle-volume
               mountPath: /checks/bin/
             - name: validator-config-volume
@@ -234,6 +236,7 @@ spec:
             - name: validator-config-volume
               mountPath: /checks/app/config/
             {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}
+            {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" .Values.components.agent.extraVolumeMounts) | nindent 12 }}
         {{- end }}{{/* End Prometheus container */}}
         {{- if eq (include "cloudzero-agent.Values.components.agent.mode" .) "clustered" }}
         # CloudZero Alloy container (binary embedded in agent image)
@@ -315,6 +318,7 @@ spec:
             - name: alloy-tmp
               mountPath: /tmp
             {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}
+            {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" .Values.components.agent.extraVolumeMounts) | nindent 12 }}
         {{- end }}{{/* End Alloy container */}}
       {{- include "cloudzero-agent.generatePodSecurityContext" (mergeOverwrite
           (.Values.defaults.securityContext | default (dict))
@@ -348,6 +352,7 @@ spec:
           secret:
             secretName: {{ include "cloudzero-agent.secretName" . }}
         {{- end }}
+        {{- include "cloudzero-agent.extraVolumes" (dict "volumes" .Values.components.agent.extraVolumes) | nindent 8 }}
         - name: cloudzero-agent-storage-volume
         {{- if .Values.server.persistentVolume.enabled }}
           persistentVolumeClaim:

helm/templates/aggregator-deploy.yaml

@@ -85,6 +85,7 @@ spec:
               value: "{{ .Values.aggregator.collector.port }}"
           volumeMounts:
             {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}
+            {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" .Values.components.aggregator.extraVolumeMounts) | nindent 12 }}
             - name: aggregator-config-volume
               mountPath: {{ .Values.aggregator.mountRoot }}/config
               readOnly: true
@@ -131,6 +132,7 @@ spec:
               value: "{{ .Values.aggregator.shipper.port }}"
           volumeMounts:
             {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}
+            {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" .Values.components.aggregator.extraVolumeMounts) | nindent 12 }}
             - name: aggregator-config-volume
               mountPath: {{ .Values.aggregator.mountRoot }}/config
               readOnly: true
@@ -191,6 +193,7 @@ spec:
           secret:
             secretName: {{ include "cloudzero-agent.secretName" . }}
         {{- end }}
+        {{- include "cloudzero-agent.extraVolumes" (dict "volumes" .Values.components.aggregator.extraVolumes) | nindent 8 }}
         - name: aggregator-config-volume
           configMap:
             name: {{ include "cloudzero-agent.aggregator.name" . }}

helm/templates/backfill-job.yaml

@@ -166,18 +166,14 @@ spec:
               volumeMounts:
                 - name: insights-server-config
                   mountPath: {{ include "cloudzero-agent.insightsController.configurationMountPath" $ }}
+                {{- include "cloudzero-agent.apiKeyVolumeMount" $ | nindent 16 }}
+                {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" $.Values.components.webhookServer.backfill.extraVolumeMounts) | nindent 16 }}
               {{- if or $.Values.insightsController.volumeMounts $.Values.insightsController.tls.enabled }}
-              {{- if or $.Values.existingSecretName $.Values.apiKey }}
-                - name: cloudzero-api-key
-                  mountPath: {{ $.Values.serverConfig.containerSecretFilePath }}
-                  subPath: ""
-                  readOnly: true
-              {{- end }}
                 {{- with $.Values.insightsController.volumeMounts }}
                   {{- toYaml . | nindent 16 }}
                 {{- end }}
               {{- end }}
-          {{- if or $.Values.insightsController.volumes $.Values.insightsController.tls.enabled }}
+          {{- if or $.Values.insightsController.volumes $.Values.insightsController.tls.enabled (or $.Values.existingSecretName $.Values.apiKey) (include "cloudzero-agent.hasExtraVolumes" (dict "volumes" $.Values.components.webhookServer.backfill.extraVolumes)) }}
           volumes:
             - name: insights-server-config
               configMap:
@@ -192,6 +188,7 @@ spec:
               secret:
                 secretName: {{ include "cloudzero-agent.secretName" $ }}
             {{- end }}
+            {{- include "cloudzero-agent.extraVolumes" (dict "volumes" $.Values.components.webhookServer.backfill.extraVolumes) | nindent 12 }}
             {{- with $.Values.insightsController.volumes }}
               {{- toYaml . | nindent 12 }}
             {{- end }}

helm/templates/config-loader-job.yaml

@@ -91,6 +91,7 @@ spec:
               ) | nindent 10 }}
           volumeMounts:
             {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}
+            {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" .Values.components.miscellaneous.configLoader.extraVolumeMounts) | nindent 12 }}
             - name: config-values
               mountPath: /cloudzero/config/values # values.yaml
             - name: config-volume
@@ -127,6 +128,7 @@ spec:
           secret:
             secretName: {{ include "cloudzero-agent.secretName" . }}
         {{- end }}
+        {{- include "cloudzero-agent.extraVolumes" (dict "volumes" .Values.components.miscellaneous.configLoader.extraVolumes) | nindent 8 }}
         {{- with .Values.insightsController.volumes }}
           {{- toYaml . | nindent 8 }}
         {{- end }}

helm/templates/webhook-deploy.yaml

@@ -131,18 +131,14 @@ spec:
           volumeMounts:
             - name: insights-server-config
               mountPath: {{ include "cloudzero-agent.insightsController.configurationMountPath" . }}
+            {{- include "cloudzero-agent.apiKeyVolumeMount" . | nindent 12 }}
+            {{- include "cloudzero-agent.extraVolumeMounts" (dict "volumeMounts" .Values.components.webhookServer.extraVolumeMounts) | nindent 12 }}
           {{- if or .Values.insightsController.volumeMounts .Values.insightsController.tls.enabled }}
             {{- if .Values.insightsController.tls.enabled }}
             - name: tls-certs
               mountPath: {{ .Values.insightsController.tls.mountPath }}
               readOnly: true
             {{- end }}
-          {{- if or .Values.existingSecretName .Values.apiKey }}
-            - name: cloudzero-api-key
-              mountPath: {{ .Values.serverConfig.containerSecretFilePath }}
-              subPath: ""
-              readOnly: true
-          {{- end }}
             {{- with .Values.insightsController.volumeMounts }}
               {{- toYaml . | nindent 12 }}
             {{- end }}
@@ -169,7 +165,7 @@ spec:
             successThreshold: {{ .Values.insightsController.server.healthCheck.successThreshold }}
             failureThreshold: {{ .Values.insightsController.server.healthCheck.failureThreshold }}
           {{- end }}
-      {{- if or .Values.insightsController.volumes .Values.insightsController.tls.enabled }}
+      {{- if or .Values.insightsController.volumes .Values.insightsController.tls.enabled (or .Values.existingSecretName .Values.apiKey) (include "cloudzero-agent.hasExtraVolumes" (dict "volumes" .Values.components.webhookServer.extraVolumes)) }}
       volumes:
         - name: insights-server-config
           configMap:
@@ -184,6 +180,7 @@ spec:
           secret:
             secretName: {{ include "cloudzero-agent.secretName" . }}
         {{- end }}
+        {{- include "cloudzero-agent.extraVolumes" (dict "volumes" .Values.components.webhookServer.extraVolumes) | nindent 8 }}
         {{- with .Values.insightsController.volumes }}
           {{- toYaml . | nindent 8 }}
         {{- end }}

helm/tests/api_key_mount_path_validation_test.yaml

@@ -0,0 +1,31 @@
+suite: test external api key mode behavior
+templates:
+  - templates/aggregator-deploy.yaml
+tests:
+  - it: should render when both apiKey and existingSecretName are null
+    set:
+      apiKey: null
+      existingSecretName: null
+    asserts:
+      - isKind:
+          of: Deployment
+
+  - it: should not create cloudzero-api-key volume when both apiKey and existingSecretName are null
+    set:
+      apiKey: null
+      existingSecretName: null
+    asserts:
+      - notContains:
+          path: spec.template.spec.volumes
+          content:
+            name: cloudzero-api-key
+
+  - it: should not create cloudzero-api-key volumeMount when both apiKey and existingSecretName are null
+    set:
+      apiKey: null
+      existingSecretName: null
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].volumeMounts
+          content:
+            name: cloudzero-api-key

helm/tests/apikey_secret_validation_test.yaml

@@ -2,18 +2,15 @@ suite: test apiKey and existingSecretName validation
 templates:
   - aggregator-secret.yaml
 tests:
-  # Schema validation failure tests - these test the anyOf + oneOf constraints
+  # API key source validation tests
 
-  - it: should fail when neither apiKey nor existingSecretName is set
-    values:
-      - ../values.yaml # Use empty base values
+  - it: should allow external mode when both apiKey and existingSecretName are null
     set:
       apiKey: null
       existingSecretName: null
-      host: api.cloudzero.com
     asserts:
-      - failedTemplate:
-          errorPattern: "anyOf"
+      - hasDocuments:
+          count: 0
 
   - it: should fail when both apiKey and existingSecretName are set
     set: