Expose the controller's /metrics endpoint through a dedicated Service

helm/kagent/templates/_helpers.tpl

@@ -132,6 +132,33 @@ Check if leader election should be enabled (more than 1 replica)
 {{- gt (.Values.controller.replicas | int) 1 -}}
 {{- end -}}
 
+{{/*
+Extract the TCP port from controller.metrics.bindAddress.
+
+Anchors the digit run to the end of the string so every Go-style
+address form the controller binary accepts is handled correctly: bare
+":port", host-qualified "host:port", and bracketed IPv6 "[::1]:port"
+all yield the trailing port. Returns "0" or "" when the binary's
+disable sentinel is in use; callers must consult
+`kagent.controller.metricsEnabled` before rendering manifests.
+*/}}
+{{- define "kagent.controller.metricsPort" -}}
+{{- regexFind "[0-9]+$" (.Values.controller.metrics.bindAddress | toString) -}}
+{{- end -}}
+
+{{/*
+Returns "1" when the controller metrics resources (Service, RBAC,
+container port, env vars) should render, empty otherwise. Honours both
+disable signals: `controller.metrics.enabled=false` and the binary's
+own `--metrics-bind-address=0` sentinel reached through `bindAddress`.
+The two are equivalent so the field name keeps faith with the binary's
+documented contract (see go/core/pkg/app/app.go).
+*/}}
+{{- define "kagent.controller.metricsEnabled" -}}
+{{- $port := include "kagent.controller.metricsPort" . -}}
+{{- if and .Values.controller.metrics.enabled $port (ne $port "0") -}}1{{- end -}}
+{{- end -}}
+
 {{/*
 PostgreSQL service name for the bundled postgres instance
 */}}

helm/kagent/templates/controller-deployment.yaml

@@ -84,6 +84,12 @@ spec:
             {{- else }}
             {{ fail "No database connection configured. Set database.postgres.url, database.postgres.urlFile, or enable database.postgres.bundled." }}
             {{- end }}
+            {{- if include "kagent.controller.metricsEnabled" . }}
+            - name: METRICS_BIND_ADDRESS
+              value: {{ .Values.controller.metrics.bindAddress | quote }}
+            - name: METRICS_SECURE
+              value: {{ .Values.controller.metrics.secureServing | quote }}
+            {{- end }}
             {{- with .Values.controller.env }}
               {{- toYaml . | nindent 12 }}
             {{- end }}
@@ -97,6 +103,11 @@ spec:
             - name: http
               containerPort: {{ .Values.controller.service.ports.targetPort }}
               protocol: TCP
+            {{- if .Values.controller.metrics.enabled }}
+            - name: metrics
+              containerPort: {{ include "kagent.controller.metricsPort" . | int }}
+              protocol: TCP
+            {{- end }}
           resources:
             {{- toYaml .Values.controller.resources | nindent 12 }}
           {{- with (.Values.controller.securityContext | default .Values.securityContext) }}

helm/kagent/templates/controller-metrics-service.yaml

@@ -0,0 +1,18 @@
+{{- if include "kagent.controller.metricsEnabled" . }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "kagent.fullname" . }}-controller-metrics
+  namespace: {{ include "kagent.namespace" . }}
+  labels:
+    {{- include "kagent.controller.labels" . | nindent 4 }}
+spec:
+  type: {{ .Values.controller.metrics.service.type }}
+  ports:
+    - name: {{ ternary "https" "http-metrics" .Values.controller.metrics.secureServing }}
+      port: {{ .Values.controller.metrics.service.port }}
+      targetPort: {{ include "kagent.controller.metricsPort" . | int }}
+      protocol: TCP
+  selector:
+    {{- include "kagent.controller.selectorLabels" . | nindent 4 }}
+{{- end }}

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

@@ -0,0 +1,21 @@
+{{- if and (include "kagent.controller.metricsEnabled" .) .Values.controller.metrics.secureServing }}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: {{ include "kagent.fullname" . }}-metrics-auth-role
+  labels:
+    {{- include "kagent.controller.labels" . | nindent 4 }}
+rules:
+  - apiGroups:
+      - authentication.k8s.io
+    resources:
+      - tokenreviews
+    verbs:
+      - create
+  - apiGroups:
+      - authorization.k8s.io
+    resources:
+      - subjectaccessreviews
+    verbs:
+      - create
+{{- end }}

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

@@ -0,0 +1,16 @@
+{{- if and (include "kagent.controller.metricsEnabled" .) .Values.controller.metrics.secureServing }}
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: {{ include "kagent.fullname" . }}-metrics-auth-rolebinding
+  labels:
+    {{- include "kagent.controller.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-clusterrole.yaml

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

helm/kagent/tests/controller-deployment_test.yaml

@@ -496,3 +496,152 @@ tests:
           path: spec.template.spec.containers[0].env
           content:
             name: POSTGRES_PASSWORD
+
+  - it: should not expose metrics container port by default
+    template: controller-deployment.yaml
+    asserts:
+      - lengthEqual:
+          path: spec.template.spec.containers[0].ports
+          count: 1
+      - notContains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: metrics
+
+  - it: should not set metrics env vars by default
+    template: controller-deployment.yaml
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_BIND_ADDRESS
+          any: true
+      - notContains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_SECURE
+          any: true
+
+  - it: should expose metrics container port when enabled
+    template: controller-deployment.yaml
+    set:
+      controller.metrics.enabled: true
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: metrics
+            containerPort: 8443
+            protocol: TCP
+
+  - it: should set metrics env vars when enabled
+    template: controller-deployment.yaml
+    set:
+      controller.metrics.enabled: true
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_BIND_ADDRESS
+            value: ":8443"
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_SECURE
+            value: "true"
+
+  - it: should reflect insecure serving in env
+    template: controller-deployment.yaml
+    set:
+      controller.metrics.enabled: true
+      controller.metrics.secureServing: false
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_SECURE
+            value: "false"
+
+  - it: should derive metrics container port from bindAddress
+    template: controller-deployment.yaml
+    set:
+      controller.metrics.enabled: true
+      controller.metrics.bindAddress: ":9443"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_BIND_ADDRESS
+            value: ":9443"
+      - contains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: metrics
+            containerPort: 9443
+            protocol: TCP
+
+  - it: should derive metrics container port from a host-qualified bindAddress
+    template: controller-deployment.yaml
+    set:
+      controller.metrics.enabled: true
+      controller.metrics.bindAddress: "127.0.0.1:9443"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: metrics
+            containerPort: 9443
+            protocol: TCP
+
+  - it: should derive metrics container port from a bracketed IPv6 bindAddress
+    template: controller-deployment.yaml
+    set:
+      controller.metrics.enabled: true
+      controller.metrics.bindAddress: "[::1]:9443"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: metrics
+            containerPort: 9443
+            protocol: TCP
+
+  - it: should not gain metrics wiring when bindAddress disables metrics
+    template: controller-deployment.yaml
+    set:
+      controller.metrics.enabled: true
+      controller.metrics.bindAddress: "0"
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_BIND_ADDRESS
+          any: true
+      - notContains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_SECURE
+          any: true
+      - notContains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: metrics
+
+  - it: should let controller.env override the chart-supplied metrics env
+    template: controller-deployment.yaml
+    set:
+      controller.metrics.enabled: true
+      controller.env:
+        - name: METRICS_BIND_ADDRESS
+          value: "0"
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_BIND_ADDRESS
+            value: ":8443"
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: METRICS_BIND_ADDRESS
+            value: "0"