From 3a9ad8f9025ea4cdeed782be7cfb6248a16f37ef Mon Sep 17 00:00:00 2001
From: morazow <m.orazow@gmail.com>
Date: Fri, 13 Feb 2026 16:47:54 +0100
Subject: [PATCH 1/6] [helm] Enable metrics reporting in helm charts

---
 helm/README.md                                |  42 ++++
 helm/templates/_metrics.tpl                   |  53 +++++
 helm/templates/configmap.yaml                 |   5 +-
 helm/templates/svc-coordinator.yaml           |   4 +
 helm/templates/svc-tablet.yaml                |   4 +
 helm/tests/metrics_test.yaml                  | 195 ++++++++++++++++++
 helm/values.yaml                              |   7 +
 .../install-deploy/deploying-with-helm.md     |  28 +++
 8 files changed, 337 insertions(+), 1 deletion(-)
 create mode 100644 helm/templates/_metrics.tpl
 create mode 100644 helm/tests/metrics_test.yaml

diff --git a/helm/README.md b/helm/README.md
index cd0985f6e4..26b0729327 100644
--- a/helm/README.md
+++ b/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.
diff --git a/helm/templates/_metrics.tpl b/helm/templates/_metrics.tpl
new file mode 100644
index 0000000000..d015f16021
--- /dev/null
+++ b/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 -}}
diff --git a/helm/templates/configmap.yaml b/helm/templates/configmap.yaml
index b0e868c90e..7b3560d64a 100644
--- a/helm/templates/configmap.yaml
+++ b/helm/templates/configmap.yaml
@@ -26,4 +26,7 @@ data:
   server.yaml: |
     {{- range $key, $val := .Values.configurationOverrides }}
     {{ $key }}: {{ tpl (printf "%v" $val) $ }}
-    {{- end }}
\ No newline at end of file
+    {{- end }}
+    {{- if .Values.metrics.enabled }}
+    {{- include "fluss.metrics.config" . | nindent 4 }}
+    {{- end }}
diff --git a/helm/templates/svc-coordinator.yaml b/helm/templates/svc-coordinator.yaml
index 64a622ae28..2f29f71de6 100644
--- a/helm/templates/svc-coordinator.yaml
+++ b/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
diff --git a/helm/templates/svc-tablet.yaml b/helm/templates/svc-tablet.yaml
index 517653e87f..d4d3bd212a 100644
--- a/helm/templates/svc-tablet.yaml
+++ b/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
diff --git a/helm/tests/metrics_test.yaml b/helm/tests/metrics_test.yaml
new file mode 100644
index 0000000000..0a4c83ce8a
--- /dev/null
+++ b/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
diff --git a/helm/values.yaml b/helm/values.yaml
index db5d3fc2a9..fc53aba553 100644
--- a/helm/values.yaml
+++ b/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
diff --git a/website/docs/install-deploy/deploying-with-helm.md b/website/docs/install-deploy/deploying-with-helm.md
index 9bdbf414e5..f0496627ef 100644
--- a/website/docs/install-deploy/deploying-with-helm.md
+++ b/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:

From fc286b2afa51a51a58f7622a87ae7ee1a0849f7d Mon Sep 17 00:00:00 2001
From: morazow <m.orazow@gmail.com>
Date: Mon, 2 Mar 2026 19:00:20 +0100
Subject: [PATCH 2/6] Address review suggestions

---
 helm/templates/_metrics.tpl                      | 16 +++++++++++++++-
 helm/templates/configmap.yaml                    |  2 --
 helm/templates/svc-coordinator.yaml              |  4 +---
 helm/templates/svc-tablet.yaml                   |  4 +---
 helm/tests/metrics_test.yaml                     | 11 ++++++++++-
 .../docs/install-deploy/deploying-with-helm.md   |  7 ++-----
 6 files changed, 29 insertions(+), 15 deletions(-)

diff --git a/helm/templates/_metrics.tpl b/helm/templates/_metrics.tpl
index d015f16021..f4f29e7643 100644
--- a/helm/templates/_metrics.tpl
+++ b/helm/templates/_metrics.tpl
@@ -17,7 +17,7 @@
 #
 
 {{/*
-Render metrics reporter configuration entries.
+Renders metrics reporter configuration entries.
 Expects the root context as argument.
 
 From values:
@@ -33,6 +33,7 @@ Renders:
 Keys already present in configurationOverrides are not rendered.
 */}}
 {{- define "fluss.metrics.config" -}}
+{{- if .Values.metrics.enabled -}}
 {{- $config := .Values.configurationOverrides | default dict -}}
 {{- $reporters := .Values.metrics.reporters | default dict -}}
 {{- $reporterNames := keys $reporters | sortAlpha -}}
@@ -51,3 +52,16 @@ metrics.reporters: {{ join "," $reporterNames }}
 {{- end -}}
 {{- end -}}
 {{- end -}}
+{{- end -}}
+
+{{/*
+Renders metrics annotations entries as YAML format.
+Expects the root context as argument.
+*/}}
+{{- define "fluss.metrics.annotations" -}}
+{{- if .Values.metrics.enabled -}}
+{{- with .Values.metrics.annotations -}}
+{{- toYaml . -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
diff --git a/helm/templates/configmap.yaml b/helm/templates/configmap.yaml
index 7b3560d64a..a3d4684ca8 100644
--- a/helm/templates/configmap.yaml
+++ b/helm/templates/configmap.yaml
@@ -27,6 +27,4 @@ data:
     {{- range $key, $val := .Values.configurationOverrides }}
     {{ $key }}: {{ tpl (printf "%v" $val) $ }}
     {{- end }}
-    {{- if .Values.metrics.enabled }}
     {{- include "fluss.metrics.config" . | nindent 4 }}
-    {{- end }}
diff --git a/helm/templates/svc-coordinator.yaml b/helm/templates/svc-coordinator.yaml
index 2f29f71de6..7c6e2e3ce3 100644
--- a/helm/templates/svc-coordinator.yaml
+++ b/helm/templates/svc-coordinator.yaml
@@ -23,10 +23,8 @@ 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 }}
+    {{- include "fluss.metrics.annotations" . | nindent 4 }}
 spec:
   clusterIP: None
   type: ClusterIP
diff --git a/helm/templates/svc-tablet.yaml b/helm/templates/svc-tablet.yaml
index d4d3bd212a..c29e3941fd 100644
--- a/helm/templates/svc-tablet.yaml
+++ b/helm/templates/svc-tablet.yaml
@@ -23,10 +23,8 @@ 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 }}
+    {{- include "fluss.metrics.annotations" . | nindent 4 }}
 spec:
   clusterIP: None
   type: ClusterIP
diff --git a/helm/tests/metrics_test.yaml b/helm/tests/metrics_test.yaml
index 0a4c83ce8a..9e07b8f63a 100644
--- a/helm/tests/metrics_test.yaml
+++ b/helm/tests/metrics_test.yaml
@@ -137,6 +137,14 @@ suite: metrics-enabled-service
 templates:
   - templates/svc-coordinator.yaml
 tests:
+  - it: does not render metrics annotations when metrics are disabled
+    set:
+      metrics.annotations:
+        prometheus.io/scrape: "true"
+    asserts:
+      - equal:
+          path: metadata.annotations
+          value: null
   - it: renders value-driven annotations when provided
     set:
       metrics.enabled: true
@@ -191,5 +199,6 @@ tests:
     set:
       metrics.enabled: true
     asserts:
-      - isNull:
+      - equal:
           path: metadata.annotations
+          value: null
diff --git a/website/docs/install-deploy/deploying-with-helm.md b/website/docs/install-deploy/deploying-with-helm.md
index f0496627ef..630f16985f 100644
--- a/website/docs/install-deploy/deploying-with-helm.md
+++ b/website/docs/install-deploy/deploying-with-helm.md
@@ -268,11 +268,8 @@ If `metrics.annotations` is configured, these annotations are also added to Flus
 metrics:
   enabled: true
   reporters:
-    grph:
-      port: 9020
-      host: example-localhost
-      protocol: TCP
-      interval: "60 SECONDS"
+    jmx:
+      port: 9250-9260
     prometheus:
       port: 9249
   annotations:

From 16c59dfa9f935786311ddff784555a2e39d9c2be Mon Sep 17 00:00:00 2001
From: morazow <m.orazow@gmail.com>
Date: Wed, 4 Mar 2026 14:19:35 +0100
Subject: [PATCH 3/6] Address review suggestions: introduce metrics service

---
 helm/README.md                                | 27 +++---
 helm/templates/svc-coordinator.yaml           |  2 -
 helm/templates/svc-metrics-coordinator.yaml   | 43 +++++++++
 helm/templates/svc-metrics-tablet.yaml        | 43 +++++++++
 helm/templates/svc-tablet.yaml                |  2 -
 helm/tests/metrics_test.yaml                  | 92 ++++++++++++++-----
 helm/values.yaml                              |  3 +
 .../install-deploy/deploying-with-helm.md     | 25 ++++-
 8 files changed, 198 insertions(+), 39 deletions(-)
 create mode 100644 helm/templates/svc-metrics-coordinator.yaml
 create mode 100644 helm/templates/svc-metrics-tablet.yaml

diff --git a/helm/README.md b/helm/README.md
index 26b0729327..b529e4f9ee 100644
--- a/helm/README.md
+++ b/helm/README.md
@@ -22,7 +22,7 @@ This chart deploys an Apache Fluss cluster on Kubernetes, following Helm best pr
 It requires a Zookeeper ensemble to be running in the same Kubernetes cluster. In future releases, we may add support for an embedded Zookeeper cluster.
 
 
-## Development environment 
+## Development environment
 
 | component                                                                      | version |
 | ------------------------------------------------------------------------------ | ------- |
@@ -33,7 +33,7 @@ It requires a Zookeeper ensemble to be running in the same Kubernetes cluster. I
 | [Apache Fluss](https://fluss.apache.org/docs/)                                 | v0.10.0-incubating  |
 
 
-## Image requirements 
+## Image requirements
 
 A container image for Fluss is available on DockerHub as `fluss/fluss`. You can use it directly or build your own from this repo. To use your own image you need to build the project with [Maven](https://fluss.apache.org/community/dev/building/) and build it with Docker.
 
@@ -93,9 +93,9 @@ 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
+### Metrics and Prometheus Scraping
 
-The chart can enable Fluss metrics reporters and add scrape annotations to Services.
+The chart can enable Fluss metrics reporters and create dedicated metrics services for `coordinator` and `tablet` components.
 
 Example:
 
@@ -107,7 +107,9 @@ helm install fluss ./fluss-helm \
 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
+- create separate metrics services exposing the Prometheus reporter port
+- optionally add metrics scrape annotations to metrics services from values
+- optionally add custom labels to metrics services for `ServiceMonitor` selectors
 
 Values:
 
@@ -115,7 +117,9 @@ Values:
 | --- | --- |
 | `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. |
+| `metrics.service.portName` | Named port exposed by metrics services (usually used by ServiceMonitor endpoint `port`). |
+| `metrics.service.labels` | Optional labels rendered on metrics services (usually used by ServiceMonitor selectors). |
+| `metrics.annotations` | Optional map of annotations rendered on metrics services when metrics are enabled. |
 
 Example `values.yaml` snippet:
 
@@ -123,13 +127,14 @@ Example `values.yaml` snippet:
 metrics:
   enabled: true
   reporters:
-    grph:
-      port: 9020
-      host: example-localhost
-      protocol: TCP
-      interval: "60 SECONDS"
+    jmx:
+      port: 9250-9260
     prometheus:
       port: 9249
+  service:
+    portName: metrics
+    labels:
+      monitoring: enabled
   annotations:
     prometheus.io/scrape: "true"
     prometheus.io/path: "/metrics"
diff --git a/helm/templates/svc-coordinator.yaml b/helm/templates/svc-coordinator.yaml
index 7c6e2e3ce3..64a622ae28 100644
--- a/helm/templates/svc-coordinator.yaml
+++ b/helm/templates/svc-coordinator.yaml
@@ -23,8 +23,6 @@ metadata:
   labels:
     {{- include "fluss.labels" . | nindent 4 }}
     app.kubernetes.io/component: coordinator
-  annotations:
-    {{- include "fluss.metrics.annotations" . | nindent 4 }}
 spec:
   clusterIP: None
   type: ClusterIP
diff --git a/helm/templates/svc-metrics-coordinator.yaml b/helm/templates/svc-metrics-coordinator.yaml
new file mode 100644
index 0000000000..bdb2e4221c
--- /dev/null
+++ b/helm/templates/svc-metrics-coordinator.yaml
@@ -0,0 +1,43 @@
+#
+# 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.
+#
+
+{{- if .Values.metrics.enabled }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: coordinator-server-metrics-hs
+  labels:
+    {{- include "fluss.labels" . | nindent 4 }}
+    app.kubernetes.io/component: coordinator
+    {{- with .Values.metrics.service.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+  annotations:
+    {{- include "fluss.metrics.annotations" . | nindent 4 }}
+spec:
+  clusterIP: None
+  type: ClusterIP
+  ports:
+    - name: {{ default "metrics" .Values.metrics.service.portName }}
+      protocol: TCP
+      port: {{ default 9249 .Values.metrics.reporters.prometheus.port }}
+      targetPort: {{ default 9249 .Values.metrics.reporters.prometheus.port }}
+  selector:
+    {{- include "fluss.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: coordinator
+{{- end }}
diff --git a/helm/templates/svc-metrics-tablet.yaml b/helm/templates/svc-metrics-tablet.yaml
new file mode 100644
index 0000000000..1d8f434b72
--- /dev/null
+++ b/helm/templates/svc-metrics-tablet.yaml
@@ -0,0 +1,43 @@
+#
+# 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.
+#
+
+{{- if .Values.metrics.enabled }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: tablet-server-metrics-hs
+  labels:
+    {{- include "fluss.labels" . | nindent 4 }}
+    app.kubernetes.io/component: tablet
+    {{- with .Values.metrics.service.labels }}
+    {{- toYaml . | nindent 4 }}
+    {{- end }}
+  annotations:
+    {{- include "fluss.metrics.annotations" . | nindent 4 }}
+spec:
+  clusterIP: None
+  type: ClusterIP
+  ports:
+    - name: {{ default "metrics" .Values.metrics.service.portName }}
+      protocol: TCP
+      port: {{ default 9249 .Values.metrics.reporters.prometheus.port }}
+      targetPort: {{ default 9249 .Values.metrics.reporters.prometheus.port }}
+  selector:
+    {{- include "fluss.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: tablet
+{{- end }}
diff --git a/helm/templates/svc-tablet.yaml b/helm/templates/svc-tablet.yaml
index c29e3941fd..517653e87f 100644
--- a/helm/templates/svc-tablet.yaml
+++ b/helm/templates/svc-tablet.yaml
@@ -23,8 +23,6 @@ metadata:
   labels:
     {{- include "fluss.labels" . | nindent 4 }}
     app.kubernetes.io/component: tablet
-  annotations:
-    {{- include "fluss.metrics.annotations" . | nindent 4 }}
 spec:
   clusterIP: None
   type: ClusterIP
diff --git a/helm/tests/metrics_test.yaml b/helm/tests/metrics_test.yaml
index 9e07b8f63a..052ebd5848 100644
--- a/helm/tests/metrics_test.yaml
+++ b/helm/tests/metrics_test.yaml
@@ -133,19 +133,50 @@ tests:
           pattern: 'metrics\.reporters:\s*grph,prometheus'
 ---
 
-suite: metrics-enabled-service
+suite: metrics-service-disabled
 templates:
-  - templates/svc-coordinator.yaml
+  - templates/svc-metrics-coordinator.yaml
 tests:
-  - it: does not render metrics annotations when metrics are disabled
+  - it: does not render coordinator metrics service when metrics are disabled
+    asserts:
+      - hasDocuments:
+          count: 0
+---
+
+suite: metrics-service-enabled
+templates:
+  - templates/svc-metrics-coordinator.yaml
+tests:
+  - it: renders coordinator metrics service with named metrics port
     set:
-      metrics.annotations:
-        prometheus.io/scrape: "true"
+      metrics.enabled: true
     asserts:
       - equal:
-          path: metadata.annotations
-          value: null
-  - it: renders value-driven annotations when provided
+          path: metadata.name
+          value: coordinator-server-metrics-hs
+      - equal:
+          path: spec.ports[0].name
+          value: metrics
+      - equal:
+          path: spec.ports[0].port
+          value: 9249
+      - equal:
+          path: spec.clusterIP
+          value: None
+  - it: renders custom port name and service labels for ServiceMonitor selectors
+    set:
+      metrics.enabled: true
+      metrics.service.portName: fluss-metrics
+      metrics.service.labels:
+        monitoring: enabled
+    asserts:
+      - equal:
+          path: spec.ports[0].name
+          value: fluss-metrics
+      - equal:
+          path: metadata.labels.monitoring
+          value: enabled
+  - it: renders value-driven annotations on metrics service when provided
     set:
       metrics.enabled: true
       metrics.annotations:
@@ -162,6 +193,38 @@ tests:
       - equal:
           path: metadata.annotations["prometheus.io/port"]
           value: "9249"
+  - it: renders no annotations when not configured
+    set:
+      metrics.enabled: true
+    asserts:
+      - equal:
+          path: metadata.annotations
+          value: null
+---
+
+suite: pod-service-separation
+templates:
+  - templates/svc-coordinator.yaml
+  - templates/svc-tablet.yaml
+tests:
+  - it: keeps coordinator pod service without metrics annotations
+    set:
+      metrics.enabled: true
+      metrics.annotations:
+        prometheus.io/scrape: "true"
+    template: templates/svc-coordinator.yaml
+    asserts:
+      - notExists:
+          path: metadata.annotations
+  - it: keeps tablet pod service without metrics annotations
+    set:
+      metrics.enabled: true
+      metrics.annotations:
+        prometheus.io/scrape: "true"
+    template: templates/svc-tablet.yaml
+    asserts:
+      - notExists:
+          path: metadata.annotations
 ---
 
 suite: metrics-enabled-statefulset
@@ -189,16 +252,3 @@ tests:
           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:
-      - equal:
-          path: metadata.annotations
-          value: null
diff --git a/helm/values.yaml b/helm/values.yaml
index fc53aba553..f3fccfa1cf 100644
--- a/helm/values.yaml
+++ b/helm/values.yaml
@@ -63,6 +63,9 @@ metrics:
   reporters:
     prometheus:
       port: 9249
+  service:
+    portName: metrics
+    labels: {}
   annotations: {}
 
 resources: {}
diff --git a/website/docs/install-deploy/deploying-with-helm.md b/website/docs/install-deploy/deploying-with-helm.md
index 630f16985f..b7ace52695 100644
--- a/website/docs/install-deploy/deploying-with-helm.md
+++ b/website/docs/install-deploy/deploying-with-helm.md
@@ -139,7 +139,7 @@ The Fluss Helm chart deploys the following Kubernetes resources:
 - **CoordinatorServer**: 1x StatefulSet with Headless Service for cluster coordination
 - **TabletServer**: 3x StatefulSet with Headless Service for data storage and processing
 - **ConfigMap**: Configuration management for `server.yaml` settings
-- **Services**: Headless services providing stable pod DNS names
+- **Services**: Headless services for pod communication, plus optional dedicated headless metrics services when metrics are enabled
 
 ### Step 3: Verify Installation
 
@@ -183,6 +183,16 @@ The following table lists the configurable parameters of the Fluss chart and the
 | `listeners.internal.port` | Internal communication port | `9123` |
 | `listeners.client.port` | Client port (intra-cluster) | `9124` |
 
+### Metrics Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `metrics.enabled` | Enables metrics reporter configuration and dedicated metrics services | `false` |
+| `metrics.reporters` | Map of Fluss metric reporters and reporter options | `{ prometheus: { port: 9249 } }` |
+| `metrics.service.portName` | Named port exposed on metrics services (used by ServiceMonitor endpoint `port`) | `metrics` |
+| `metrics.service.labels` | Additional labels added to metrics services for ServiceMonitor selectors | `{}` |
+| `metrics.annotations` | Optional annotations added to metrics services (for annotation-based scraping) | `{}` |
+
 ### Fluss Configuration Overrides
 
 | Parameter | Description | Default |
@@ -257,12 +267,17 @@ listeners:
 
 ### Metrics and Monitoring
 
-When `metrics.enabled` is `true`, the Helm chart renders metrics reporter entries into `server.yaml`:
+When `metrics.enabled` is `true`, the Helm chart does the following:
 
 - `metrics.reporters`: comma-separated reporter names from `metrics.reporters`
 - `metrics.reporter.<name>.<option>`: one entry per reporter option in `metrics.reporters`
+- Creates dedicated metrics services:
+  - `coordinator-server-metrics-hs`
+  - `tablet-server-metrics-hs`
+- Exposes the Prometheus reporter port as a named service port (`metrics.service.portName`)
+- Adds optional labels from `metrics.service.labels` for ServiceMonitor selection
 
-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.
+If `metrics.annotations` is configured, these annotations are added to the dedicated metrics services and can be used for annotation based scraping.
 
 ```yaml
 metrics:
@@ -272,6 +287,10 @@ metrics:
       port: 9250-9260
     prometheus:
       port: 9249
+  service:
+    portName: metrics
+    labels:
+      monitoring: enabled
   annotations:
     prometheus.io/scrape: "true"
     prometheus.io/path: "/metrics"

From 266165b11522fe7756478b93c6b17905aa633ba2 Mon Sep 17 00:00:00 2001
From: Muhammet Orazov <916295+morazow@users.noreply.github.com>
Date: Fri, 6 Mar 2026 10:21:20 +0100
Subject: [PATCH 4/6] Apply suggestions from code review

Co-authored-by: Lorenzo Affetti <lorenzo.affetti@gmail.com>
---
 helm/templates/svc-metrics-coordinator.yaml        | 2 +-
 website/docs/install-deploy/deploying-with-helm.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/helm/templates/svc-metrics-coordinator.yaml b/helm/templates/svc-metrics-coordinator.yaml
index bdb2e4221c..c5d6cf4da8 100644
--- a/helm/templates/svc-metrics-coordinator.yaml
+++ b/helm/templates/svc-metrics-coordinator.yaml
@@ -20,7 +20,7 @@
 apiVersion: v1
 kind: Service
 metadata:
-  name: coordinator-server-metrics-hs
+  name: {{ .Release.Name }}-coordinator-server-metrics-hs
   labels:
     {{- include "fluss.labels" . | nindent 4 }}
     app.kubernetes.io/component: coordinator
diff --git a/website/docs/install-deploy/deploying-with-helm.md b/website/docs/install-deploy/deploying-with-helm.md
index b7ace52695..b6efb2be7a 100644
--- a/website/docs/install-deploy/deploying-with-helm.md
+++ b/website/docs/install-deploy/deploying-with-helm.md
@@ -139,7 +139,7 @@ The Fluss Helm chart deploys the following Kubernetes resources:
 - **CoordinatorServer**: 1x StatefulSet with Headless Service for cluster coordination
 - **TabletServer**: 3x StatefulSet with Headless Service for data storage and processing
 - **ConfigMap**: Configuration management for `server.yaml` settings
-- **Services**: Headless services for pod communication, plus optional dedicated headless metrics services when metrics are enabled
+- **Services**: Headless services providing stable pod DNS names, plus optional dedicated headless services when metrics are enabled
 
 ### Step 3: Verify Installation
 
@@ -267,7 +267,7 @@ listeners:
 
 ### Metrics and Monitoring
 
-When `metrics.enabled` is `true`, the Helm chart does the following:
+When `metrics.enabled` is `true`, adds the following `server.yaml` config entries:
 
 - `metrics.reporters`: comma-separated reporter names from `metrics.reporters`
 - `metrics.reporter.<name>.<option>`: one entry per reporter option in `metrics.reporters`

From 1416ac3fdf7fc89eebcbe122f36179ef94814354 Mon Sep 17 00:00:00 2001
From: Muhammet Orazov <916295+morazow@users.noreply.github.com>
Date: Fri, 6 Mar 2026 10:34:44 +0100
Subject: [PATCH 5/6] Apply suggestion from @affo

Co-authored-by: Lorenzo Affetti <lorenzo.affetti@gmail.com>
---
 helm/templates/svc-metrics-coordinator.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/helm/templates/svc-metrics-coordinator.yaml b/helm/templates/svc-metrics-coordinator.yaml
index c5d6cf4da8..0cbd255409 100644
--- a/helm/templates/svc-metrics-coordinator.yaml
+++ b/helm/templates/svc-metrics-coordinator.yaml
@@ -23,7 +23,7 @@ metadata:
   name: {{ .Release.Name }}-coordinator-server-metrics-hs
   labels:
     {{- include "fluss.labels" . | nindent 4 }}
-    app.kubernetes.io/component: coordinator
+    app.kubernetes.io/component: metrics
     {{- with .Values.metrics.service.labels }}
     {{- toYaml . | nindent 4 }}
     {{- end }}

From f91ef73d2692b81827780c374e668f53b327db3d Mon Sep 17 00:00:00 2001
From: morazow <m.orazow@gmail.com>
Date: Fri, 6 Mar 2026 10:39:25 +0100
Subject: [PATCH 6/6] Address review suggestions

(cherry picked from commit 82ad87e2bb2cbdfb8036a91062a87a24bf61a394)
---
 helm/README.md                                | 60 ++++++++++++-----
 helm/templates/_metrics.tpl                   | 13 +---
 helm/templates/svc-metrics-coordinator.yaml   | 11 ++--
 helm/templates/svc-metrics-tablet.yaml        | 15 +++--
 helm/tests/metrics_test.yaml                  | 31 ++++++---
 helm/values.yaml                              |  8 +--
 .../install-deploy/deploying-with-helm.md     | 65 +++++++++++++------
 7 files changed, 134 insertions(+), 69 deletions(-)

diff --git a/helm/README.md b/helm/README.md
index b529e4f9ee..ff7257c34a 100644
--- a/helm/README.md
+++ b/helm/README.md
@@ -105,11 +105,9 @@ helm install fluss ./fluss-helm \
 ```
 
 When enabled, the chart will:
+
 - configure `metrics.reporters` from reporter names in values
 - configure `metrics.reporter.<name>.<option>` entries from values
-- create separate metrics services exposing the Prometheus reporter port
-- optionally add metrics scrape annotations to metrics services from values
-- optionally add custom labels to metrics services for `ServiceMonitor` selectors
 
 Values:
 
@@ -117,28 +115,58 @@ Values:
 | --- | --- |
 | `metrics.enabled` | Enables metrics reporting and endpoint exposure. |
 | `metrics.reporters` | Map of Fluss metric reporters and their options. |
-| `metrics.service.portName` | Named port exposed by metrics services (usually used by ServiceMonitor endpoint `port`). |
-| `metrics.service.labels` | Optional labels rendered on metrics services (usually used by ServiceMonitor selectors). |
-| `metrics.annotations` | Optional map of annotations rendered on metrics services when metrics are enabled. |
+| `metrics.reporters.jmx.port` | JMX reporter port range (e.g. `9250-9260`). |
+| `metrics.reporters.prometheus.port` | Prometheus reporter port (default `9249`). |
+| `metrics.reporters.prometheus.service.portName` | Named port exposed by metrics services (default `metrics`). |
+| `metrics.reporters.prometheus.service.labels` | Optional labels on metrics services (useful for [ServiceMonitor](https://prometheus-operator.dev/docs/api-reference/api/#monitoring.coreos.com/v1.ServiceMonitor) selectors). |
+| `metrics.reporters.prometheus.service.annotations` | Optional annotations on metrics services (useful for annotation-based scraping). |
+
+#### Prometheus Annotation Based Scraping
+
+The values below enable annotation based scraping:
+
+```yaml
+metrics:
+  enabled: true
+  reporters:
+    prometheus:
+      port: 9249
+      service:
+        annotations:
+          prometheus.io/scrape: "true"
+          prometheus.io/path: "/metrics"
+          prometheus.io/port: "9249"
+```
+
+#### Prometheus ServiceMonitor Based Scraping
 
-Example `values.yaml` snippet:
+When using the [Prometheus Operator](https://prometheus-operator.dev/), use the values below to add labels to the metrics services and then create a `ServiceMonitor` that selects them:
 
 ```yaml
 metrics:
   enabled: true
   reporters:
-    jmx:
-      port: 9250-9260
     prometheus:
       port: 9249
-  service:
-    portName: metrics
-    labels:
+      service:
+        portName: metrics
+        labels:
+          monitoring: enabled
+```
+
+Apply the following to create a `ServiceMonitor` resource that matches the label:
+
+```yaml
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: fluss-metrics
+spec:
+  selector:
+    matchLabels:
       monitoring: enabled
-  annotations:
-    prometheus.io/scrape: "true"
-    prometheus.io/path: "/metrics"
-    prometheus.io/port: "9249"
+  endpoints:
+    - port: metrics
 ```
 
 ### Zookeeper and storage
diff --git a/helm/templates/_metrics.tpl b/helm/templates/_metrics.tpl
index f4f29e7643..e549ad9c49 100644
--- a/helm/templates/_metrics.tpl
+++ b/helm/templates/_metrics.tpl
@@ -45,6 +45,7 @@ metrics.reporters: {{ join "," $reporterNames }}
 {{- end -}}
 {{- range $name := $reporterNames -}}
 {{- range $option, $value := index $reporters $name -}}
+{{- if ne $option "service" -}}
 {{- $fullKey := printf "metrics.reporter.%s.%s" $name $option -}}
 {{- if not (hasKey $config $fullKey) }}
 {{ $fullKey }}: {{ tpl (printf "%v" $value) $ }}
@@ -53,15 +54,5 @@ metrics.reporters: {{ join "," $reporterNames }}
 {{- end -}}
 {{- end -}}
 {{- end -}}
-
-{{/*
-Renders metrics annotations entries as YAML format.
-Expects the root context as argument.
-*/}}
-{{- define "fluss.metrics.annotations" -}}
-{{- if .Values.metrics.enabled -}}
-{{- with .Values.metrics.annotations -}}
-{{- toYaml . -}}
-{{- end -}}
-{{- end -}}
 {{- end -}}
+
diff --git a/helm/templates/svc-metrics-coordinator.yaml b/helm/templates/svc-metrics-coordinator.yaml
index 0cbd255409..f286d383a7 100644
--- a/helm/templates/svc-metrics-coordinator.yaml
+++ b/helm/templates/svc-metrics-coordinator.yaml
@@ -16,7 +16,8 @@
 # limitations under the License.
 #
 
-{{- if .Values.metrics.enabled }}
+{{- if and .Values.metrics.enabled .Values.metrics.reporters.prometheus }}
+{{- $promSvc := .Values.metrics.reporters.prometheus.service | default dict }}
 apiVersion: v1
 kind: Service
 metadata:
@@ -24,16 +25,18 @@ metadata:
   labels:
     {{- include "fluss.labels" . | nindent 4 }}
     app.kubernetes.io/component: metrics
-    {{- with .Values.metrics.service.labels }}
+    {{- with $promSvc.labels }}
     {{- toYaml . | nindent 4 }}
     {{- end }}
+  {{- with $promSvc.annotations }}
   annotations:
-    {{- include "fluss.metrics.annotations" . | nindent 4 }}
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
 spec:
   clusterIP: None
   type: ClusterIP
   ports:
-    - name: {{ default "metrics" .Values.metrics.service.portName }}
+    - name: {{ default "metrics" $promSvc.portName }}
       protocol: TCP
       port: {{ default 9249 .Values.metrics.reporters.prometheus.port }}
       targetPort: {{ default 9249 .Values.metrics.reporters.prometheus.port }}
diff --git a/helm/templates/svc-metrics-tablet.yaml b/helm/templates/svc-metrics-tablet.yaml
index 1d8f434b72..8fbb3adb06 100644
--- a/helm/templates/svc-metrics-tablet.yaml
+++ b/helm/templates/svc-metrics-tablet.yaml
@@ -16,24 +16,27 @@
 # limitations under the License.
 #
 
-{{- if .Values.metrics.enabled }}
+{{- if and .Values.metrics.enabled .Values.metrics.reporters.prometheus }}
+{{- $promSvc := .Values.metrics.reporters.prometheus.service | default dict }}
 apiVersion: v1
 kind: Service
 metadata:
-  name: tablet-server-metrics-hs
+  name: {{ .Release.Name }}-tablet-server-metrics-hs
   labels:
     {{- include "fluss.labels" . | nindent 4 }}
-    app.kubernetes.io/component: tablet
-    {{- with .Values.metrics.service.labels }}
+    app.kubernetes.io/component: metrics
+    {{- with $promSvc.labels }}
     {{- toYaml . | nindent 4 }}
     {{- end }}
+  {{- with $promSvc.annotations }}
   annotations:
-    {{- include "fluss.metrics.annotations" . | nindent 4 }}
+    {{- toYaml . | nindent 4 }}
+  {{- end }}
 spec:
   clusterIP: None
   type: ClusterIP
   ports:
-    - name: {{ default "metrics" .Values.metrics.service.portName }}
+    - name: {{ default "metrics" $promSvc.portName }}
       protocol: TCP
       port: {{ default 9249 .Values.metrics.reporters.prometheus.port }}
       targetPort: {{ default 9249 .Values.metrics.reporters.prometheus.port }}
diff --git a/helm/tests/metrics_test.yaml b/helm/tests/metrics_test.yaml
index 052ebd5848..a6130a5a57 100644
--- a/helm/tests/metrics_test.yaml
+++ b/helm/tests/metrics_test.yaml
@@ -141,6 +141,15 @@ tests:
     asserts:
       - hasDocuments:
           count: 0
+  - it: does not render coordinator metrics service when prometheus reporter is absent
+    set:
+      metrics.enabled: true
+      metrics.reporters:
+        jmx:
+          port: 9250
+    asserts:
+      - hasDocuments:
+          count: 0
 ---
 
 suite: metrics-service-enabled
@@ -153,7 +162,7 @@ tests:
     asserts:
       - equal:
           path: metadata.name
-          value: coordinator-server-metrics-hs
+          value: RELEASE-NAME-coordinator-server-metrics-hs
       - equal:
           path: spec.ports[0].name
           value: metrics
@@ -166,8 +175,8 @@ tests:
   - it: renders custom port name and service labels for ServiceMonitor selectors
     set:
       metrics.enabled: true
-      metrics.service.portName: fluss-metrics
-      metrics.service.labels:
+      metrics.reporters.prometheus.service.portName: fluss-metrics
+      metrics.reporters.prometheus.service.labels:
         monitoring: enabled
     asserts:
       - equal:
@@ -179,7 +188,7 @@ tests:
   - it: renders value-driven annotations on metrics service when provided
     set:
       metrics.enabled: true
-      metrics.annotations:
+      metrics.reporters.prometheus.service.annotations:
         prometheus.io/scrape: "true"
         prometheus.io/path: "/metrics"
         prometheus.io/port: "9249"
@@ -197,9 +206,15 @@ tests:
     set:
       metrics.enabled: true
     asserts:
-      - equal:
+      - isNull:
           path: metadata.annotations
-          value: null
+  - it: uses metrics component label
+    set:
+      metrics.enabled: true
+    asserts:
+      - equal:
+          path: metadata.labels["app.kubernetes.io/component"]
+          value: metrics
 ---
 
 suite: pod-service-separation
@@ -210,7 +225,7 @@ tests:
   - it: keeps coordinator pod service without metrics annotations
     set:
       metrics.enabled: true
-      metrics.annotations:
+      metrics.reporters.prometheus.service.annotations:
         prometheus.io/scrape: "true"
     template: templates/svc-coordinator.yaml
     asserts:
@@ -219,7 +234,7 @@ tests:
   - it: keeps tablet pod service without metrics annotations
     set:
       metrics.enabled: true
-      metrics.annotations:
+      metrics.reporters.prometheus.service.annotations:
         prometheus.io/scrape: "true"
     template: templates/svc-tablet.yaml
     asserts:
diff --git a/helm/values.yaml b/helm/values.yaml
index f3fccfa1cf..1b10e9fe7b 100644
--- a/helm/values.yaml
+++ b/helm/values.yaml
@@ -63,10 +63,10 @@ metrics:
   reporters:
     prometheus:
       port: 9249
-  service:
-    portName: metrics
-    labels: {}
-  annotations: {}
+      service:
+        portName: metrics
+        labels: {}
+        annotations: {}
 
 resources: {}
   # We usually recommend not to specify default resources and to leave this as a conscious
diff --git a/website/docs/install-deploy/deploying-with-helm.md b/website/docs/install-deploy/deploying-with-helm.md
index b6efb2be7a..db5e2d1c1c 100644
--- a/website/docs/install-deploy/deploying-with-helm.md
+++ b/website/docs/install-deploy/deploying-with-helm.md
@@ -189,9 +189,11 @@ The following table lists the configurable parameters of the Fluss chart and the
 |-----------|-------------|---------|
 | `metrics.enabled` | Enables metrics reporter configuration and dedicated metrics services | `false` |
 | `metrics.reporters` | Map of Fluss metric reporters and reporter options | `{ prometheus: { port: 9249 } }` |
-| `metrics.service.portName` | Named port exposed on metrics services (used by ServiceMonitor endpoint `port`) | `metrics` |
-| `metrics.service.labels` | Additional labels added to metrics services for ServiceMonitor selectors | `{}` |
-| `metrics.annotations` | Optional annotations added to metrics services (for annotation-based scraping) | `{}` |
+| `metrics.reporters.jmx.port` | JMX reporter port range | - |
+| `metrics.reporters.prometheus.port` | Prometheus reporter port | `9249` |
+| `metrics.reporters.prometheus.service.portName` | Named port exposed on metrics services (used by ServiceMonitor endpoint `port`) | `metrics` |
+| `metrics.reporters.prometheus.service.labels` | Additional labels added to metrics services for ServiceMonitor selectors | `{}` |
+| `metrics.reporters.prometheus.service.annotations` | Optional annotations added to metrics services (for annotation-based scraping) | `{}` |
 
 ### Fluss Configuration Overrides
 
@@ -271,33 +273,56 @@ When `metrics.enabled` is `true`, adds the following `server.yaml` config entrie
 
 - `metrics.reporters`: comma-separated reporter names from `metrics.reporters`
 - `metrics.reporter.<name>.<option>`: one entry per reporter option in `metrics.reporters`
-- Creates dedicated metrics services:
-  - `coordinator-server-metrics-hs`
-  - `tablet-server-metrics-hs`
-- Exposes the Prometheus reporter port as a named service port (`metrics.service.portName`)
-- Adds optional labels from `metrics.service.labels` for ServiceMonitor selection
 
-If `metrics.annotations` is configured, these annotations are added to the dedicated metrics services and can be used for annotation based scraping.
+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`.
+
+#### Prometheus Annotation Based Scraping
+
+The example values below show how to add annotations to the metrics services so that a Prometheus server can discovery and scrape them automatically based on the annotations:
 
 ```yaml
 metrics:
   enabled: true
   reporters:
-    jmx:
-      port: 9250-9260
     prometheus:
       port: 9249
-  service:
-    portName: metrics
-    labels:
-      monitoring: enabled
-  annotations:
-    prometheus.io/scrape: "true"
-    prometheus.io/path: "/metrics"
-    prometheus.io/port: "9249"
+      service:
+        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`.
+#### Prometheus ServiceMonitor Based Scraping
+
+Similarly, if using the [Prometheus Operator](https://prometheus-operator.dev/), use the values below to add labels to the metrics services and then create a [`ServiceMonitor`](https://prometheus-operator.dev/docs/api-reference/api/#monitoring.coreos.com/v1.ServiceMonitor) that selects them:
+
+```yaml
+metrics:
+  enabled: true
+  reporters:
+    prometheus:
+      port: 9249
+      service:
+        portName: metrics
+        labels:
+          monitoring: enabled
+```
+
+Then create a `ServiceMonitor` resource that matches the label:
+
+```yaml
+apiVersion: monitoring.coreos.com/v1
+kind: ServiceMonitor
+metadata:
+  name: fluss-metrics
+spec:
+  selector:
+    matchLabels:
+      monitoring: enabled
+  endpoints:
+    - port: metrics
+```
 
 ### Storage Configuration