feat(helm): add metrics endpoint and optional ServiceMonitor support

helm/kagent/templates/controller-configmap.yaml

@@ -56,6 +56,10 @@ data:
   STREAMING_MAX_BUF_SIZE: {{ .Values.controller.streaming.maxBufSize | quote }}
   STREAMING_TIMEOUT: {{ .Values.controller.streaming.timeout | quote }}
   WATCH_NAMESPACES: {{ include "kagent.watchNamespaces" . | quote }}
+  {{- if .Values.controller.metrics.enabled }}
+  METRICS_BIND_ADDRESS: ":{{ .Values.controller.metrics.port }}"
+  METRICS_SECURE: {{ .Values.controller.metrics.secure | quote }}
+  {{- end }}
   ZAP_LOG_LEVEL: {{ .Values.controller.loglevel | quote }}
   {{- $agentHost := "" }}
   {{- if and .Values.controller.agentDeployment .Values.controller.agentDeployment.host (not (eq .Values.controller.agentDeployment.host "")) }}

helm/kagent/templates/controller-deployment.yaml

@@ -97,6 +97,11 @@ spec:
             - name: http
               containerPort: {{ .Values.controller.service.ports.targetPort }}
               protocol: TCP
+            {{- if .Values.controller.metrics.enabled }}
+            - name: metrics
+              containerPort: {{ .Values.controller.metrics.port }}
+              protocol: TCP
+            {{- end }}
           resources:
             {{- toYaml .Values.controller.resources | nindent 12 }}
           {{- with (.Values.controller.securityContext | default .Values.securityContext) }}

helm/kagent/templates/controller-service.yaml

@@ -12,5 +12,11 @@ spec:
       targetPort: {{ .Values.controller.service.ports.targetPort }}
       protocol: TCP
       name: controller
+    {{- if .Values.controller.metrics.enabled }}
+    - port: {{ .Values.controller.metrics.port }}
+      targetPort: {{ .Values.controller.metrics.port }}
+      protocol: TCP
+      name: metrics
+    {{- end }}
   selector:
     {{- include "kagent.controller.selectorLabels" . | nindent 4 }}

helm/kagent/templates/controller-servicemonitor.yaml

@@ -0,0 +1,25 @@
+{{- if and .Values.controller.metrics.enabled .Values.controller.metrics.serviceMonitor.enabled (.Capabilities.APIVersions.Has "monitoring.coreos.com/v1/ServiceMonitor") }}
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: {{ include "kagent.fullname" . }}-controller
+  namespace: {{ include "kagent.namespace" . }}
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+    {{- with .Values.controller.metrics.serviceMonitor.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  selector:
+    matchLabels:
+      {{- include "kagent.controller.selectorLabels" . | nindent 6 }}
+  endpoints:
+  - port: metrics
+    interval: {{ .Values.controller.metrics.serviceMonitor.interval }}
+    scrapeTimeout: {{ .Values.controller.metrics.serviceMonitor.scrapeTimeout }}
+    {{- if .Values.controller.metrics.secure }}
+    scheme: https
+    tlsConfig:
+      insecureSkipVerify: true
+    {{- end }}
+{{- end }}

helm/kagent/templates/rbac/metrics-auth-role.yaml

@@ -0,0 +1,30 @@
+{{- if .Values.controller.metrics.enabled }}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: {{ include "kagent.fullname" . }}-metrics-auth-role
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+rules:
+- apiGroups: ["authentication.k8s.io"]
+  resources: ["tokenreviews"]
+  verbs: ["create"]
+- apiGroups: ["authorization.k8s.io"]
+  resources: ["subjectaccessreviews"]
+  verbs: ["create"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: {{ include "kagent.fullname" . }}-metrics-auth-rolebinding
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: {{ include "kagent.fullname" . }}-metrics-auth-role
+subjects:
+- kind: ServiceAccount
+  name: {{ include "kagent.fullname" . }}-controller
+  namespace: {{ include "kagent.namespace" . }}
+{{- end }}

helm/kagent/templates/rbac/metrics-reader-role.yaml

@@ -0,0 +1,11 @@
+{{- if .Values.controller.metrics.enabled }}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: {{ include "kagent.fullname" . }}-metrics-reader
+  labels:
+    {{- include "kagent.labels" . | nindent 4 }}
+rules:
+- nonResourceURLs: ["/metrics"]
+  verbs: ["get"]
+{{- end }}

helm/kagent/tests/controller-deployment_test.yaml

@@ -76,6 +76,29 @@ tests:
       - equal:
           path: spec.template.spec.containers[0].ports[0].containerPort
           value: 8083
+      - lengthEqual:
+          path: spec.template.spec.containers[0].ports
+          count: 1
+
+  - it: should add metrics port and env vars when enabled
+    set:
+      controller.metrics.enabled: true
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: metrics
+            containerPort: 9093
+            protocol: TCP
+        template: controller-deployment.yaml
+      - equal:
+          path: data.METRICS_BIND_ADDRESS
+          value: ":9093"
+        template: controller-configmap.yaml
+      - equal:
+          path: data.METRICS_SECURE
+          value: "false"
+        template: controller-configmap.yaml
 
   - it: should set A2A_BASE_URL with computed default value
     template: controller-configmap.yaml

helm/kagent/tests/controller-service_test.yaml

@@ -29,6 +29,9 @@ tests:
       - equal:
           path: spec.ports[0].protocol
           value: TCP
+      - lengthEqual:
+          path: spec.ports
+          count: 1
 
   - it: should have correct selector labels
     asserts:
@@ -68,4 +71,16 @@ tests:
     asserts:
       - equal:
           path: metadata.namespace
-          value: custom-namespace
+          value: custom-namespace
+
+  - it: should expose metrics port when enabled
+    set:
+      controller.metrics.enabled: true
+    asserts:
+      - contains:
+          path: spec.ports
+          content:
+            port: 9093
+            targetPort: 9093
+            protocol: TCP
+            name: metrics

helm/kagent/tests/controller-servicemonitor_test.yaml

@@ -0,0 +1,46 @@
+suite: test controller servicemonitor
+templates:
+  - controller-servicemonitor.yaml
+tests:
+  - it: should not render by default
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: should not render when CRD is not installed
+    set:
+      controller.metrics.enabled: true
+      controller.metrics.serviceMonitor.enabled: true
+    asserts:
+      - hasDocuments:
+          count: 0
+
+  - it: should render ServiceMonitor when both enabled and CRD present
+    set:
+      controller.metrics.enabled: true
+      controller.metrics.serviceMonitor.enabled: true
+    capabilities:
+      apiVersions:
+        - monitoring.coreos.com/v1/ServiceMonitor
+    asserts:
+      - isKind:
+          of: ServiceMonitor
+      - equal:
+          path: spec.endpoints[0].port
+          value: metrics
+
+  - it: should add TLS config when secure is true
+    set:
+      controller.metrics.enabled: true
+      controller.metrics.serviceMonitor.enabled: true
+      controller.metrics.secure: true
+    capabilities:
+      apiVersions:
+        - monitoring.coreos.com/v1/ServiceMonitor
+    asserts:
+      - equal:
+          path: spec.endpoints[0].scheme
+          value: https
+      - equal:
+          path: spec.endpoints[0].tlsConfig.insecureSkipVerify
+          value: true

helm/kagent/tests/metrics-rbac_test.yaml

@@ -0,0 +1,92 @@
+suite: test metrics rbac
+templates:
+  - rbac/metrics-auth-role.yaml
+  - rbac/metrics-reader-role.yaml
+tests:
+  - it: should not render when metrics disabled
+    asserts:
+      - hasDocuments:
+          count: 0
+        template: rbac/metrics-auth-role.yaml
+      - hasDocuments:
+          count: 0
+        template: rbac/metrics-reader-role.yaml
+
+  - it: should render metrics-auth ClusterRole and ClusterRoleBinding when metrics enabled
+    set:
+      controller.metrics.enabled: true
+    template: rbac/metrics-auth-role.yaml
+    asserts:
+      - hasDocuments:
+          count: 2
+      - isKind:
+          of: ClusterRole
+        documentIndex: 0
+      - isKind:
+          of: ClusterRoleBinding
+        documentIndex: 1
+
+  - it: metrics-auth ClusterRole should have tokenreview and subjectaccessreview rules
+    set:
+      controller.metrics.enabled: true
+    template: rbac/metrics-auth-role.yaml
+    documentIndex: 0
+    asserts:
+      - equal:
+          path: metadata.name
+          value: RELEASE-NAME-metrics-auth-role
+      - contains:
+          path: rules
+          content:
+            apiGroups: ["authentication.k8s.io"]
+            resources: ["tokenreviews"]
+            verbs: ["create"]
+      - contains:
+          path: rules
+          content:
+            apiGroups: ["authorization.k8s.io"]
+            resources: ["subjectaccessreviews"]
+            verbs: ["create"]
+
+  - it: metrics-auth ClusterRoleBinding should bind to controller serviceaccount
+    set:
+      controller.metrics.enabled: true
+    template: rbac/metrics-auth-role.yaml
+    documentIndex: 1
+    asserts:
+      - equal:
+          path: metadata.name
+          value: RELEASE-NAME-metrics-auth-rolebinding
+      - equal:
+          path: roleRef.kind
+          value: ClusterRole
+      - equal:
+          path: roleRef.name
+          value: RELEASE-NAME-metrics-auth-role
+      - equal:
+          path: subjects[0].kind
+          value: ServiceAccount
+      - equal:
+          path: subjects[0].name
+          value: RELEASE-NAME-controller
+      - equal:
+          path: subjects[0].namespace
+          value: NAMESPACE
+
+  - it: should render metrics-reader ClusterRole when metrics enabled
+    set:
+      controller.metrics.enabled: true
+    template: rbac/metrics-reader-role.yaml
+    asserts:
+      - hasDocuments:
+          count: 1
+      - isKind:
+          of: ClusterRole
+      - equal:
+          path: metadata.name
+          value: RELEASE-NAME-metrics-reader
+      - contains:
+          path: rules
+          content:
+            nonResourceURLs: ["/metrics"]
+            verbs: ["get"]

helm/kagent/values.yaml

@@ -222,6 +222,17 @@ controller:
     ports:
       port: 8083
       targetPort: 8083
+  metrics:
+    enabled: false
+    port: 9093
+    # -- The controller binary defaults to secure=true. Set to false for plain HTTP scraping (most common).
+    # Note: when the controller Service type is NodePort or LoadBalancer the metrics port will be externally reachable.
+    secure: false
+    serviceMonitor:
+      enabled: false
+      interval: 30s
+      scrapeTimeout: 10s
+      labels: {}
   env: []
   envFrom: []