How --cpu-share actually works in pod level?

[RyougiShiki-214]

Suppose we created pods foo and bar with the cpu share settings in this table:

Detailed command

sudo podman pod create \
    --name foo \
    --cpu-shares 512

sudo podman run -d \
    --pod foo \
    --name a \
    my/container:latest

sudo podman run -d \
    --pod foo \
    --name b \
    my/container:latest

sudo podman run -d \
    --pod foo \
    --name c \
    my/container:latest

sudo podman pod create \
    --name bar \
    --cpu-shares 512

sudo podman run -d \
    --pod bar \
    --name a \
    --cpu-shares 2048 \
    my/container:latest

sudo podman run -d \
    --pod bar \
    --name b \
    my/container:latest

sudo podman run -d \
    --pod bar \
    --name c \
    my/container:latest

Pod foo (Pod level set --cpu-share 512)

container	--cpu-shares
a	default
b	default
c	default

Pod bar (Pod level set --cpu-share 512)

container	--cpu-shares
a	2048
b	default
c	default

Now, suppose there's X unit of cpu time in total for podman, how --cpu-share actually works? There are 4 guesses:

1. foo and containers in foo get 50% X in total, bar and containers in bar get 50% X in total. Then containers divide up the cpu time got by their pod, the default --cpu-share of container is 1024:
   Pod foo got 50%X in total

   container	--cpu-shares	CPU time
   a	default (1024)	50%[1024/(1024+1024+1024)] = 16.7% X
   b	default (1024)	50%[1024/(1024+1024+1024)] = 16.7% X
   c	default (1024)	50%[1024/(1024+1024+1024)] = 16.7% X

   Pod bar got 50%X in total

   container	--cpu-shares	CPU time
   a	2048	50%[2048/(2048+1024+1024)] = 25% X
   b	default (1024)	50%[1024/(2048+1024+1024)] = 12.5% X
   c	default (1024)	50%[1024/(2048+1024+1024)] = 12.5% X

2. foo and containers in foo get 50% X in total, bar and containers in bar get 50% X in total. Then containers divide up the cpu time got by their pod, the default --cpu-share of container is Pod's --cpu-share value:
   Pod foo got 50%X in total

   container	--cpu-shares	CPU time
   a	default (512)	50%[512/(512+512+512)] = 16.7% X
   b	default (512)	50%[512/(512+512+512)] = 16.7% X
   c	default (512)	50%[512/(512+512+512)] = 16.7% X

   Pod bar got 50%X in total

   container	--cpu-shares	CPU time
   a	2048	50%[2048/(2048+512+512)] = 33.3% X
   b	default (512)	50%[512/(2048+512+512)] = 8.3% X
   c	default (512)	50%[512/(2048+512+512)] = 8.3% X

3. Pods do not get any cpu time (X). Then containers divide up the cpu time (X) directly, the default --cpu-share of container is 1024:

   container	--cpu-shares	CPU time
   foo-a	default (1024)	1024/(1024+1024+1024+2048+1024+1024) = 14.3% X
   foo-b	default (1024)	1024/(1024+1024+1024+2048+1024+1024) = 14.3% X
   foo-c	default (1024)	1024/(1024+1024+1024+2048+1024+1024) = 14.3% X
   bar-a	2048	2048/(1024+1024+1024+2048+1024+1024) = 28.6% X
   bar-b	default (1024)	1024/(1024+1024+1024+2048+1024+1024) = 14.3% X
   bar-c	default (1024)	1024/(1024+1024+1024+2048+1024+1024) = 14.3% X

4. Pods do not get any cpu time (X). Then containers divide up the cpu time (X) directly, the default --cpu-share of container is Pod's --cpu-share value:

   container	--cpu-shares	CPU time
   foo-a	default (512)	512/(512+512+512+2048+512+512) = 11.1% X
   foo-b	default (512)	512/(512+512+512+2048+512+512) = 11.1% X
   foo-c	default (512)	512/(512+512+512+2048+512+512) = 11.1% X
   bar-a	2048	2048/(512+512+512+2048+512+512) = 44.4% X
   bar-b	default (512)	512/(512+512+512+2048+512+512) = 11.1% X
   bar-c	default (512)	512/(512+512+512+2048+512+512) = 11.1% X

I tried to ask Gemini, ChatGPT, Claude Sonnet, DeepSeek, Qwen, Github Copilot, anyway their answers are different, three of them support guess 1, two of them support guess 3, and one of them support guess 4.

Generally, there has been a serious divergence of opinions among different LLMs, which made me comfused... So, I think it's time to seek help from real human.

[giuseppe]

cpu shares/weight are related to their siblings cgroups.

so if you have:

graph TD;
    A-->B;
    A-->C;
    B[B <br /> 1024] --> D[D <br /> ...];
    B --> E[E <br /> ...];
    C[C <br /> 1024] --> F[F <br /> 2048];
    C --> G[G <br /> 1024];

Loading

The weight you assign to D and E does not affect F and G at all.

B and C gets 50% each of the cpu cyles assigned to A.

F gets 2/3 of the cpu cycles assigned to C, and G gets 1/3.

[RyougiShiki-214]

cpu shares/weight are related to their siblings cgroups.

so if you have:

graph TD;
    A-->B;
    A-->C;
    B[B <br /> 1024] --> D[D <br /> ...];
    B --> E[E <br /> ...];
    C[C <br /> 1024] --> F[F <br /> 2048];
    C --> G[G <br /> 1024];

Loading

The weight you assign to D and E does not affect F and G at all.

B and C gets 50% each of the cpu cyles assigned to A.

F gets 2/3 of the cpu cycles assigned to C, and G gets 1/3.

Thanks for your reply! However I'm still not sure about the way how --cpu-share actually assign cgroups to pods and containers.

Would pods be the "parent" cgroup of it's containers:

graph TD
    CPU_Time["CPU Time"]
    Pod_A["Pod A"]
    Pod_B["Pod B"]
    Container_1["Container 1<br/>(in pod A)"]
    Container_2["Container 2<br/>(in pod A)"]
    Container_3["Container 3<br/>(in pod A)"]
    Container_4["Container 4<br/>(in pod B)"]
    Container_5["Container 5<br/>(in pod B)"]
    Container_6["Container 6<br/>(in pod B)"]
    Container_7["Container 7<br/>(not in pod)"]
    Container_8["Container 8<br/>(not in pod)"]
    Container_9["Container 9<br/>(not in pod)"]

    CPU_Time --> Pod_A
    CPU_Time --> Pod_B
    CPU_Time --> Container_7
    CPU_Time --> Container_8
    CPU_Time --> Container_9

    Pod_A --> Container_1
    Pod_A --> Container_2
    Pod_A --> Container_3

    Pod_B --> Container_4
    Pod_B --> Container_5
    Pod_B --> Container_6

Loading

Or, --cpu-share at Pod level is just a default value prepared for those containers without --cpu-share in pod. The containers have flat cgroup structure like (pods do not have a cgroup, only containers do):

graph TD
    CPU_Time["CPU Time"]
    Container_1["Container 1<br/>(in pod A)"]
    Container_2["Container 2<br/>(in pod A)"]
    Container_3["Container 3<br/>(in pod A)"]
    Container_4["Container 4<br/>(in pod B)"]
    Container_5["Container 5<br/>(in pod B)"]
    Container_6["Container 6<br/>(in pod B)"]
    Container_7["Container 7<br/>(not in pod)"]
    Container_8["Container 8<br/>(not in pod)"]
    Container_9["Container 9<br/>(not in pod)"]

    CPU_Time --> Container_1
    CPU_Time --> Container_2
    CPU_Time --> Container_3
    CPU_Time --> Container_4
    CPU_Time --> Container_5
    CPU_Time --> Container_6
    CPU_Time --> Container_7
    CPU_Time --> Container_8
    CPU_Time --> Container_9

Loading

In fact, this is precisely the focus of the debate among LLMs.

[giuseppe]

Would pods be the "parent" cgroup of it's containers:

yes

[RyougiShiki-214]

Would pods be the "parent" cgroup of it's containers:

yes

Thank you so much!
By the way, I wonder if the reason Gemini gave below makes some sense (maybe Gemini confused cgroup v1 and v2?) or is totally bullshit🤣

Gemini said

Podman would create a flat cgroup structure for all containers.

The key to understanding this is separating what the Linux kernel scheduler does from what the Podman command does for convenience.

1. How the Linux CPU Scheduler (CFS) Works: A Flat Race
   The Completely Fair Scheduler (CFS) in the Linux kernel is responsible for distributing CPU time. For cgroups, its behavior is simple and strict:

It only compares siblings. The scheduler looks at all competing cgroups at the same level and distributes CPU time based on the relative cpu.shares value of each one.

There is no "parent budget." It does not assign a chunk of CPU time to a parent cgroup (like a pod's cgroup) for it to then redistribute to its children. That two-level distribution model does not exist for the cpu.shares mechanism.

Think of it like a race. Every container is a runner. cpu.shares is the runner's "handicap" or "priority weighting." The race official (the scheduler) looks at every individual runner's handicap to decide how to manage the race. The official does not give a "team captain" (the pod) a block of energy to distribute among their runners.

This kernel-level reality makes the two-stage model described in Guess 1 impossible. Podman cannot change how the fundamental Linux scheduler works.

2. How Podman Applies the Setting: A Configuration Template
   So, what does podman pod create --cpu-shares 512 actually do?

It doesn't set a scheduler property on the pod's parent cgroup. Instead, it saves 512 as a piece of configuration metadata for that pod. It's a default value or a "template" for any container that joins the pod.

Here is the flow of logic Podman uses:

When you execute podman run --pod foo ..., Podman prepares to create the container.

It checks if you provided a --cpu-shares flag on the podman run command itself.

If YES (like for bar-a with 2048), it uses that value directly. This overrides any pod-level setting.

If NO (like for all containers in foo), Podman then checks the metadata of the pod it's joining. It sees that pod foo was configured with a default of 512, so it applies that value to the new container.

If neither the container nor the pod has a --cpu-shares value set, Podman falls back to the system default of 1024.

This means the pod's --cpu-shares setting is purely a convenience—a way to set a default for a group of containers without having to type it on every single podman run command.

Final Verdict

Guess 1 is incorrect because it describes a hierarchical, two-stage CPU allocation that the Linux CFS scheduler does not perform for cpu.shares.

Guess 4 is correct because it accurately models the real-world behavior:

The pod's setting acts as a default.

The container's setting overrides the default.

All containers compete in a single, flat pool based on their final, effective cpu.shares value, which is exactly how the kernel scheduler is designed to work.