(1.37) Metrics API not documented

[lmktfy]

This is a Bug Report

KEP issue: kubernetes/enhancements#5207

Problem: https://www.kubernetes.dev/resources/keps/5207/#release-signoff-checklist shows that metrics.k8s.io is due to graduate to v1 in the Kubernetes 1.37 release, but there isn't documentation for it yet.

There was #56349 but this only updates some pages that mention the API.

Proposed Solution:
Document the API metrics.k8s.io

Additional Information:
Filed as a bug because this change should have failed PRR / a criterion for graduation is not met.
/kind bug
/language en
/sig instrumentation

[lmktfy]

I am going to triage this as accepted, but if other contributors (or even one other contributor) disagrees with that triage, it's OK to override that decision or my prioritization.

/triage accepted
/priority important-soon

[tico88612]

This is a follow-up document; I wasn't sure at the time, so I left it blank for now. The Lead has since reviewed the website PR #56349 and approved it. I'd like to know what else we need to provide?

The only thing I can think of is that the content is mainly about the metric v1 API, which requires updating thek-sigs/api-ref-generator. However, this submodule hasn't been updated in nearly 2 years. I'd like to confirm how to handle this update. I asked about this in the Slack #release-docs channel, but haven't received a response yet.

I would appreciate it if you could provide more specific details. Thank you!

[Caesarsage]

This should be generated alongside the other reference docs after the final release cut.
Generating v1 means adding it to genref/config.yaml on reference gen, bumping the go mod version, and copying the
output over in a PR to k/website.

Thanks for bringing this up, I will keep track of it when I generate the others.

/assign

[lmktfy]

Here's the problem: https://deploy-preview-56446--kubernetes-io-main-staging.netlify.app/blog/1/01/01/kubernetes-v1-37-metrics-api-ga/#learn-more wants to link to a concept called "Metrics API" - but we don't yet have a documentation page for it to link to. Hyperlinks to GitHub are OK for Alpha features but for Beta and GA our policy is to request documentation.

There is a reference, but good reference pages automagically include a link to the relevant concept. For that automation to work, we need a concept page (and some metadata). Right now there isn't a concept page.

---

What should we add? I suggest we could add one of:

• a clear mention in https://kubernetes.io/docs/concepts/cluster-administration/observability/
• a new page at https://kubernetes.io/docs/concepts/extend-kubernetes/metrics/
• a new page at https://kubernetes.io/docs/concepts/extend-kubernetes/observability/

(why in the "Extend Kubernetes" section? Because you can provide your own implementation, and because people actually do).