Doc: Kubelet PSI metrics feature graduates to GA by mariafromano-25 · Pull Request #54328 · kubernetes/website

mariafromano-25 · 2026-02-07T00:04:57Z

Description

Update feature status and wording as the feature goes stable.

Issue

Closes: #

k8s-ci-robot · 2026-02-07T00:05:23Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign divya-mohan0209 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:

content/en/docs/OWNERS

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

netlify · 2026-02-07T00:14:52Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`b9366bc`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/69cc272001c87e0008e36778
😎 Deploy Preview	https://deploy-preview-54328--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

lmktfy · 2026-02-08T11:04:59Z

/sig node

lmktfy

I know this PR is draft, but even so I hope the advice helps.

lmktfy · 2026-02-08T11:07:44Z

content/en/docs/concepts/cluster-administration/system-metrics.md

 ### kubelet Pressure Stall Information (PSI) metrics

-{{< feature-state for_k8s_version="v1.34" state="beta" >}}
+{{< feature-state for_k8s_version="v1.36" state="stable" >}}


Early feedback: try this

Suggested change

{{< feature-state for_k8s_version="v1.36" state="stable" >}}

{{< feature-state feature_gate_name="KubeletPSI" >}}

and then look for instances of KubeletPSI anywhere in the English docs that might need an update.

For other localizations, each localization team - usually 100% volunteers - picks its own way of working.

lmktfy · 2026-02-08T11:08:23Z

/sig instrumentation

mariafromano-25 · 2026-03-27T22:25:38Z

Followed guide: https://github.com/kubernetes/website?tab=readme-ov-file#the-kubernetes-documentation to run the website locally. My main changes in http://localhost:1313/docs/concepts/cluster-administration/system-metrics/#kubelet-pressure-stall-information-psi-metrics look like:

mariafromano-25 · 2026-03-27T22:27:06Z

cc @roycaihw @ndixita

content/en/docs/concepts/cluster-administration/system-metrics.md

SergeyKanzhelev · 2026-03-28T00:31:32Z

content/en/docs/concepts/cluster-administration/system-metrics.md

 container_pressure_io_waiting_seconds_total
 ```
+*Summary API*: Exposed at the `/stats/summary` endpoint, providing both the cumulative `totals` and the moving averages (`avg10`, `avg60`, `avg300`). These averages represent the percentage of time that tasks were stalled on a resource over the respective 10-second, 60-second, and 5-minute intervals. This endpoint reports the metrics in the following format: 
+```


most markdown linters like the empty line before the ```

SergeyKanzhelev · 2026-03-28T00:32:13Z

content/en/docs/concepts/cluster-administration/system-metrics.md


-This feature is enabled by default, by setting the `KubeletPSI` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/). The information is also exposed in the
+This feature is enabled by default. Starting with Kubernetes v.1.36, the `KubeletPSI` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is locked to true and cannot be disabled. The information is also exposed in the
 [Summary API](/docs/reference/instrumentation/node-metrics#psi).


the paragraph above already said about summary API

SergeyKanzhelev · 2026-03-28T00:33:18Z

content/en/docs/concepts/cluster-administration/system-metrics.md

+```

-This feature is enabled by default, by setting the `KubeletPSI` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/). The information is also exposed in the
+This feature is enabled by default. Starting with Kubernetes v.1.36, the `KubeletPSI` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is locked to true and cannot be disabled. The information is also exposed in the


I do not know if we need to continue saying about these versions. We have the feature gate tag above already

roycaihw · 2026-03-30T17:47:28Z

content/en/docs/concepts/cluster-administration/system-metrics.md

 container_pressure_io_stalled_seconds_total
 container_pressure_io_waiting_seconds_total
 ```
+*Summary API*: Exposed at the `/stats/summary` endpoint, providing both the cumulative `totals` and the moving averages (`avg10`, `avg60`, `avg300`). These averages represent the percentage of time that tasks were stalled on a resource over the respective 10-second, 60-second, and 5-minute intervals. This endpoint reports the metrics in the following format: 


I like the explanation. My suggestion is maybe add an example (with non-zero PSI data) to further explain how to interpret the data. An example can be more comprehensive than the plain documentation.

I created an example below, let me know what you think!

roycaihw · 2026-03-30T17:49:08Z

content/en/docs/reference/instrumentation/understand-psi-metrics.md

 [Pressure Stall Information](https://docs.kernel.org/accounting/psi.html)
 (PSI) for CPU, memory, and I/O usage. The information is collected at node, pod and container level.
-This feature is enabled by default by setting the `KubeletPSI` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/).
+Starting with Kubernetes v.1.36, the `KubeletPSI` [feature gate](/docs/reference/command-line-tools-reference/feature-gates/) is locked to true and cannot be disabled.


Similar to my comment above. I think we can add an example with non-zero PSI data here to help users understand how to interpret the PSI data.

Should I reuse the same example as the system-metrics.md page or make a new one?

…docs

Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>

mariafromano-25 · 2026-03-31T19:57:50Z

Updated view of the website when ran locally:

AnshumanTripathi · 2026-04-01T17:20:13Z

Hello @mariafromano-25 👋!
I'm reaching out from the Docs team. Just checking in as we approach Docs Freeze on Wednesday 8th April 2026 (AoE) / Thursday 9th April 2026, 12:00 UTC.
This documentation appears to still be under review. To meet the Docs Freeze, this PR must have a technical review as well as lgtm and approve labels applied, without any unaddressed comments or concerns from SIG Docs.
Thank you!

k8s-ci-robot added this to the 1.36 milestone Feb 7, 2026

k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Feb 7, 2026

k8s-ci-robot requested review from RainbowMango and brancz February 7, 2026 00:05

k8s-ci-robot added language/en Issues or PRs related to English language size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Feb 7, 2026

ndixita mentioned this pull request Feb 7, 2026

Support PSI based on cgroupv2 kubernetes/enhancements#4205

Open

31 tasks

k8s-ci-robot added the sig/node Categorizes an issue or PR as relevant to SIG Node. label Feb 8, 2026

github-project-automation bot added this to SIG Node: code and documentation PRs Feb 8, 2026

github-project-automation bot moved this to Triage in SIG Node: code and documentation PRs Feb 8, 2026

lmktfy reviewed Feb 8, 2026

View reviewed changes

k8s-ci-robot added the sig/instrumentation Categorizes an issue or PR as relevant to SIG Instrumentation. label Feb 8, 2026

bart0sh moved this from Triage to Work in progress in SIG Node: code and documentation PRs Feb 18, 2026

mariafromano-25 force-pushed the dev-1.36 branch from 1755fe1 to 0b780a4 Compare February 21, 2026 01:17

k8s-ci-robot added size/S Denotes a PR that changes 10-29 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Feb 21, 2026

mariafromano-25 force-pushed the dev-1.36 branch from 63886d8 to 0eb9a92 Compare March 27, 2026 22:09

mariafromano-25 marked this pull request as ready for review March 27, 2026 22:27

k8s-ci-robot requested a review from salaxander March 27, 2026 22:27

mariafromano-25 changed the title ~~[WIP] Doc: Kubelet PSI metrics feature graduates to GA~~ Doc: Kubelet PSI metrics feature graduates to GA Mar 27, 2026

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Mar 27, 2026

SergeyKanzhelev reviewed Mar 28, 2026

View reviewed changes

content/en/docs/concepts/cluster-administration/system-metrics.md Outdated Show resolved Hide resolved

SergeyKanzhelev reviewed Mar 28, 2026

View reviewed changes

roycaihw reviewed Mar 30, 2026

View reviewed changes

mariafromano-25 and others added 6 commits March 31, 2026 00:39

starting changes for psi GA docs, still WIP

7e3b01d

updated system-metrics.md with more info on both endpoints for psi

1742813

Update KubeletPSI feature gate to stable for v1.36

bd2322f

Update remaining PSI docs for GA. Added format from the linux kernel …

2fc5820

…docs

fixing wording that feature cannot be disabled after 1.36

bd3fd15

Apply suggestion from @SergeyKanzhelev

5f08b9f

Co-authored-by: Sergey Kanzhelev <S.Kanzhelev@live.com>

mariafromano-25 force-pushed the dev-1.36 branch from f0962c2 to 5f08b9f Compare March 31, 2026 00:39

mariafromano-25 added 2 commits March 31, 2026 19:31

adding example on interpreting metrics

66118cd

fixed some typos and spacing

b9366bc

	{{< feature-state for_k8s_version="v1.36" state="stable" >}}
	{{< feature-state feature_gate_name="KubeletPSI" >}}

Conversation

mariafromano-25 commented Feb 7, 2026

Description

Issue

Uh oh!

k8s-ci-robot commented Feb 7, 2026

Uh oh!

netlify bot commented Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull request preview available for checking

Uh oh!

lmktfy commented Feb 8, 2026

Uh oh!

lmktfy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lmktfy commented Feb 8, 2026

Uh oh!

mariafromano-25 commented Mar 27, 2026

Uh oh!

mariafromano-25 commented Mar 27, 2026

Uh oh!

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!

mariafromano-25 commented Mar 31, 2026

Uh oh!

AnshumanTripathi commented Apr 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

netlify bot commented Feb 7, 2026 •

edited

Loading