[pve-devel] [PATCH docs 1/3] qm: resource limits: revise section cpulimit

[pve-devel] [PATCH docs 1/3] qm: resource limits: revise section cpulimit

[Alexander Zeidler]

* precise statements
* increase compactness w/o complexity
* improve section-formatting

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 qm.adoc | 40 +++++++++++++++++++++-------------------
 1 file changed, 21 insertions(+), 19 deletions(-)

diff --git a/qm.adoc b/qm.adoc
index c2392f3..268a635 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -336,31 +336,33 @@ context switches.
 Resource Limits
 ^^^^^^^^^^^^^^^
 
-In addition to the number of virtual cores, you can configure how much resources
-a VM can get in relation to the host CPU time and also in relation to other
-VMs.
-With the *cpulimit* (``Host CPU Time'') option you can limit how much CPU time
-the whole VM can use on the host. It is a floating point value representing CPU
-time in percent, so `1.0` is equal to `100%`, `2.5` to `250%` and so on. If a
-single process would fully use one single core it would have `100%` CPU Time
-usage. If a VM with four cores utilizes all its cores fully it would
-theoretically use `400%`. In reality the usage may be even a bit higher as QEMU
-can have additional threads for VM peripherals besides the vCPU core ones.
+*cpulimit*
+
+In addition to the number of virtual cores, the total available ``Host CPU
+Time'' for the VM can be set with the *cpulimit* option. It is a floating point
+value representing CPU time in percent, so `1.0` is equal to `100%`, `2.5` to
+`250%` and so on. If a single process would fully use one single core it would
+have `100%` CPU Time usage. If a VM with four cores utilizes all its cores
+fully it would theoretically use `400%`. In reality the usage may be even a bit
+higher as QEMU can have additional threads for VM peripherals besides the vCPU
+core ones.
+
 This setting can be useful if a VM should have multiple vCPUs, as it runs a few
 processes in parallel, but the VM as a whole should not be able to run all
-vCPUs at 100% at the same time. Using a specific example: lets say we have a VM
-which would profit from having 8 vCPUs, but at no time all of those 8 cores
-should run at full load - as this would make the server so overloaded that
-other VMs and CTs would get to less CPU. So, we set the *cpulimit* limit to
-`4.0` (=400%). If all cores do the same heavy work they would all get 50% of a
-real host cores CPU time. But, if only 4 would do work they could still get
-almost 100% of a real core each.
+vCPUs at 100% at the same time.
+
+Using a specific example: lets say we have a VM which would profit from having
+8 vCPUs, but at no time all of those 8 cores should run at full load - as this
+would make the server so overloaded that other VMs and CTs would get too less
+CPU. So, we set the *cpulimit* limit to `4.0` (=400%). If we now fully utilize
+all 8 vCPUs, they will receive maximum 50% CPU time of the physical cores. But
+with only 4 vCPUs fully utilized, they could still get up to 100% CPU time.
 
 NOTE: VMs can, depending on their configuration, use additional threads, such
 as for networking or IO operations but also live migration. Thus a VM can show
 up to use more CPU time than just its virtual CPUs could use. To ensure that a
-VM never uses more CPU time than virtual CPUs assigned set the *cpulimit*
-setting to the same value as the total core count.
+VM never uses more CPU time than vCPUs assigned, set the *cpulimit* to
+the same value as the total core count.
 
 The second CPU resource limiting setting, *cpuunits* (nowadays often called CPU
 shares or CPU weight), controls how much CPU time a VM gets compared to other
-- 
2.39.2

[pve-devel] [PATCH docs 2/3] qm: resource limits: revise section cpuunits

[Alexander Zeidler]

* restructure sentences minimally
* improve section-formatting

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 qm.adoc | 22 +++++++++++++---------
 1 file changed, 13 insertions(+), 9 deletions(-)

diff --git a/qm.adoc b/qm.adoc
index 268a635..15aa0fc 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -364,17 +364,21 @@ up to use more CPU time than just its virtual CPUs could use. To ensure that a
 VM never uses more CPU time than vCPUs assigned, set the *cpulimit* to
 the same value as the total core count.
 
-The second CPU resource limiting setting, *cpuunits* (nowadays often called CPU
-shares or CPU weight), controls how much CPU time a VM gets compared to other
-running VMs. It is a relative weight which defaults to `100` (or `1024` if the
-host uses legacy cgroup v1). If you increase this for a VM it will be
-prioritized by the scheduler in comparison to other VMs with lower weight. For
-example, if VM 100 has set the default `100` and VM 200 was changed to `200`,
-the latter VM 200 would receive twice the CPU bandwidth than the first VM 100.
+*cpuuntis*
+
+With the *cpuunits* option, nowadays often called CPU shares or CPU weight, you
+can control how much CPU time a VM gets compared to other running VMs. It is a
+relative weight which defaults to `100` (or `1024` if the host uses legacy
+cgroup v1). If you increase this for a VM it will be prioritized by the
+scheduler in comparison to other VMs with lower weight.
+
+For example, if VM 100 has set the default `100` and VM 200 was changed to
+`200`, the latter VM 200 would receive twice the CPU bandwidth than the first
+VM 100.
 
 For more information see `man systemd.resource-control`, here `CPUQuota`
-corresponds to `cpulimit` and `CPUWeight` corresponds to our `cpuunits`
-setting, visit its Notes section for references and implementation details.
+corresponds to `cpulimit` and `CPUWeight` to our `cpuunits` setting. Visit its
+Notes section for references and implementation details.
 
 The third CPU resource limiting setting, *affinity*, controls what host cores
 the virtual machine will be permitted to execute on. E.g., if an affinity value
-- 
2.39.2

[pve-devel] [PATCH docs 3/3] qm: resource limits: revise section affinity

[Alexander Zeidler]

* mention side effects
* increase compactness w/o complexity
* improve section-formatting

Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
---
 qm.adoc | 32 ++++++++++++++++++--------------
 1 file changed, 18 insertions(+), 14 deletions(-)

diff --git a/qm.adoc b/qm.adoc
index 15aa0fc..d92db75 100644
--- a/qm.adoc
+++ b/qm.adoc
@@ -380,20 +380,24 @@ For more information see `man systemd.resource-control`, here `CPUQuota`
 corresponds to `cpulimit` and `CPUWeight` to our `cpuunits` setting. Visit its
 Notes section for references and implementation details.
 
-The third CPU resource limiting setting, *affinity*, controls what host cores
-the virtual machine will be permitted to execute on. E.g., if an affinity value
-of `0-3,8-11` is provided, the virtual machine will be restricted to using the
-host cores `0,1,2,3,8,9,10,` and `11`. Valid *affinity* values are written in
-cpuset `List Format`. List Format is a comma-separated list of CPU numbers and
-ranges of numbers, in ASCII decimal.
-
-NOTE: CPU *affinity* uses the `taskset` command to restrict virtual machines to
-a given set of cores. This restriction will not take effect for some types of
-processes that may be created for IO. *CPU affinity is not a security feature.*
-
-For more information regarding *affinity* see `man cpuset`. Here the
-`List Format` corresponds to valid *affinity* values. Visit its `Formats`
-section for more examples.
+*affinity*
+
+With the *affinity* option you can specify the physical CPU cores which are
+used to run the VM's vCPUs. Periphal VM processes, such as those for I/O, are
+not affected by this setting. Note that the *CPU affinity is not a security
+feature*.
+
+Forcing a CPU *affinity* can make sense in certain cases, but is accompanied by
+an increase in complexity and maintenance effort. For example, if you want to
+add more VMs later or migrate VMs to nodes with fewer CPU cores. It can also
+easily lead to asynchronous and therefore limited system performance if some
+CPUs are fully utilized while others are almost idle.
+
+The *affinity* is set by calling `taskset`. It accepts the host CPU numbers
+(see `lscpu`) in the `List Format` from `man cpuset`. This ASCII decimal list
+can contain numbers but also number ranges. E.g., the *affinity* `0-1,8-11` (or
+alternatively `0,1,8,9,10,11`) only allow the VM to run on these six host
+cores.
 
 CPU Type
 ^^^^^^^^
-- 
2.39.2

[pve-devel] applied-series: [PATCH docs 1/3] qm: resource limits: revise section cpulimit

[Thomas Lamprecht]

Am 16/01/2024 um 14:22 schrieb Alexander Zeidler:
> * precise statements
> * increase compactness w/o complexity
> * improve section-formatting
> 
> Signed-off-by: Alexander Zeidler <a.zeidler@proxmox.com>
> ---
>  qm.adoc | 40 +++++++++++++++++++++-------------------
>  1 file changed, 21 insertions(+), 19 deletions(-)
> 
>

applied all three patches, but pushed some further typo fixes and rewording
for the cpulimit and affinity sections on top, thanks!