Skip to content

Commit bc84855

Browse files
rohennesrohennes
committed
TELCODOCS-1512: Adding content for new feature that enables defining shared CPUs in the performance profile
1 parent ff18e46 commit bc84855

File tree

4 files changed

+219
-0
lines changed

4 files changed

+219
-0
lines changed

‎_topic_maps/_topic_map.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2709,6 +2709,9 @@ Topics:
27092709
- Name: Creating a performance profile
27102710
File: cnf-create-performance-profiles
27112711
Distros: openshift-origin,openshift-enterprise
2712+
- Name: Shared CPUs for peripheral workload tasks
2713+
File: cnf-shared-cpu-for-workloads
2714+
Distros: openshift-origin,openshift-enterprise
27122715
- Name: Workload partitioning
27132716
File: enabling-workload-partitioning
27142717
Distros: openshift-origin,openshift-enterprise

‎modules/configuring-a-workload-to-use-shared-cpus.adoc‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="configuring-a-workload-to-use-shared-cpus_{context}"]
4+
= Configuring a workload to use shared CPUs
5+
6+
You can pin lightweight workload tasks to shared CPUs to improve CPU resource efficiency. When you enable shared CPUs on a node, containers deployed on the node feature the `OPENSHIFT_SHARED_CPUS` environment variable, which specifies the ID of the shared CPUs.
7+
8+
You can use this environment variable to pin application threads to shared CPUs.
9+
10+
.Prerequisites
11+
12+
* Log in as a user with `cluster-admin` privileges.
13+
14+
* You defined and enabled shared CPUs by using a performance profile.
15+
16+
.Procedure
17+
18+
. Create a `Pod` resource that requests shared CPUs:
19+
20+
.. Create a YAML file that defines the `Pod` resource:
21+
+
22+
.Example `shared-cpu-pod.yaml` file
23+
[source,yaml]
24+
----
25+
kind: Pod
26+
metadata:
27+
name: dpdk-pod
28+
spec:
29+
containers:
30+
- name: dpdk-cnt
31+
resources:
32+
requests:
33+
cpu: “2” <1>
34+
memory: “100m”
35+
openshift.io/shared-cpus: ”1” <2>
36+
limits:
37+
cpu: “2”
38+
memory: “100m”
39+
openshift.io/shared-cpus: ”1”
40+
----
41+
<1> Specify the number of cores required.
42+
<2> This is a boolean field to enable shared CPUs for the pod. Enter `1` to enable shared CPUs. The shared CPUs feature is disabled by default.
43+
44+
.. Create the `Pod` resource by running the following command:
45+
+
46+
[source,terminal]
47+
----
48+
$ oc create -f shared-cpu-pod.yaml
49+
----
50+
+
51+
.Example output
52+
[source,terminal]
53+
----
54+
pod/dpdk-pod created created
55+
----
56+
57+
. View the environment varialbe so you can pin lightweight tasks in your application to the shared CPU:
58+
59+
.. Start an interactive shell within the target container:
60+
+
61+
[source,terminal]
62+
----
63+
$ oc exec -it dpdk-pod -- /bin/sh
64+
----
65+
66+
.. View the environment variables within the container by running the following command:
67+
+
68+
[source,terminal]
69+
----
70+
# printenv
71+
----
72+
+
73+
.Example output
74+
[source,terminal]
75+
----
76+
...
77+
HOSTNAME=example-pod
78+
HOME=/root
79+
...
80+
OPENSHIFT_SHARED_CPUS=<CPU-ID> <1>
81+
...
82+
----
83+
<1> You can pin lightweight application threads to the CPU ID in the `OPENSHIFT_SHARED_CPUS` environment variable.

‎modules/configuring-shared-cpus-for-a-workload.adoc‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="configuring-shared-cpus-for-a-workload_{context}"]
4+
= Configuring shared CPUs in a performance profile
5+
6+
You can define and enable shared CPUs by using a performance profile. You can use these shared CPUs for lightweight application tasks.
7+
8+
.Prerequisites
9+
10+
* Log in as a user with `cluster-admin` privileges.
11+
12+
.Procedure
13+
14+
. Create a `PerformanceProfile` resource:
15+
16+
.. Create a YAML file that defines the `PerformanceProfile` resource:
17+
+
18+
.Example `shared-cpu-pp.yaml` file
19+
[source,yaml]
20+
----
21+
apiVersion: performance.openshift.io/v2
22+
kind: PerformanceProfile
23+
metadata:
24+
name: example-shared-cpu-pp
25+
spec:
26+
cpu:
27+
reserved: "0-1"
28+
isolated: "4-8"
29+
shared: "2-3" <1>
30+
workloadHints:
31+
mixedCpus: true <2>
32+
nodeSelector:
33+
node-role.kubernetes.io/performance: "test"
34+
----
35+
<1> Define the shared CPU cores. The number of shared cores must be less than the number of reserved cores.
36+
<2> Enable the shared CPUs feature by enabling on the `mixedCpus` workload hint.
37+
38+
.. Create the `PerformanceProfile` resource by running the following command:
39+
+
40+
[source,bash]
41+
----
42+
$ oc create -f shared-cpu-pp.yaml
43+
----
44+
+
45+
.Example output
46+
[source,terminal]
47+
----
48+
performanceprofile.performance.openshift.io/example-shared-cpu-pp created
49+
----
50+
51+
52+
.Verification
53+
54+
. Verify that the performance profile is active by running the following command:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc describe performanceprofile example-shared-cpu-pp
59+
----
60+
+
61+
.Example output
62+
[source,terminal]
63+
----
64+
...
65+
Events:
66+
Type Reason Age From Message
67+
---- ------ ---- ---- -------
68+
Normal Creation succeeded 27m (x17 over 35m) performance-profile-controller Succeeded to create all components
69+
----
70+
71+
. Verify the shared CPUs are present under the `reservedSystemCPUs` pool:
72+
73+
.. Enter into a debug session on the target node:
74+
+
75+
[source,terminal]
76+
----
77+
$ oc debug node/<node_name>
78+
----
79+
80+
.. Set `/host` as the root directory within the debug shell prompt.
81+
+
82+
[source,terminal]
83+
----
84+
sh-4.4# chroot /host
85+
----
86+
87+
.. Check that the `reservedSystemCPUs` pool includes the `shared` and `reserved` CPUs by running the following command:
88+
+
89+
[source,terminal]
90+
----
91+
sh-5.1# cat /etc/kubernetes/kubelet.conf | grep "reservedSystemCPUs"
92+
----
93+
+
94+
.Example output
95+
[source,terminal]
96+
----
97+
"reservedSystemCPUs": "0-3",
98+
----
99+
100+
[role="_additional-resources"]
101+
.Next steps
102+
103+
* [link to assigning workload tasks to shared CPUs - overkill?]

‎scalability_and_performance/cnf-shared-cpu-for-workloads.adoc‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="cnf-shared-cpu-for-workloads"]
3+
= Optimize compute resources by using shared CPUs
4+
include::_attributes/common-attributes.adoc[]
5+
:context: cnf-shared-cpu-for-workloads
6+
7+
toc::[]
8+
9+
Within high-performance workloads, some lightweight application tasks can occupy valuable CPU resources. For example, log printing or configuration processing can occupy an isolated core that could be used for critical workload demands. You can increase workload performance, and more efficiently use CPU resources, by moving lightweight application tasks to a set of shared CPUs.
10+
11+
You can define a set of shared CPUs by using a performance profile. When you enable shared CPUs, the kublet's `reservedSystemCpus` pool is internally partitioned into a `shared` CPU pool and a `reserved` CPU pool.
12+
13+
Shared CPUs can process system housekeeping tasks and lightweight workload tasks. In contrast, reserved CPUs only process system housekeeping tasks. This ensures no added latency in system housekeeping tasks, while minor latency in peripheral workload tasks is acceptable.
14+
15+
A typical use-case for shared CPUs is Data Plane Development Kit (DPDK) applications. DPDK applications require intensive data processing, such as packet forwarding, routing, and network function virtualization (NFV). Moving peripheral DPDK application tasks to a set of shared CPUs prevents lightweight tasks from monopolizing isolated cores meant for critical workload processing.
16+
17+
[NOTE]
18+
====
19+
System housekeeping tasks can only run on shared CPUs when workload partitioning is disabled.
20+
====
21+
22+
include::modules/configuring-shared-cpus-for-a-workload.adoc[leveloffset=+1]
23+
24+
include::modules/configuring-a-workload-to-use-shared-cpus.adoc[leveloffset=+1]
25+
26+
27+
[id="{context}-additional-resources"]
28+
[role="_additional-resources"]
29+
== Additional resources
30+
* For more information about xyz

0 commit comments

Comments
 (0)