feat: add new kube_service_spec_ports metric by Serializator · Pull Request #2849 · kubernetes/kube-state-metrics

Serializator · 2026-01-18T01:10:18Z

What this PR does / why we need it:
Add new metric kube_service_spec_ports to represent ports on the service resource.

The kube_service_spec_ prefix matches with the naming convention for the rest of the metrics.

To stay aligned with other metrics, .spec.ports.appProtocol is not included as a label. The same is true for the kube_endpoint_address metric.

.spec.ports.targetPort is not included as a label due to its inconsistent value. It can be a named port or port number.

How does this change affect the cardinality of KSM:
Increases cardinality with a new time series.

Which issue(s) this PR fixes:
Fixes #2819

Serializator · 2026-02-04T16:03:21Z

Hey @dgrisonnet & @mrueg! Would one of you have time to approve the workflow so tests can run? Thank you in advance!

bhope

Thanks for the PR. A few comments:

Stability: new metrics should start at basemetrics.ALPHA, not basemetrics.STABLE (see inline)
node_port_number: should always be present as a label, using "" when no NodePort is set (see inline)

bhope · 2026-03-01T21:52:08Z

internal/store/service.go

+			"kube_service_spec_ports",
+			"Service ports. One series for each port",
+			metric.Gauge,
+			basemetrics.STABLE,


I believe this should be basemetrics.ALPHA. We can only promote a metric to alpha->beta->stable after it has gone through multiple releases without any issues. Happy to be corrected if I am missing any context.

Thank you for the review! I updated it to be basemetrics.ALPHA

bhope · 2026-03-01T21:55:00Z

internal/store/service.go

+					values := []string{port.Name, string(protocol), strconv.FormatInt(int64(port.Port), 10)}
+
+					// 0 means no node port is set. It is also a reserved port (RFC-6335) so there shouldn't be a problem.
+					if port.NodePort > 0 {


node_port_number should always be present per the project's best practices. Use "" when NodePort == 0 instead of conditionally adding the label.
Check the best practices here: https://github.com/kubernetes/kube-state-metrics/blob/main/docs/design/metrics-best-practices.md#optional-properties

Thank you! I've updated it to be an empty string when the node port is not set.

bhope · 2026-03-18T21:58:05Z

internal/store/service.go

+						nodePortNumber = strconv.FormatInt(int64(port.NodePort), 10)
+					}
+
+					keys := []string{"port_name", "port_protocol", "port_number", "node_port_number"}


nit: probably should sit outside for loop

Good point 😉

bhope · 2026-03-18T22:02:02Z

docs/metrics/service/service-metrics.md

 | kube_service_created                      | Gauge       | Unix creation timestamp                                                                                                                 | seconds                 | `service`=&lt;service-name&gt; <br> `namespace`=&lt;service-namespace&gt; <br> `uid`=&lt;service-uid&gt;                                                                                                                                                                                                                                 | STABLE       |
 | kube_service_spec_type                    | Gauge       | Type about service                                                                                                                      |                         | `service`=&lt;service-name&gt; <br> `namespace`=&lt;service-namespace&gt; <br> `uid`=&lt;service-uid&gt; <br> `type`=&lt;ClusterIP\|NodePort\|LoadBalancer\|ExternalName&gt;                                                                                                                                                             | STABLE       |
 | kube_service_spec_external_ip             | Gauge       | Service external ips. One series for each ip                                                                                            |                         | `service`=&lt;service-name&gt; <br> `namespace`=&lt;service-namespace&gt; <br> `uid`=&lt;service-uid&gt; <br> `external_ip`=&lt;external-ip&gt;                                                                                                                                                                                          | STABLE       |
+| kube_service_spec_ports                   | Gauge       | Service port. One series for each port                                                                                                  |                         | `service`=&lt;service-name&gt; <br> `namespace`=&lt;service-namespace&gt; <br> `uid`=&lt;service-uid&gt; <br> `port_number`=&lt;port-number&gt; <br> `node_port_number`=&lt;node-port-number&gt;                                                                                                                                         | EXPERIMENTAL |


Can you verify this? Your code emits port_name and port_protocol too

You're correct. Good catch! I added port_name and port_protocol to the documentation.

bhope · 2026-03-18T22:03:35Z

/triage accepted

bhope · 2026-03-19T00:07:27Z

Overall its in a good shape now. Can you squash the commits?

Signed-off-by: Julian van den Berkmortel <7153670+Serializator@users.noreply.github.com>

Serializator · 2026-03-19T20:56:24Z

@bhope squashed the commits and also resolved a linting problem.

bhope · 2026-03-19T21:26:04Z

Thanks

/lgtm

k8s-ci-robot · 2026-03-19T21:26:16Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: bhope, Serializator
Once this PR has been reviewed and has the lgtm label, please assign catherinef-dev for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

mrueg · 2026-03-20T21:11:23Z

Can we quantify the number of timeseries it generates per port, service, etc.?

k8s-ci-robot added the needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. label Jan 18, 2026

k8s-ci-robot requested a review from dgrisonnet January 18, 2026 01:10

github-project-automation bot added this to SIG Instrumentation Jan 18, 2026

k8s-ci-robot requested a review from mrueg January 18, 2026 01:10

github-project-automation bot moved this to Needs Triage in SIG Instrumentation Jan 18, 2026

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Jan 18, 2026

Serializator changed the title ~~Add new kube_service_spec_ports metric~~ feat: add new kube_service_spec_ports metric Jan 18, 2026

Serializator force-pushed the ISSUE-2819-kube-service-port-metric branch from a35c311 to dc2f674 Compare January 18, 2026 01:18

Serializator force-pushed the ISSUE-2819-kube-service-port-metric branch from dc2f674 to e9da2b6 Compare January 30, 2026 22:07

bhope suggested changes Mar 1, 2026

View reviewed changes

github-project-automation bot moved this from Needs Triage to In Progress in SIG Instrumentation Mar 1, 2026

Serializator force-pushed the ISSUE-2819-kube-service-port-metric branch from e9da2b6 to 12295e8 Compare March 18, 2026 21:31

bhope reviewed Mar 18, 2026

View reviewed changes

k8s-ci-robot added triage/accepted Indicates an issue or PR is ready to be actively worked on. and removed needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Mar 18, 2026

Serializator force-pushed the ISSUE-2819-kube-service-port-metric branch from 12295e8 to 33423e9 Compare March 18, 2026 22:29

feat: add new kube_service_spec_port metric

14684e0

Signed-off-by: Julian van den Berkmortel <7153670+Serializator@users.noreply.github.com>

Serializator force-pushed the ISSUE-2819-kube-service-port-metric branch from 33423e9 to 14684e0 Compare March 19, 2026 20:55

k8s-ci-robot assigned bhope Mar 19, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 19, 2026

Conversation

Serializator commented Jan 18, 2026

Uh oh!

Serializator commented Feb 4, 2026

Uh oh!

bhope left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bhope commented Mar 18, 2026

Uh oh!

bhope commented Mar 19, 2026

Uh oh!

Serializator commented Mar 19, 2026

Uh oh!

bhope commented Mar 19, 2026

Uh oh!

k8s-ci-robot commented Mar 19, 2026

Uh oh!

mrueg commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants