Skip to content

Commit 5284543

Browse files
rohennesrohennes
committed
Refactoring the performance profile section for the content improvement initiative
1 parent d758c5a commit 5284543

10 files changed

+347
-212
lines changed

‎modules/cnf-about-the-profile-creator-tool.adoc

Lines changed: 19 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,25 @@
66
[id="cnf-about-the-profile-creator-tool_{context}"]
77
= About the Performance Profile Creator
88

9-
The Performance Profile Creator (PPC) is a command-line tool, delivered with the Node Tuning Operator, used to create the performance profile.
10-
The tool consumes `must-gather` data from the cluster and several user-supplied profile arguments. The PPC generates a performance profile that is appropriate for your hardware and topology.
9+
The Performance Profile Creator (PPC) is a command-line tool, delivered with the Node Tuning Operator, that can help you to create a performance profile for your cluster.
1110

12-
The tool is run by one of the following methods:
11+
Initially, you can use the PPC tool to process the `must-gather` data to display key performance configurations for your cluster, including the following information:
1312

14-
* Invoking `podman`
13+
* NUMA cell partitioning with the allocated CPU IDs
14+
* Hyper-Threading node configuration
1515
16-
* Calling a wrapper script
16+
You can use this information to help you configure the performance profile.
17+
18+
.Running the PPC
19+
Specify performance configuration arguments to the PPC tool to generate a proposed performance profile that is appropriate for your hardware, topology, and use-case.
20+
21+
You can run the PPC by using one of the following methods:
22+
23+
* Run the PPC by using Podman
24+
25+
* Run the PPC by using the wrapper script
26+
27+
[NOTE]
28+
====
29+
Using the wrapper script abstracts some of the more granular Podman tasks into an executable script. For example, the wrapper script handles tasks such as pulling and running the required container image, mounting directories into the container, and providing parameters directly to the container through Podman. Both methods achieve the same result.
30+
====

‎modules/cnf-creating-mcp-for-ppc.adoc

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * scalability_and_performance/low_latency_tuning/cnf-tuning-low-latency-nodes-with-perf-profile.adoc
4+
5+
:_mod-docs-content-type: PROCEDURE
6+
[id="creating-mcp-for-ppc_{context}"]
7+
= Creating a machine config pool to target nodes for performance tuning
8+
9+
For multi-node clusters, you can define a machine config pool (MCP) to identify the target nodes that you want to configure with a performance profile.
10+
11+
In {sno} clusters, you must use the `master` MCP because there is only one node in the cluster. You do not need to create a separate MCP for {sno} clusters.
12+
13+
.Prerequisites
14+
15+
* You have `cluster-admin` role access.
16+
* You installed the OpenShift CLI (`oc`).
17+
18+
.Procedure
19+
20+
. Label the target nodes for configuration by running the following command:
21+
+
22+
[source,terminal]
23+
----
24+
$ oc label node <node_name> node-role.kubernetes.io/worker-cnf="" <1>
25+
----
26+
<1> Replace `<node_name>` with the name of your node. This example applies the `worker-cnf` label.
27+
28+
. Create a `MachineConfigPool` resource containing the target nodes:
29+
30+
.. Create a YAML file that defines the `MachineConfigPool` resource:
31+
+
32+
.Example `mcp-worker-cnf.yaml` file
33+
[source,yaml]
34+
----
35+
apiVersion: machineconfiguration.openshift.io/v1
36+
kind: MachineConfigPool
37+
metadata:
38+
name: worker-cnf <1>
39+
labels:
40+
machineconfiguration.openshift.io/role: worker-cnf <2>
41+
spec:
42+
machineConfigSelector:
43+
matchExpressions:
44+
- {
45+
key: machineconfiguration.openshift.io/role,
46+
operator: In,
47+
values: [worker, worker-cnf],
48+
}
49+
paused: false
50+
nodeSelector:
51+
matchLabels:
52+
node-role.kubernetes.io/worker-cnf: "" <3>
53+
----
54+
<1> Specify a name for the `MachineConfigPool` resource.
55+
<2> Specify a unique label for the machine config pool.
56+
<3> Specify the nodes with the target label that you defined.
57+
58+
.. Apply the `MachineConfigPool` resource by running the following command:
59+
+
60+
[source,terminal]
61+
----
62+
$ oc apply -f mcp-worker-cnf.yaml
63+
----
64+
+
65+
.Example output
66+
[source,terminal]
67+
----
68+
machineconfigpool.machineconfiguration.openshift.io/worker-cnf created
69+
----
70+
71+
.Verification
72+
73+
* Check the machine config pools in your cluster by running the following command:
74+
+
75+
[source,terminal]
76+
----
77+
$ oc get mcp
78+
----
79+
+
80+
.Example output
81+
[source,terminal]
82+
----
83+
NAME CONFIG UPDATED UPDATING DEGRADED MACHINECOUNT READYMACHINECOUNT UPDATEDMACHINECOUNT DEGRADEDMACHINECOUNT AGE
84+
master rendered-master-58433c7c3c1b4ed5ffef95234d451490 True False False 3 3 3 0 6h46m
85+
worker rendered-worker-168f52b168f151e4f853259729b6azc4 True False False 2 2 2 0 6h46m
86+
worker-cnf rendered-worker-cnf-168f52b168f151e4f853259729b6azc4 True False False 1 1 1 0 73s
87+
----

‎modules/cnf-gathering-data-about-cluster-using-must-gather.adoc

Lines changed: 7 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -4,39 +4,18 @@
44

55
:_mod-docs-content-type: PROCEDURE
66
[id="gathering-data-about-your-cluster-using-must-gather_{context}"]
7-
= Gathering data about your cluster using the must-gather command
7+
= Gathering data about your cluster for the PPC
88

99
The Performance Profile Creator (PPC) tool requires `must-gather` data. As a cluster administrator, run the `must-gather` command to capture information about your cluster.
1010

1111
.Prerequisites
1212

1313
* Access to the cluster as a user with the `cluster-admin` role.
14-
* The OpenShift CLI (`oc`) installed.
14+
* You installed the OpenShift CLI (`oc`).
15+
* You identified a target MCP that you want to configure with a performance profile.
1516
1617
.Procedure
1718

18-
. Optional: Verify that a matching machine config pool exists with a label:
19-
+
20-
[source,terminal]
21-
----
22-
$ oc describe mcp/worker-rt
23-
----
24-
+
25-
.Example output
26-
[source,terminal]
27-
----
28-
Name: worker-rt
29-
Namespace:
30-
Labels: machineconfiguration.openshift.io/role=worker-rt
31-
----
32-
33-
. If a matching label does not exist add a label for a machine config pool (MCP) that matches with the MCP name:
34-
+
35-
[source,terminal]
36-
----
37-
$ oc label mcp <mcp_name> machineconfiguration.openshift.io/role=<mcp_name>
38-
----
39-
4019
. Navigate to the directory where you want to store the `must-gather` data.
4120

4221
. Collect cluster information by running the following command:
@@ -45,13 +24,16 @@ $ oc label mcp <mcp_name> machineconfiguration.openshift.io/role=<mcp_name>
4524
----
4625
$ oc adm must-gather
4726
----
27+
+
28+
The command creates a folder with the `must-gather` data in your local directory with a naming format similar to the following: `must-gather.local.1971646453781853027`.
4829

4930
. Optional: Create a compressed file from the `must-gather` directory:
5031
+
5132
[source,terminal]
5233
----
53-
$ tar cvaf must-gather.tar.gz must-gather/
34+
$ tar cvaf must-gather.tar.gz <must_gather_folder> <1>
5435
----
36+
<1> Replace with the name of the `must-gather` data folder.
5537
+
5638
[NOTE]
5739
====

‎modules/cnf-how-run-podman-to-create-profile.adoc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
[id="how-to-run-podman-to-create-a-profile_{context}"]
66
= How to run podman to create a performance profile
7-
7+
// Is this example required for a specific reason?
88
The following example illustrates how to run `podman` to create a performance profile with 20 reserved CPUs that are to be split across the NUMA nodes.
99

1010
Node hardware configuration:
@@ -18,7 +18,7 @@ Run `podman` to create the performance profile:
1818

1919
[source,terminal,subs="attributes+"]
2020
----
21-
$ podman run --entrypoint performance-profile-creator -v /must-gather:/must-gather:z registry.redhat.io/openshift4/ose-cluster-node-tuning-operator:v{product-version} --mcp-name=worker-cnf --reserved-cpu-count=20 --rt-kernel=true --split-reserved-cpus-across-numa=true --must-gather-dir-path /must-gather > my-performance-profile.yaml
21+
$ podman run --entrypoint performance-profile-creator -v /must-gather:/must-gather:z registry.redhat.io/openshift4/ose-cluster-node-tuning-operator:latest --mcp-name=worker-cnf --reserved-cpu-count=20 --rt-kernel=true --split-reserved-cpus-across-numa=true --must-gather-dir-path /must-gather > my-performance-profile.yaml
2222
----
2323

2424
The created profile is described in the following YAML:

‎modules/cnf-performance-profile-creator-arguments.adoc

Lines changed: 36 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -6,62 +6,72 @@
66
[id="performance-profile-creator-arguments_{context}"]
77
= Performance Profile Creator arguments
88

9-
.Performance Profile Creator arguments
9+
.Required Performance Profile Creator arguments
10+
[cols="30%,70%",options="header"]
11+
|===
12+
| Argument | Description
13+
14+
| `mcp-name`
15+
|Name for MCP; for example, `worker-cnf` corresponding to the target machines.
16+
17+
| `must-gather-dir-path`
18+
| The path of the must gather directory.
19+
20+
This argument is only required if you run the PPC tool by using Podman. If you use the PPC with the wrapper script, do not use this argument. Instead, specify the directory path to the `must-gather` tarball by using the `-t` option for the wrapper script.
21+
22+
| `reserved-cpu-count`
23+
| Number of reserved CPUs. Use a natural number greater than zero.
24+
25+
| `rt-kernel`
26+
| Enables real-time kernel.
27+
28+
Possible values: `true` or `false`.
29+
30+
|===
31+
32+
.Optional Performance Profile Creator arguments
1033
[cols="30%,70%",options="header"]
1134
|===
1235
| Argument | Description
1336

1437
| `disable-ht`
15-
a|Disable hyperthreading.
38+
a|Disable Hyper-Threading.
1639

1740
Possible values: `true` or `false`.
1841

1942
Default: `false`.
2043

2144
[WARNING]
2245
====
23-
If this argument is set to `true` you should not disable hyperthreading in the BIOS. Disabling hyperthreading is accomplished with a kernel command line argument.
46+
If this argument is set to `true` you should not disable Hyper-Threading in the BIOS. Disabling Hyper-Threading is accomplished with a kernel command line argument.
2447
====
2548

26-
| --enable-hardware-tuning
49+
|enable-hardware-tuning
2750
a|Enable the setting of maximum CPU frequencies.
28-
This parameter is optional.
2951

30-
To enable this feature, set the maximum frequency for applications running on isolated and reserved CPUs for both of the following:
52+
To enable this feature, set the maximum frequency for applications running on isolated and reserved CPUs for both of the following fields:
3153

3254
* `spec.hardwareTuning.isolatedCpuFreq`
3355
* `spec.hardwareTuning.reservedCpuFreq`
56+
57+
This is an advanced feature. If you configure hardware tuning, the generated `PerformanceProfile` includes warnings and guidance on how to set frequency settings.
3458

3559
| `info`
36-
a| This captures cluster information and is used in discovery mode only. Discovery mode also requires the `must-gather-dir-path` argument. If any other arguments are set they are ignored.
60+
a| This captures cluster information. This argument also requires the `must-gather-dir-path` argument. If any other arguments are set they are ignored.
3761

3862
Possible values:
3963

4064
* `log`
4165
* `JSON`
4266

43-
+
44-
[NOTE]
45-
====
46-
These options define the output format with the JSON format being reserved for debugging.
47-
====
48-
4967
Default: `log`.
5068

51-
| `mcp-name`
52-
|MCP name for example `worker-cnf` corresponding to the target machines. This parameter is required.
53-
54-
| `must-gather-dir-path`
55-
| Must gather directory path. This parameter is required.
56-
57-
When the user runs the tool with the wrapper script `must-gather` is supplied by the script itself and the user must not specify it.
58-
5969
| `offlined-cpu-count`
6070
a| Number of offlined CPUs.
6171

6272
[NOTE]
6373
====
64-
This must be a natural number greater than 0. If not enough logical processors are offlined then error messages are logged. The messages are:
74+
Use a natural number greater than zero. If not enough logical processors are offlined, then error messages are logged. The messages are:
6575
[source,terminal]
6676
----
6777
Error: failed to compute the reserved and isolated CPUs: please ensure that reserved-cpu-count plus offlined-cpu-count should be in the range [0,1]
@@ -77,8 +87,8 @@ a|The power consumption mode.
7787

7888
Possible values:
7989

80-
* `default`: CPU partitioning with enabled power management and basic low-latency.
81-
* `low-latency`: Enhanced measures to improve latency figures.
90+
* `default`: Performance achieved through CPU partitioning only.
91+
* `low-latency`: Enhanced measures to improve latency.
8292
* `ultra-low-latency`: Priority given to optimal latency, at the expense of power management.
8393

8494
Default: `default`.
@@ -92,20 +102,8 @@ Default: `false`.
92102

93103
| `profile-name`
94104
| Name of the performance profile to create.
95-
Default: `performance`.
96-
97-
| `reserved-cpu-count`
98-
a| Number of reserved CPUs. This parameter is required.
99105

100-
[NOTE]
101-
====
102-
This must be a natural number. A value of 0 is not allowed.
103-
====
104-
105-
| `rt-kernel`
106-
| Enable real-time kernel. This parameter is required.
107-
108-
Possible values: `true` or `false`.
106+
Default: `performance`.
109107

110108
| `split-reserved-cpus-across-numa`
111109
| Split the reserved CPUs across NUMA nodes.
@@ -131,4 +129,4 @@ Default: `restricted`.
131129
Possible values: `true` or `false`.
132130

133131
Default: `false`.
134-
|===
132+
|===

0 commit comments

Comments
 (0)