Merge pull request #8133 from xordspar0/cpu-limit-details

[CI:DOCS] Add more details about how CPU limits work

docs/source/markdown/podman-build.1.md

@@ -111,21 +111,23 @@ network namespaces can be found.
 
 **--cpu-period**=*limit*
 
-Limit the CPU CFS (Completely Fair Scheduler) period
-
-Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify.
+Set the CPU period for the Completely Fair Scheduler (CFS), which is a
+duration in microseconds. Once the container's CPU quota is used up, it will
+not be scheduled to run until the current period ends. Defaults to 100000
+microseconds.
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see
 https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
 
 **--cpu-quota**=*limit*
 
-Limit the CPU CFS (Completely Fair Scheduler) quota
+Limit the CPU Completely Fair Scheduler (CFS) quota.
 
 Limit the container's CPU usage. By default, containers run with the full
-CPU resource. This flag tell the kernel to restrict the container's CPU usage
-to the quota you specify.
+CPU resource. The limit is a number in microseconds. If you provide a number,
+the container will be allowed to use that much CPU time until the CPU period
+ends (controllable via **--cpu-period**).
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see

docs/source/markdown/podman-create.1.md

@@ -103,21 +103,23 @@ Write the pid of the `conmon` process to a file. `conmon` runs in a separate pro
 
 **--cpu-period**=*limit*
 
-Limit the CPU CFS (Completely Fair Scheduler) period
-
-Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify.
+Set the CPU period for the Completely Fair Scheduler (CFS), which is a
+duration in microseconds. Once the container's CPU quota is used up, it will
+not be scheduled to run until the current period ends. Defaults to 100000
+microseconds.
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see
 https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
 
 **--cpu-quota**=*limit*
 
-Limit the CPU CFS (Completely Fair Scheduler) quota
+Limit the CPU Completely Fair Scheduler (CFS) quota.
 
 Limit the container's CPU usage. By default, containers run with the full
-CPU resource. This flag tell the kernel to restrict the container's CPU usage
-to the quota you specify.
+CPU resource. The limit is a number in microseconds. If you provide a number,
+the container will be allowed to use that much CPU time until the CPU period
+ends (controllable via **--cpu-period**).
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see
@@ -177,7 +179,9 @@ PID    container	CPU	CPU share
 
 **--cpus**=*number*
 
-Number of CPUs. The default is *0.0* which means no limit.
+Number of CPUs. The default is *0.0* which means no limit. This is shorthand
+for **--cpu-period** and **--cpu-quota**, so you may only set either
+**--cpus** or **--cpu-period** and **--cpu-quota**.
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see

docs/source/markdown/podman-run.1.md

@@ -118,19 +118,23 @@ Write the pid of the **conmon** process to a file. As **conmon** runs in a separ
 
 **--cpu-period**=*limit*
 
-Limit the container's CPU usage by setting CPU CFS (Completely Fair Scheduler) period.
+Set the CPU period for the Completely Fair Scheduler (CFS), which is a
+duration in microseconds. Once the container's CPU quota is used up, it will
+not be scheduled to run until the current period ends. Defaults to 100000
+microseconds.
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see
 https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
 
 **--cpu-quota**=*limit*
 
-Limit the CPU CFS (Completely Fair Scheduler) quota.
+Limit the CPU Completely Fair Scheduler (CFS) quota.
 
 Limit the container's CPU usage. By default, containers run with the full
-CPU resource. This flag tell the kernel to restrict the container's CPU usage
-to the quota you specify.
+CPU resource. The limit is a number in microseconds. If you provide a number,
+the container will be allowed to use that much CPU time until the CPU period
+ends (controllable via **--cpu-period**).
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see
@@ -188,7 +192,9 @@ division of CPU shares:
 
 **--cpus**=*number*
 
-Number of CPUs. The default is *0.0* which means no limit.
+Number of CPUs. The default is *0.0* which means no limit. This is shorthand
+for **--cpu-period** and **--cpu-quota**, so you may only set either
+**--cpus** or **--cpu-period** and **--cpu-quota**.
 
 On some systems, changing the CPU limits may not be allowed for non-root
 users. For more details, see