docs: Specify resource_limits shape for CPU quota - #29490
Open
dom-calautti wants to merge 1 commit into
Open
Conversation
… API
This issue was originally reported back in 2023. A maintainer suggested it
was really just a docs gap, so this fixes that.
Reporter posted "cpu_quota" in the create body for /libpod/containers/create,
following the naming of the --cpu-quota CLI flag, and it got silently
ignored - the container was created fine, but the quota was never applied.
Turns out there's no top-level cpu_quota field on this endpoint at all.
The libpod create endpoint decodes into SpecGenerator, and CPU limits there
live under the nested OCI runtime-spec shape:
"resource_limits": {"cpu": {"quota": <value>}}. The flat "cpu_quota" field
only exists on the separate Docker-compatible /containers/create endpoint,
so it's an easy mix-up if you're going off the CLI flag name.
Verified with both a build from this branch and manual API calls: the flat
field is silently dropped, the nested one works as expected.
Added the correct shape as a comment on ResourceLimits in specgen.go, since
that's what the libpod create endpoint's generated Swagger docs are sourced
from.
Fixes: podman-container-tools#19764
Signed-off-by: Domenico Calautti <domeniccalautti@gmail.com>
mheon
reviewed
Aug 13, 2026
| // Can only be set as root on cgroups v1 systems, but can be set as | ||
| // rootless as well for cgroups v2. | ||
| // Optional. | ||
| // This follows the OCI runtime-spec LinuxResources layout, e.g. set a |
Contributor
There was a problem hiding this comment.
This should probably go in the API swagger documentation, not here - doesn't make much sense to describe it with JSON payloads in documentation for local usage
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
… API
Reporter posted "cpu_quota" in the create body for /libpod/containers/create, following the naming of the --cpu-quota CLI flag, and it got silently ignored.
The container was created fine, but the quota was never applied.
There's no top-level cpu_quota field on this endpoint at all. The flat "cpu_quota" field only exists on the separate Docker-compatible /containers/create endpoint, so it's an easy mix-up if you're going off the CLI flag name.
Verified this issue still exists: The flat field is silently dropped, the nested one works as expected (see screenshot below)

Added the correct shape as a comment on ResourceLimits in specgen.go, since that's what the libpod create endpoint's generated Swagger docs are sourced from.
Fixes: #19764
Checklist
Ensure you have completed the following checklist for your pull request to be reviewed:
commits. (
git commit -s). (If needed, usegit commit -s --amend). The author email must matchthe sign-off email address. See CONTRIBUTING.md
for more information.
Fixes: #00000in commit message (if applicable)make validatepr(format/lint checks)Noneif no user-facing changes)Does this PR introduce a user-facing change?
None