[helm] Enable metrics reporting on helm charts

helm/README.md

@@ -93,6 +93,48 @@ Important Fluss options surfaced by the chart:
 - internal.listener.name: Which listener is used for internal communication (defaults to INTERNAL).
 - tablet-server.id: Required to be unique per TabletServer. The chart auto‑derives this from the StatefulSet pod ordinal at runtime.
 
+### Metrics and Prometheus scraping
+
+The chart can enable Fluss metrics reporters and add scrape annotations to Services.
+
+Example:
+
+```bash
+helm install fluss ./fluss-helm \
+  --set metrics.enabled=true
+```
+
+When enabled, the chart will:
+- configure `metrics.reporters` from reporter names in values
+- configure `metrics.reporter.<name>.<option>` entries from values
+- optionally add metrics scrape annotations to Fluss Services from values
+
+Values:
+
+| Key | Description |
+| --- | --- |
+| `metrics.enabled` | Enables metrics reporting and endpoint exposure. |
+| `metrics.reporters` | Map of Fluss metric reporters and their options. |
+| `metrics.annotations` | Optional map of annotations rendered on Fluss Services when metrics are enabled. |
+
+Example `values.yaml` snippet:
+
+```yaml
+metrics:
+  enabled: true
+  reporters:
+    grph:
+      port: 9020
+      host: example-localhost
+      protocol: TCP
+      interval: "60 SECONDS"
+    prometheus:
+      port: 9249
+  annotations:
+    prometheus.io/scrape: "true"
+    prometheus.io/path: "/metrics"
+    prometheus.io/port: "9249"
+```
 
 ### Zookeeper and storage
 - zookeeper.address must point to a reachable ensemble.

helm/templates/_metrics.tpl

@@ -0,0 +1,53 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+{{/*
+Render metrics reporter configuration entries.
+Expects the root context as argument.
+
+From values:
+  metrics:
+    reporters:
+      prometheus:
+        port: 9249
+
+Renders:
+  metrics.reporters: prometheus
+  metrics.reporter.prometheus.port: 9249
+
+Keys already present in configurationOverrides are not rendered.
+*/}}
+{{- define "fluss.metrics.config" -}}
+{{- $config := .Values.configurationOverrides | default dict -}}
+{{- $reporters := .Values.metrics.reporters | default dict -}}
+{{- $reporterNames := keys $reporters | sortAlpha -}}
+{{- if eq (len $reporterNames) 0 -}}
+{{- fail "metrics.reporters must contain at least one reporter when metrics.enabled is true" -}}
+{{- end -}}
+{{- if not (hasKey $config "metrics.reporters") }}
+metrics.reporters: {{ join "," $reporterNames }}
+{{- end -}}
+{{- range $name := $reporterNames -}}
+{{- range $option, $value := index $reporters $name -}}
+{{- $fullKey := printf "metrics.reporter.%s.%s" $name $option -}}
+{{- if not (hasKey $config $fullKey) }}
+{{ $fullKey }}: {{ tpl (printf "%v" $value) $ }}
+{{- end -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}

helm/templates/configmap.yaml

@@ -26,4 +26,7 @@ data:
   server.yaml: |
     {{- range $key, $val := .Values.configurationOverrides }}
     {{ $key }}: {{ tpl (printf "%v" $val) $ }}
-    {{- end }}
+    {{- end }}
+    {{- if .Values.metrics.enabled }}
+    {{- include "fluss.metrics.config" . | nindent 4 }}
+    {{- end }}

helm/templates/svc-coordinator.yaml

@@ -23,6 +23,10 @@ metadata:
   labels:
     {{- include "fluss.labels" . | nindent 4 }}
     app.kubernetes.io/component: coordinator
+  {{- if and .Values.metrics.enabled .Values.metrics.annotations }}
+  annotations:
+    {{- toYaml .Values.metrics.annotations | nindent 4 }}
+  {{- end }}
 spec:
   clusterIP: None
   type: ClusterIP

helm/templates/svc-tablet.yaml

@@ -23,6 +23,10 @@ metadata:
   labels:
     {{- include "fluss.labels" . | nindent 4 }}
     app.kubernetes.io/component: tablet
+  {{- if and .Values.metrics.enabled .Values.metrics.annotations }}
+  annotations:
+    {{- toYaml .Values.metrics.annotations | nindent 4 }}
+  {{- end }}
 spec:
   clusterIP: None
   type: ClusterIP

helm/tests/metrics_test.yaml

@@ -0,0 +1,195 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+suite: metrics-disabled-configmap
+templates:
+  - templates/configmap.yaml
+tests:
+  - it: does not add metrics reporter settings when metrics are disabled
+    asserts:
+      - notMatchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporters:\s*prometheus'
+      - notMatchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporter\.prometheus\.port:'
+---
+
+suite: metrics-enabled-configmap
+templates:
+  - templates/configmap.yaml
+tests:
+  - it: adds default prometheus reporter settings when metrics are enabled
+    set:
+      metrics.enabled: true
+    asserts:
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporters:\s*prometheus'
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporter\.prometheus\.port:\s*9249'
+---
+
+suite: metrics-enabled-configmap-custom-reporters
+templates:
+  - templates/configmap.yaml
+tests:
+  - it: renders multiple reporter options from structured metrics values
+    set:
+      metrics.enabled: true
+      metrics.reporters:
+        grph:
+          port: 9020
+          host: example-localhost
+          protocol: TCP
+          interval: "60 SECONDS"
+        prometheus:
+          port: 9249
+    asserts:
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporters:\s*grph,prometheus'
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporter\.grph\.port:\s*9020'
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporter\.grph\.host:\s*example-localhost'
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporter\.grph\.protocol:\s*TCP'
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporter\.grph\.interval:\s*60 SECONDS'
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporter\.prometheus\.port:\s*9249'
+---
+
+suite: metrics-enabled-empty-reporters-fails
+templates:
+  - templates/configmap.yaml
+tests:
+  - it: fails with clear message when reporters are empty
+    set:
+      metrics.enabled: true
+      metrics.reporters: null
+    asserts:
+      - failedTemplate:
+          errorMessage: metrics.reporters must contain at least one reporter when metrics.enabled is true
+---
+
+suite: metrics-config-overrides-precedence
+templates:
+  - templates/configmap.yaml
+tests:
+  - it: prefers configurationOverrides for reporter keys when both are set
+    set:
+      metrics.enabled: true
+      metrics.reporters:
+        prometheus:
+          port: 9249
+      configurationOverrides:
+        metrics.reporter.prometheus.port: 9300
+    asserts:
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporter\.prometheus\.port:\s*9300'
+      - notMatchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporter\.prometheus\.port:\s*9249'
+  - it: prefers configurationOverrides for metrics.reporters when both are set
+    set:
+      metrics.enabled: true
+      metrics.reporters:
+        grph:
+          port: 9020
+        prometheus:
+          port: 9249
+      configurationOverrides:
+        metrics.reporters: grph
+    asserts:
+      - matchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporters:\s*grph'
+      - notMatchRegex:
+          path: data["server.yaml"]
+          pattern: 'metrics\.reporters:\s*grph,prometheus'
+---
+
+suite: metrics-enabled-service
+templates:
+  - templates/svc-coordinator.yaml
+tests:
+  - it: renders value-driven annotations when provided
+    set:
+      metrics.enabled: true
+      metrics.annotations:
+        prometheus.io/scrape: "true"
+        prometheus.io/path: "/metrics"
+        prometheus.io/port: "9249"
+    asserts:
+      - equal:
+          path: metadata.annotations["prometheus.io/scrape"]
+          value: "true"
+      - equal:
+          path: metadata.annotations["prometheus.io/path"]
+          value: "/metrics"
+      - equal:
+          path: metadata.annotations["prometheus.io/port"]
+          value: "9249"
+---
+
+suite: metrics-enabled-statefulset
+templates:
+  - templates/sts-coordinator.yaml
+  - templates/sts-tablet.yaml
+tests:
+  - it: does not expose metrics container port for coordinator
+    set:
+      metrics.enabled: true
+    template: templates/sts-coordinator.yaml
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: metrics
+            containerPort: 9249
+  - it: does not expose metrics container port for tablet
+    set:
+      metrics.enabled: true
+    template: templates/sts-tablet.yaml
+    asserts:
+      - notContains:
+          path: spec.template.spec.containers[0].ports
+          content:
+            name: metrics
+            containerPort: 9249
+---
+
+suite: metrics-enabled-without-annotations
+templates:
+  - templates/svc-tablet.yaml
+tests:
+  - it: renders no annotations when not configured
+    set:
+      metrics.enabled: true
+    asserts:
+      - isNull:
+          path: metadata.annotations

helm/values.yaml

@@ -58,6 +58,13 @@ listeners:
   client:
     port: 9124
 
+metrics:
+  enabled: false
+  reporters:
+    prometheus:
+      port: 9249
+  annotations: {}
+
 resources: {}
   # We usually recommend not to specify default resources and to leave this as a conscious
   # choice for the user. This also increases chances charts run on environments with little

website/docs/install-deploy/deploying-with-helm.md

@@ -255,6 +255,34 @@ listeners:
     port: 9124
 ```
 
+### Metrics and Monitoring
+
+When `metrics.enabled` is `true`, the Helm chart renders metrics reporter entries into `server.yaml`:
+
+- `metrics.reporters`: comma-separated reporter names from `metrics.reporters`
+- `metrics.reporter.<name>.<option>`: one entry per reporter option in `metrics.reporters`
+
+If `metrics.annotations` is configured, these annotations are also added to Fluss Services and can be used by reporters such as Prometheus to scrape metrics endpoints.
+
+```yaml
+metrics:
+  enabled: true
+  reporters:
+    grph:
+      port: 9020
+      host: example-localhost
+      protocol: TCP
+      interval: "60 SECONDS"
+    prometheus:
+      port: 9249
+  annotations:
+    prometheus.io/scrape: "true"
+    prometheus.io/path: "/metrics"
+    prometheus.io/port: "9249"
+```
+
+If a metrics key is already provided in `configurationOverrides` (for example, `metrics.reporters` or `metrics.reporter.prometheus.port`), the chart keeps the value from `configurationOverrides`.
+
 ### Storage Configuration
 
 Configure different storage volumes for coordinator or tablet pods: