node: start moving the resource management docs to concepts #48797

ffromani · 2024-11-21T11:40:36Z

Description

Move the cpu management policies and options docs from tasks to concepts
xref: #48340 (review)

In the 1.32 cycle I don't have capacity to move except for CPU manager, which is the worst offender anyway. Other managers should follow suite, hopefully in the 1.33 cycle already.

Issue

Closes: #38121 (albeit in a different and IMO better way)

k8s-ci-robot · 2024-11-21T11:40:48Z

[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 nate-double-u for approval. For more information see the Kubernetes Code Review Process.

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

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 · 2024-11-21T11:40:59Z

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	`84d616d`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/673f1cb37f4e95000808f924

We have reached a point where the existing CPU management task page is quite hard to follow. Start moving the resource management concepts to the concept page. We begin with the CPU management policies, the worst offender right now. Over time, the plan is to move all the concepts from tasks in the concepts page. Signed-off-by: Francesco Romani <[email protected]>

netlify · 2024-11-21T11:48:48Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`dbdd3ec`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/673f1c378d677600096cf597
😎 Deploy Preview	https://deploy-preview-48797--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 site configuration.

netlify · 2024-11-21T11:58:43Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`84d616d`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/673f1cb49f654200082aced6
😎 Deploy Preview	https://deploy-preview-48797--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 site configuration.

tengqm · 2024-11-21T13:41:28Z

Totally agree to this refactoring, however, I'd suggest we postpone this because 1.32 is about to be released soon. Propagating this change to localization teams takes some time.

ffromani · 2024-11-21T13:44:02Z

Totally agree to this refactoring, however, I'd suggest we postpone this because 1.32 is about to be released soon. Propagating this change to localization teams takes some time.

cc @sftim so we go ahead with #48340 as-is?

ffromani · 2024-11-21T14:12:42Z

also note this change will impact PRs #48469 and #48356 other than #48340

ffromani · 2024-11-22T14:11:00Z

Totally agree to this refactoring, however, I'd suggest we postpone this because 1.32 is about to be released soon. Propagating this change to localization teams takes some time.

If this helps, what I want to do here is 90% content movement (which I honestly believe helps anyway). @sftim could you please provide your take here about @tengqm 's concern, also considering #48797 (comment) ?

sftim · 2024-11-22T14:16:06Z

Totally agree to this refactoring, however, I'd suggest we postpone this because 1.32 is about to be released soon. Propagating this change to localization teams takes some time.

The decision is about what to postpone

adding the new code
fixing the documentation

In an ideal world, we avoid adding features where we don't also have capacity to document them well. That's what commercial product docs often aim for. In the same ideal world, we planned in that refactoring early.

See #48340 (comment) for a compromise option. How does that sound?

sftim · 2024-11-22T14:16:36Z

If we can get the refactoring done within a few days of now, I'd prefer to land it and redo the feature PRs.

ffromani · 2024-11-22T14:21:42Z

If we can get the refactoring done within a few days of now, I'd prefer to land it and redo the feature PRs.

ok, fair point. Let's timebox this attempt. I'll need some sig-node reviews and I asked for them: https://kubernetes.slack.com/archives/C0BP8PW9G/p1732284959539839
If i can get them and get #48797 in good shape we can see how we can serialize the merges here. Otherwise I'll push to make it ready for early 1.33 merge (or when the floodgates open anyway)

sftim

/lgtm

sftim · 2024-11-21T11:47:02Z

content/en/docs/concepts/policy/node-resource-managers.md

+responsible for these optimizations. The the overall resource management process is governed using
+its [policy](/docs/tasks/administer-cluster/topology-manager/).
+
+## CPU Management Policies


I recommend a tweak on this one:

Suggested change

## CPU Management Policies

## Policies for assigning CPUs to Pods

sftim · 2024-11-23T19:54:07Z

content/en/docs/concepts/policy/node-resource-managers.md

@@ -13,10 +13,234 @@ In order to support latency-critical and high-throughput workloads, Kubernetes o

 <!-- body -->

-The main manager, the Topology Manager, is a Kubelet component that co-ordinates the overall resource management process through its [policy](/docs/tasks/administer-cluster/topology-manager/).
+## Hardware Topology Alignment policies


(extra optional change)

Suggested change

## Hardware Topology Alignment policies

## Hardware topology alignment policies

sftim · 2024-11-23T19:54:32Z

content/en/docs/concepts/policy/node-resource-managers.md

+_Topology Manager_ is a kubelet component that aims to coordinate the set of components that are
+responsible for these optimizations. The the overall resource management process is governed using
+its [policy](/docs/tasks/administer-cluster/topology-manager/).


Extra optional change

Suggested change

_Topology Manager_ is a kubelet component that aims to coordinate the set of components that are

responsible for these optimizations. The the overall resource management process is governed using

its [policy](/docs/tasks/administer-cluster/topology-manager/).

the policy you specify. To learn more, read

[Control Topology Management Policies on a Node](/docs/tasks/administer-cluster/topology-manager/).

sftim · 2024-11-23T19:55:13Z

content/en/docs/concepts/policy/node-resource-managers.md

+## CPU Management Policies
+
+{{< feature-state for_k8s_version="v1.26" state="stable" >}}
+


Optional extra change

Suggested change

Once a Pod is bound to a Node, the kubelet on that node may need to either multiplex the existing

hardware (for example, sharing CPUs across multiple Pods) or allocate hardware by dedicating some

resource (for example, assigning one of more CPUs for a Pod's exclusive use).

sftim · 2024-11-23T19:56:13Z

content/en/docs/concepts/policy/node-resource-managers.md

+{{< note >}}
+CPU Manager doesn't support offlining and onlining of CPUs at runtime.
+{{< /note >}}


Optional extra change

Suggested change

{{< note >}}

CPU Manager doesn't support offlining and onlining of CPUs at runtime.

{{< /note >}}

CPU Manager doesn't support offlining and onlining of CPUs at runtime.

sftim · 2024-11-23T19:58:45Z

content/en/docs/concepts/policy/node-resource-managers.md

+policy and does not apply to hardware where the number of sockets is greater
+than number of NUMA nodes.
+
+##### distribute-cpus-across-cores


Optional extra change

Suggested change

##### distribute-cpus-across-cores

##### `distribute-cpus-across-cores`

sftim · 2024-11-23T19:59:23Z

content/en/docs/tasks/administer-cluster/cpu-management-policies.md

-management policies to determine some placement preferences on the node.
-
-### Configuration
+## CPU Management Policies configuration


Optional extra change

Suggested change

## CPU Management Policies configuration

## Configuring CPU management policies

sftim · 2024-11-23T20:01:10Z

content/en/docs/tasks/administer-cluster/cpu-management-policies.md

 state file `cpu_manager_state` in the kubelet root directory.
 {{< /note >}}

+#### None policy configuration


Suggested change

#### None policy configuration

#### `none` policy configuration

?

Not sure if this is right.

sftim · 2024-11-23T20:05:10Z

content/en/docs/concepts/policy/node-resource-managers.md

+container's resource limit for the CPU resource is an integer greater than or
+equal to one. The `nginx` container is granted 2 exclusive CPUs.
+
+#### Static policy options


Optional extra change

Suggested change

#### Static policy options

#### Static policy options {#cpu-policy-static--options}

(sic)

sftim · 2024-11-23T20:05:35Z

content/en/docs/concepts/policy/node-resource-managers.md

+#### Static policy options
+
+The behavior of the static policy can be fine-tuned using the CPU Manager policy options.
+The following policy options exist for the static `CPUManager` policy.


Optional extra change

Suggested change

The following policy options exist for the static `CPUManager` policy.

The behavior of the static policy can be fine-tuned using CPU manager policy options.

The following policy options exist for the static CPU management policy:

{{/* options in alphabetical order */}}

`align-by-socket` (alpha, hidden by default)

: Align CPUs by physical package / socket boundary, rather than logical NUMA boundaries (available since Kubernetes v1.25)

`distribute-cpus-across-cores` (alpha, hidden by default)

: allocate virtual cores, sometimes called hardware threads, across different physical cores (1.31 or higher)

`distribute-cpus-across-numa` (alpha, hidden by default)

: spread CPUs across different NUMA domains, aiming for an even balance between the selected domains (available since Kubernetes v1.23)

`full-pcpus-only` (beta, visible by default)

: Always allocate full physical cores (available since Kubernetes v1.22)

You can toggle groups of options on and off based upon their maturity level

using the following feature gates:

* `CPUManagerPolicyBetaOptions` (default enabled). Disable to hide beta-level options.

* `CPUManagerPolicyAlphaOptions` (default disabled). Enable to show alpha-level options.

You will still have to enable each option using the `cpuManagerPolicyOptions` field in the

kubelet configuration file.

For more detail about the individual options you can configure, read on.

k8s-ci-robot · 2024-11-23T20:14:50Z

LGTM label has been added.

Git tree hash: df88e29f6338dc3d61435521fba556715bf73816

k8s-ci-robot added this to the 1.32 milestone Nov 21, 2024

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Nov 21, 2024

k8s-ci-robot requested a review from derekwaynecarr November 21, 2024 11:40

k8s-ci-robot added the language/en Issues or PRs related to English language label Nov 21, 2024

k8s-ci-robot requested a review from sjenning November 21, 2024 11:40

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 21, 2024

ffromani mentioned this pull request Nov 21, 2024

Add prefer-align-cpus-by-uncorecache feature gate #48340

Open

ffromani changed the title ~~node: move resource management docs to concepts~~ node: start moving the resource management docs to concepts Nov 21, 2024

ffromani force-pushed the issue-38121-cpu-manager branch from dbdd3ec to 84d616d Compare November 21, 2024 11:42

sftim reviewed Nov 23, 2024

View reviewed changes

k8s-ci-robot assigned sftim Nov 23, 2024

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 23, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

node: start moving the resource management docs to concepts #48797

node: start moving the resource management docs to concepts #48797

ffromani commented Nov 21, 2024 •

edited

Loading

k8s-ci-robot commented Nov 21, 2024

netlify bot commented Nov 21, 2024 •

edited

Loading

netlify bot commented Nov 21, 2024

netlify bot commented Nov 21, 2024

tengqm commented Nov 21, 2024

ffromani commented Nov 21, 2024

ffromani commented Nov 21, 2024

ffromani commented Nov 22, 2024

sftim commented Nov 22, 2024

sftim commented Nov 22, 2024

ffromani commented Nov 22, 2024

sftim left a comment

sftim Nov 21, 2024

sftim Nov 23, 2024

sftim Nov 23, 2024

sftim Nov 23, 2024

sftim Nov 23, 2024

sftim Nov 23, 2024

sftim Nov 23, 2024

sftim Nov 23, 2024

sftim Nov 23, 2024

sftim Nov 23, 2024

sftim Nov 23, 2024 •

edited

Loading

k8s-ci-robot commented Nov 23, 2024

	## CPU Management Policies
	## Policies for assigning CPUs to Pods

	## Hardware Topology Alignment policies
	## Hardware topology alignment policies

		## CPU Management Policies

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

+Once a Pod is bound to a Node, the kubelet on that node may need to either multiplex the existing
+hardware (for example, sharing CPUs across multiple Pods) or allocate hardware by dedicating some
+resource (for example, assigning one of more CPUs for a Pod's exclusive use).

	##### distribute-cpus-across-cores
	##### `distribute-cpus-across-cores`

	## CPU Management Policies configuration
	## Configuring CPU management policies

	#### None policy configuration
	#### `none` policy configuration

	#### Static policy options
	#### Static policy options {#cpu-policy-static--options}

-The following policy options exist for the static `CPUManager` policy.
+The behavior of the static policy can be fine-tuned using CPU manager policy options.
+The following policy options exist for the static CPU management policy:
+{{/* options in alphabetical order */}}
+`align-by-socket` (alpha, hidden by default)
+: Align CPUs by physical package / socket boundary, rather than logical NUMA boundaries (available since Kubernetes v1.25)
+`distribute-cpus-across-cores` (alpha, hidden by default)
+: allocate virtual cores, sometimes called hardware threads, across different physical cores  (1.31 or higher)
+`distribute-cpus-across-numa` (alpha, hidden by default)
+: spread CPUs across different NUMA domains, aiming for an even balance between the selected domains (available since Kubernetes v1.23)
+`full-pcpus-only` (beta, visible by default)
+: Always allocate full physical cores (available since Kubernetes v1.22)
+You can toggle groups of options on and off based upon their maturity level
+using the following feature gates:
+* `CPUManagerPolicyBetaOptions` (default enabled). Disable to hide beta-level options.
+* `CPUManagerPolicyAlphaOptions` (default disabled). Enable to show alpha-level options.
+You will still have to enable each option using the `cpuManagerPolicyOptions` field in the
+kubelet configuration file.
+For more detail about the individual options you can configure, read on.

node: start moving the resource management docs to concepts #48797

Are you sure you want to change the base?

node: start moving the resource management docs to concepts #48797

Conversation

ffromani commented Nov 21, 2024 • edited Loading

Description

Issue

k8s-ci-robot commented Nov 21, 2024

netlify bot commented Nov 21, 2024 • edited Loading

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

netlify bot commented Nov 21, 2024

✅ Pull request preview available for checking

netlify bot commented Nov 21, 2024

✅ Pull request preview available for checking

tengqm commented Nov 21, 2024

ffromani commented Nov 21, 2024

ffromani commented Nov 21, 2024

ffromani commented Nov 22, 2024

sftim commented Nov 22, 2024

sftim commented Nov 22, 2024

ffromani commented Nov 22, 2024

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim Nov 23, 2024 • edited Loading

Choose a reason for hiding this comment

k8s-ci-robot commented Nov 23, 2024

ffromani commented Nov 21, 2024 •

edited

Loading

netlify bot commented Nov 21, 2024 •

edited

Loading

sftim Nov 23, 2024 •

edited

Loading