docs: size from the pod's CPU request, and document runtime.cpu.cores: all - #2078
Merged
Conversation
…s: all` spiceai/spiceai#12581 changed where the CPU entitlement comes from for the most common Kubernetes shape, which made three pages wrong rather than merely incomplete. `runtime.cpu`: the detection ladder gains the declared-request rung, and the claims it replaces are gone — that a cgroup share is never an input to sizing "so a pod with requests and no limits is sized for the whole node" described the behaviour this change reverses. Adds `all` as an accepted value, including the one way it differs from every other setting: it defers to a quantity named on a lower-precedence surface, which is what lets a platform set it fleet-wide without silencing a per-pod spicepod. New subsection covers the multiple, the 2-core floor, why the request must be *declared* rather than inferred from a share, and the two load-bearing details of the downward-API block — the `divisor: 1m`, and emitting it only when a request is set, since `resourceFieldRef` otherwise reports node allocatable. Performance tuning: the Kubernetes guidance said a pod following its own advice (requests, no limits) is sized for the whole node. It now says what actually happens, that this is the no-configuration default because the Helm chart and the Kubernetes Operator both emit the passthrough, and gives a table of which knob answers which intent — including `runtime.cpu.cores` as the way to bound the runtime without the CFS throttling a `limits.cpu` imposes. Observability: `spiced_cpu_budget_cores{source}` gains `request_burst` and `all_cores`, and `spiced_cpu_request_millicores` no longer claims to be "never used for sizing" — it is the declared request, and the `source` label is what says whether it won. Every constant and label is checked against the shipped source: factor 2, the 2000-millicore floor, the 10-millicore implausibility threshold, the six source labels, and the chart's `containerName` and `divisor`.
Contributor
✅ Pull with Spice PassedPassing checks:
|
Contributor
|
🚀 deployed to https://9d2902cd.spiceai-org-website.pages.dev |
bjchambers
commented
Aug 11, 2026
Four review points. The `source` label values were listed without meaning, so a reader seeing `request_burst` had nothing to go on. A new section in Observability gives each of the six a row: what it means and, for `request_burst`, the formula it applied. `spiced_cpu_request_millicores` did not say how the request reaches the runtime. It cannot read `resources.requests.cpu` itself, so the same section carries the downward-API block and states that the Helm chart and the Kubernetes Operator both emit it by default — a hand-written pod spec reports `affinity` instead. The `auto` row of the accepted-values table said only "detect the entitlement". It now gives the formula and, more usefully, why the multiple exists: it exceeds the request deliberately so a burstable pod can still burst above its scheduling floor. The Kubernetes deployment page said nothing about CPU at all. It gains a sizing section — the three pod shapes and what each resolves to, that the chart and operator wire the request automatically, and `runtime.cpu.cores: all` for bursting across the whole machine, which is what the Spice Cloud Platform sets on hosted instances. It closes on preferring `runtime.cpu.cores` to a `limits.cpu` CFS quota. The docs build caught a broken anchor on the way: the Kubernetes index resolves with a trailing slash, so `../../reference/…` strips the version segment.
lukekim
approved these changes
Aug 11, 2026
…ement-docs # Conflicts: # website/docs/reference/spicepod/runtime.md
Contributor
|
🚀 deployed to https://6901005e.spiceai-org-website.pages.dev |
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
2 participants
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.
Documents the CPU-entitlement change from spiceai/spiceai#12581 (step 6 of spiceai/spiceai#12489). Targets
website/docs— trunk, i.e. Next — since the change ships in 2.2.0 and is not in any released version.Why this is a correction, not an addition
Three pages described behaviour that spiceai/spiceai#12581 reverses. The clearest example, from
runtime.cpu:That is now false, and it was the recommended Kubernetes configuration — so the wrong sentence was the one most readers would act on.
runtime.cpureferencemin(max(2 cores, request × 2), available CPUs), below the CPU quota and above the affinity mask.alldocumented as an accepted value, with the property that distinguishes it from every other setting: it defers to a quantity named on a lower-precedence surface. That is what lets a platform setSPICE_CPU_CORES=allfleet-wide without silencing an operator's ownruntime.cpu.cores: 4. It does not defer toauto.divisor: 1mis what makes the value millicores, and the block must be emitted only when a request is set, becauseresourceFieldRefotherwise reports node allocatable — the exact over-sizing this prevents.Performance tuning
The Kubernetes section said a pod following its own advice is sized for the whole node. It now states the default plainly —
requests.cpu: 4on a 64-core node sizes for 8 cores, with no configuration needed — and adds a table of which knob answers which intent:runtime.cpu.cores: allruntime.cpu.cores: 6resources.limits.cpu(accepts throttling)The existing "avoid CPU limits" tip now points at
runtime.cpu.coresas the way to bound the runtime without a CFS quota — it caps how much machine the runtime organizes itself around, not how much CPU it may consume.Observability
spiced_cpu_budget_cores{source}gainsrequest_burstandall_cores.spiced_cpu_request_millicoresno longer claims to be "never used for sizing" — it is the declared request, and thesourcelabel is the authority on whether it won.Verification
Every value is checked against the shipped source rather than this PR's description:
CPU_REQUEST_BURST_FACTOR = 2,REQUEST_DERIVED_FLOOR_MILLICORES = 2000,SUSPECT_CORE_SHAPED_MILLICORES = 10, the sixCpuSource::as_strlabels, and the chart'scontainerName: spiceai/divisor: 1m. The startup-log examples are copied from real output, not composed.npm run buildpasses, which is what validates the new#sizing-from-a-cpu-requestanchor and the cross-page links into it.Refs spiceai/spiceai#12489