Merge pull request #34 from upcloud-tools/helm/observability

feat: add metrics support to helm chart and the driver

Author: aardbol

AGENTS.md

@@ -8,3 +8,13 @@
 - **Security policy**: Defined in `SECURITY.md` at the repo root. Direct reporters to GitHub's Private vulnerability reporting tool.
 - **Code scanning**: Use `github/codeql-action` (latest v3.x, pinned by SHA) with `go` language matrix.
 - **Dependabot**: Config in `.github/dependabot.yml` tracks `gomod`, `github-actions`, and `docker` ecosystems daily.
+- **Versioning and changelogs**:
+  - Two separate changelogs, never mix: `/CHANGELOG.md` for app (Go code), `deploy/helm/CHANGELOG.md` for Helm chart (templates, values, schema)
+  - App version format `vX.Y.Z` — tracked in `deploy/helm/Chart.yaml` (`appVersion`) and root `CHANGELOG.md`
+  - Chart version format `X.Y.Z` — tracked in `deploy/helm/Chart.yaml` (`version`) and Helm `CHANGELOG.md`
+  - When Go code changes: bump `appVersion`, update root `CHANGELOG.md`
+  - When Helm template/values change: bump chart `version`, update Helm `CHANGELOG.md`
+  - `artifacthub.io/changes` in `Chart.yaml`: replace with the changes for the current version only, not cumulative across versions
+- **Helm chart conventions**:
+  - `# @schema` annotations inline on same line as value (Traefik style): `fieldName: value  # @schema type:[integer, null]`
+  - Run helm unit tests via `make helm-unittest`

CHANGELOG.md

@@ -2,7 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [2.6.0] - 2026-06-20
+
+### Added
+- metrics: Prometheus metrics server on `--metrics-address` (default `:8090`) with go/process collectors at `/metrics`
+- metrics: CSI gRPC operation counters and histograms — `csi_plugin_operations_total`, `csi_plugin_operation_duration_seconds`, `csi_plugin_operations_in_flight`
+- metrics: instrumented UpCloud API client wrapper — `upcloud_api_requests_total`, `upcloud_api_request_duration_seconds`
 
 ## [2.5.1] - 2026-06-20
 

README.md

@@ -32,6 +32,16 @@ validation. Full E2E coverage for snapshot creation and PVC restore from snapsho
 Multistage Containerfile produces an Alpine-based image with only the packages required for block storage operations
 (`xfsprogs`, `e2fsprogs`, `cloud-utils-growpart`, etc.) — no superfluous binaries.
 
+### Prometheus Metrics
+The driver exposes Prometheus metrics at `:8090/metrics` (configurable via `--metrics-address`). Includes:
+
+- **CSI gRPC operations** — `csi_plugin_operations_total` (by method + status), `csi_plugin_operation_duration_seconds` (histogram), `csi_plugin_operations_in_flight` (gauge)
+- **UpCloud API calls** — `upcloud_api_requests_total` (by method + result), `upcloud_api_request_duration_seconds` (histogram)
+- **Go runtime** — goroutines, GC, memory, CPU, and file descriptor metrics
+
+The Helm chart provides a ClusterIP metrics Service and optional `ServiceMonitor` / `PrometheusRule` resources for
+prometheus-operator. Controller sidecars expose `--http-endpoint` on ports 8080–8083.
+
 ## Repository Security
 
 This repository uses the following security and supply-chain measures:

deploy/helm/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Helm chart changelog
 
+## [1.5.0] - 2026-06-20
+
+### Changed
+- App version bumped to `v2.6.0`
+
+### Added
+- `metrics` block with configurable ServiceMonitor and PrometheusRule support — controller sidecars now expose `--http-endpoint` on standard ports (8080-8083) and a ClusterIP metrics Service is created by default
+- Driver metrics port (`csi-metrics:8090`) on controller and node, wired into metrics Service and ServiceMonitor
+
 ## [1.4.0] - 2026-06-20
 
 ### Added

deploy/helm/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: upcloud-csi
 description: CSI driver for UpCloud block storage
 type: application
-version: "1.4.0"
-appVersion: "v2.5.1"
+version: "1.5.0"
+appVersion: "v2.6.0"
 kubeVersion: ">=1.21.0"
 keywords:
   - csi
@@ -25,6 +25,6 @@ annotations:
     - name: Support
       url: https://github.com/upcloud-tools/upcloud-csi/issues
   artifacthub.io/changes: |
-    - "Add extraObjects support"
-    - "Add imagePullSecrets per component"
-    - "Make updateStrategy, lifecycle, topology, and other pod spec fields configurable"
+    - "Add metrics Service, ServiceMonitor, and PrometheusRule support"
+    - "Driver plugin exposes Prometheus metrics via --metrics-address flag"
+    - "Driver metrics port on controller and node, wired into Service and ServiceMonitor"

deploy/helm/templates/controller-statefulset.yaml

@@ -92,6 +92,9 @@ spec:
             - "--csi-address=$(ADDRESS)"
             - "--v={{ .Values.controller.logLevel | default .Values.logLevel }}"
             - "--timeout=600s"
+            {{- if .Values.metrics.enabled }}
+            - "--http-endpoint=:8080"
+            {{- end }}
           env:
             - name: ADDRESS
               value: /var/lib/csi/sockets/pluginproxy/csi.sock
@@ -106,13 +109,22 @@ spec:
           resources:
             {{- tpl (toYaml .) $ | nindent 12 }}
           {{- end }}
+          {{- if .Values.metrics.enabled }}
+          ports:
+            - containerPort: 8080
+              name: prov-metrics
+              protocol: TCP
+          {{- end }}
         - name: csi-attacher
           image: "{{ .Values.controller.sidecars.csiAttacher.repository }}:{{ .Values.controller.sidecars.csiAttacher.tag }}"
           imagePullPolicy: {{ .Values.controller.sidecars.csiAttacher.pullPolicy }}
           args:
             - "--v={{ .Values.controller.logLevel | default .Values.logLevel }}"
             - "--csi-address=$(ADDRESS)"
             - "--timeout=600s"
+            {{- if .Values.metrics.enabled }}
+            - "--http-endpoint=:8081"
+            {{- end }}
           env:
             - name: ADDRESS
               value: /var/lib/csi/sockets/pluginproxy/csi.sock
@@ -127,6 +139,12 @@ spec:
           resources:
             {{- tpl (toYaml .) $ | nindent 12 }}
           {{- end }}
+          {{- if .Values.metrics.enabled }}
+          ports:
+            - containerPort: 8081
+              name: att-metrics
+              protocol: TCP
+          {{- end }}
         - name: csi-resizer
           image: "{{ .Values.controller.sidecars.csiResizer.repository }}:{{ .Values.controller.sidecars.csiResizer.tag }}"
           imagePullPolicy: {{ .Values.controller.sidecars.csiResizer.pullPolicy }}
@@ -135,6 +153,9 @@ spec:
             - "--timeout=600s"
             - "--csi-address=$(ADDRESS)"
             - "--handle-volume-inuse-error=true"
+            {{- if .Values.metrics.enabled }}
+            - "--http-endpoint=:8082"
+            {{- end }}
           env:
             - name: ADDRESS
               value: /var/lib/csi/sockets/pluginproxy/csi.sock
@@ -149,6 +170,12 @@ spec:
           resources:
             {{- tpl (toYaml .) $ | nindent 12 }}
           {{- end }}
+          {{- if .Values.metrics.enabled }}
+          ports:
+            - containerPort: 8082
+              name: res-metrics
+              protocol: TCP
+          {{- end }}
         - name: csi-snapshotter
           image: "{{ .Values.controller.sidecars.csiSnapshotter.repository }}:{{ .Values.controller.sidecars.csiSnapshotter.tag }}"
           imagePullPolicy: {{ .Values.controller.sidecars.csiSnapshotter.pullPolicy }}
@@ -157,6 +184,9 @@ spec:
             - "--v={{ .Values.controller.logLevel | default .Values.logLevel }}"
             - "--timeout=600s"
             - "--leader-election=false"
+            {{- if .Values.metrics.enabled }}
+            - "--http-endpoint=:8083"
+            {{- end }}
           env:
             - name: ADDRESS
               value: /var/lib/csi/sockets/pluginproxy/csi.sock
@@ -171,6 +201,12 @@ spec:
           resources:
             {{- tpl (toYaml .) $ | nindent 12 }}
           {{- end }}
+          {{- if .Values.metrics.enabled }}
+          ports:
+            - containerPort: 8083
+              name: snap-metrics
+              protocol: TCP
+          {{- end }}
         - name: csi-upcloud-plugin
           image: {{ include "upcloud-csi.driverImage" . }}
           imagePullPolicy: {{ .Values.image.pullPolicy }}
@@ -179,6 +215,9 @@ spec:
             - "--nodehost=$(NODE_ID)"
             - "--mode=monolith"
             - "--address=tcp://0.0.0.0:13071"
+            {{- if .Values.metrics.enabled }}
+            - "--metrics-address=tcp://0.0.0.0:8090"
+            {{- end }}
           env:
             - name: CSI_ENDPOINT
               value: "unix:///var/lib/csi/sockets/pluginproxy/csi.sock"
@@ -208,6 +247,11 @@ spec:
             - containerPort: 13071
               name: health
               protocol: TCP
+            {{- if .Values.metrics.enabled }}
+            - containerPort: 8090
+              name: csi-metrics
+              protocol: TCP
+            {{- end }}
           livenessProbe:
             httpGet:
               path: /health

deploy/helm/templates/node-daemonset.yaml

@@ -121,6 +121,9 @@ spec:
             - "--nodehost=$(NODE_ID)"
             - "--mode=monolith"
             - "--address=tcp://0.0.0.0:13071"
+            {{- if .Values.metrics.enabled }}
+            - "--metrics-address=tcp://0.0.0.0:8090"
+            {{- end }}
           env:
             - name: CSI_ENDPOINT
               value: unix:///csi/csi.sock
@@ -150,6 +153,11 @@ spec:
             - containerPort: 13071
               name: health
               protocol: TCP
+            {{- if .Values.metrics.enabled }}
+            - containerPort: 8090
+              name: csi-metrics
+              protocol: TCP
+            {{- end }}
           livenessProbe:
             httpGet:
               path: /health

deploy/helm/templates/prometheusrule.yaml

@@ -0,0 +1,17 @@
+{{- if and .Values.metrics.enabled .Values.metrics.prometheusRule.enabled }}
+apiVersion: monitoring.coreos.com/v1
+kind: PrometheusRule
+metadata:
+  name: {{ include "upcloud-csi.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "upcloud-csi.labels" . | nindent 4 }}
+    {{- with .Values.metrics.prometheusRule.additionalLabels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  groups:
+    - name: upcloud-csi
+      rules:
+        {{- toYaml .Values.metrics.prometheusRule.rules | nindent 8 }}
+{{- end }}

deploy/helm/templates/service-metrics.yaml

@@ -0,0 +1,36 @@
+{{- if .Values.metrics.enabled }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "upcloud-csi.fullname" . }}-metrics
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "upcloud-csi.labels" . | nindent 4 }}
+    app.kubernetes.io/component: metrics
+spec:
+  type: ClusterIP
+  ports:
+    - name: prov-metrics
+      port: 8080
+      targetPort: 8080
+      protocol: TCP
+    - name: att-metrics
+      port: 8081
+      targetPort: 8081
+      protocol: TCP
+    - name: res-metrics
+      port: 8082
+      targetPort: 8082
+      protocol: TCP
+    - name: snap-metrics
+      port: 8083
+      targetPort: 8083
+      protocol: TCP
+    - name: csi-metrics
+      port: 8090
+      targetPort: 8090
+      protocol: TCP
+  selector:
+    {{- include "upcloud-csi.selectorLabels" . | nindent 4 }}
+    app: {{ include "upcloud-csi.fullname" . }}-controller
+{{- end }}

deploy/helm/templates/servicemonitor.yaml

@@ -0,0 +1,31 @@
+{{- if and .Values.metrics.enabled .Values.metrics.serviceMonitor.enabled }}
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: {{ include "upcloud-csi.fullname" . }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    {{- include "upcloud-csi.labels" . | nindent 4 }}
+    {{- with .Values.metrics.serviceMonitor.additionalLabels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+spec:
+  endpoints:
+    - port: prov-metrics
+      interval: {{ .Values.metrics.serviceMonitor.interval }}
+    - port: att-metrics
+      interval: {{ .Values.metrics.serviceMonitor.interval }}
+    - port: res-metrics
+      interval: {{ .Values.metrics.serviceMonitor.interval }}
+    - port: snap-metrics
+      interval: {{ .Values.metrics.serviceMonitor.interval }}
+    - port: csi-metrics
+      interval: {{ .Values.metrics.serviceMonitor.interval }}
+  namespaceSelector:
+    matchNames:
+      - {{ .Release.Namespace }}
+  selector:
+    matchLabels:
+      {{- include "upcloud-csi.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: metrics
+{{- end }}