New Conversion from cgroup v1 CPU Shares to v2 CPU Weight
Source: Kubernetes Blog
Announcement: Improved Conversion Formula for CPU Shares → CPU Weight
We’re excited to introduce a new conversion formula that translates cgroup v1 CPU shares to cgroup v2 CPU weight. This enhancement resolves critical issues related to CPU priority allocation for Kubernetes workloads running on systems that use cgroup v2.
Background
Kubernetes was originally designed with cgroup v1 in mind, where CPU shares were defined simply by assigning the container’s CPU requests in millicpu form.
Example: a container requesting 1 CPU (1024m) would get cpu.shares = 1024.
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 262 144, i.e., (2^{1}) to (2^{18})) was replaced with CPU weight (which ranges from 1 to 10 000, i.e., (10^{0}) to (10^{4})).
With the transition to cgroup v2, KEP‑2254 introduced a conversion formula to map cgroup v1 CPU shares to cgroup v2 CPU weight:
cpu.weight = (1 + ((cpu.shares - 2) * 9999) / 262142)This formula linearly maps values from ([2^{1}, 2^{18}]) to ([10^{0}, 10^{4}]).
While this approach is simple, the linear mapping introduces several significant problems that affect both performance and configuration granularity.
Problems with the Previous Conversion Formula
The current conversion formula introduces two major issues.
Reduced priority against non‑Kubernetes workloads
-
In cgroup v1, the default value for CPU shares is
1024.
A container requesting 1 CPU (1024 m) therefore has the same priority as system processes that run outside Kubernetes. -
In cgroup v2, the default CPU weight is
100, but the current formula converts 1 CPU (1024 m) to only ≈ 39 weight – less than 40 % of the default.
Example
| Context | Setting | Value |
|---|---|---|
| Container request | 1 CPU (1024 m) | – |
| cgroup v1 | cpu.shares | 1024 (default) |
| cgroup v2 (current) | cpu.weight | 39 (much lower than default 100) |
Impact
After moving to cgroup v2, Kubernetes (or OCI) workloads lose CPU priority relative to non‑Kubernetes processes. This can be severe on nodes that run many system daemons outside of Kubernetes, especially under resource‑starved conditions.
Unmanageable granularity
The current formula yields very low values for small CPU requests, making it hard to create sub‑cgroups inside containers for fine‑grained resource distribution (see KEP #5474).
Example
| Context | Setting | Value |
|---|---|---|
| Container request | 100 m CPU | – |
| cgroup v1 | cpu.shares | 102 |
| cgroup v2 (current) | cpu.weight | 4 (too low for sub‑cgroup configuration) |
Impact
With cgroup v1, a request of 100 m CPU (102 shares) allowed reasonable allocation of CPU weight among sub‑cgroups. In cgroup v2, a weight of 4 is too coarse, preventing effective distribution of CPU resources among sub‑croups. This becomes even more critical with the upcoming support for Writable cgroups for unprivileged containers (KEP #5474).
New conversion formula
Description
The new formula is more complicated, but it does a much better job mapping between cgroup v1 CPU shares and cgroup v2 CPU weight:
[ \text{cpu.weight} = \Bigl\lceil 10^{\left(\frac{L^{2}}{612} + \frac{125L}{612} - \frac{7}{34}\right)} \Bigr\rceil, \qquad\text{where } L = \log_{2}(\text{cpu.shares}) ]
It is a quadratic function that passes through the three key points:
cgroup v1 cpu.shares | cgroup v2 cpu.weight |
|---|---|
| 2 ( minimum ) | 1 ( minimum ) |
| 1024 ( default ) | 100 ( default ) |
| 262 144 ( maximum ) | 10 000 ( maximum ) |
Visually, the new function looks as follows:
Zooming in on the important region:
The function is “close to linear,” yet it is carefully designed so that the three important points above line up exactly.
How it solves the problems
Better priority alignment
A container requesting 1 CPU (1024 m) now receives
cpu.weight = 102which is close to cgroup v2’s default weight of 100. This restores the intended priority relationship between Kubernetes workloads and system processes.
Improved granularity
A container requesting 100 m CPU gets
cpu.weight = 17(see the demonstration here). This enables finer‑grained resource distribution within containers.
Adoption and integration
This change was implemented at the OCI layer. In other words, it is not implemented in Kubernetes itself; therefore, the adoption of the new conversion formula depends solely on the OCI runtime adoption.
Supported runtimes
| Runtime | Version that enables the new formula |
|---|---|
runc | v1.3.2 – release notes |
crun | v1.23 – release notes |
Impact on existing deployments
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.
Relevant scenarios include:
- 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.
The Kubernetes project recommends testing the new conversion formula in non‑production environments before upgrading OCI runtimes to ensure compatibility with existing tooling.
Where can I learn more?
- Kubernetes GitHub Issue #131216 – Detailed technical analysis and examples, including discussions and reasoning for choosing the above formula.
- KEP‑2254: cgroup v2 – Original cgroup v2 implementation in Kubernetes.
- Kubernetes cgroup documentation – Current resource‑management guidance.
How do I get involved?
If you’re interested in contributing to Kubernetes node‑level features, join the Kubernetes Node Special Interest Group (SIG‑Node).
We welcome new contributors and diverse perspectives on resource‑management challenges.