New Conversion from cgroup v1 CPU Shares to v2 CPU Weight

Kubernetes was originally designed with cgroup v1 in mind, where CPU shares
were derived from a container’s CPU requests using the following formula:

$$cpu.shares = milliCPU \times \frac{1024}{1000}$$

Note that the value 1024 in this formula is the default cpu.shares value
in cgroup v1, and is unrelated to millicores. For example, a container
requesting 1 CPU (1000m) would get (cpu.shares = 1000 \times 1024 / 1000 = 1024),
and a container requesting 100m would get (cpu.shares = 100 \times 1024 / 1000 = 102).

After a while, cgroup v1 started being replaced by its successor,
cgroup v2. In cgroup v2, the concept of CPU shares (which ranges from 2 to
262144, or from 2¹ to 2¹⁸) was replaced with CPU weight (which ranges from
[1, 10000], or 10⁰ to 10⁴).

The current conversion formula creates two major issues:

In cgroup v1, the default value for CPU shares is 1024, meaning a container
requesting 1 CPU has equal priority with system processes that live outside
of Kubernetes’ scope.
However, in cgroup v2, the default CPU weight is 100, but the current
formula converts 1 CPU (1000m) to only ≈39 weight – less than 40% of the
default.

Example:

• Container requesting 1 CPU (1000m)
• cgroup v1: cpu.shares = 1024 (equal to default)
• cgroup v2 (current): cpu.weight = 39 (much lower than default 100)

This means that after moving to cgroup v2, Kubernetes (or OCI) workloads would
de-facto reduce their CPU priority against non-Kubernetes processes. The
problem can be severe for setups with many system daemons that run
outside of Kubernetes’ scope and expect Kubernetes workloads to have
priority, especially in situations of resource starvation.

The new formula is more complicated, but does a much better job mapping
between cgroup v1 CPU shares and cgroup v2 CPU weight:

$$cpu.weight = \lceil 10^{(L^{2}/612 + 125L/612 – 7/34)} \rceil, \text{ where: } L = \log_2(cpu.shares)$$

The idea is that this is a quadratic function to cross the following values:

• (2, 1): The minimum values for both ranges.
• (1024, 100): The default values for both ranges.
• (262144, 10000): The maximum values for both ranges.

Visually, the new function looks as follows:

And if you zoom in to the important part:

The new formula is “close to linear”, yet it is carefully designed to
map the ranges in a clever way so the three important points above would
cross.

This change was implemented at the OCI layer.
In other words, this is not implemented in Kubernetes itself; therefore the
adoption of the new conversion formula depends solely on the OCI runtime
adoption.

For example:

Important: Some consumers may be affected if they assume the older linear conversion formula.
Applications or monitoring tools that directly calculate expected CPU weight values based on the
previous formula may need updates to account for the new quadratic conversion.
This is particularly relevant for:

• Custom resource management tools that predict CPU weight values.
• Monitoring systems that validate or expect specific weight values.
• Applications that programmatically set or verify CPU weight values.

Also note that reversing the conversion from cpu.weight back to milliCPU
will not always yield the exact original value. There are two sources of
information loss: the milliCPU to cpu.shares conversion involves integer
truncation (e.g. 100m becomes 102 shares, not 102.4), and more significantly,
the shares-to-weight mapping is many-to-one (e.g. milliCPU values 90
through 109 all map to cpu.weight = 17). Tools that need precise CPU
request values should read them directly from the pod spec rather than
deriving them from cgroup parameters.

The Kubernetes project recommends testing the new conversion formula in non-production
environments before upgrading OCI runtimes to ensure compatibility with existing tooling.

For those interested in this enhancement: