Compute the possible creation constraints of a workload's next Pod (#411 Q2, core) by hellices · Pull Request #528 · hellices/korvid

hellices · 2026-10-30T14:35:12Z

Closes #527

Summary

The core half of slice Q2 of #411. It computes which ResourceQuotas and LimitRanges a workload's next Pod, or a StatefulSet's new claim, could run into. This is pure Python with no UI change; the view section is the next slice. The plan is docs/superpowers/plans/2026-10-31-creation-possibilities-core.md.

format_quantity: a computed amount is shown in the unit family of the limit it relates to, with the largest suffix that shows it exactly, and never rounded. Remaining CPU of 1.5 is 1500m, and 1.5Gi against 8Gi is 1536Mi. An amount no suffix shows exactly is written in base units with its unit word.
core/creation_demand.py:
- a limit stands in for a missing request, then LimitRange Container defaults fill what is still missing;
- conflicting defaults, unparsable values and a runtimeClassName leave the affected resources not established;
- the effective Pod request is computed as Kubernetes computes it: apps plus sidecars, against each init container with the sidecars started before it;
- Pod-level resources override per resource and per side;
- it keeps each container's values, its missing CPU and memory fields, and the QoS class.
core/creation_possibilities.py:
- Quota applicability: Terminating/NotTerminating, BestEffort/NotBestEffort, PriorityClass scopes, and scopeSelector with In/NotIn/Exists/DoesNotExist. A missing priorityClassName, an unknown QoS class, or an unchecked scope or operator gives a not-established row.
- Quota rows: "would exceed" with what the Pod needs and what remains; "requires a field" for the CPU and memory keys, naming the containers, and not established when Pod-level resources may supply it; Pod counts at their limit; stale or unreadable quotas not established.
- LimitRange rows: min, max and maxLimitRequestRatio per container and per Pod, following the LimitRanger's rules (no request below min, no limit above max, both present for the ratio).
- Claims: checked against unscoped storage quotas and PersistentVolumeClaim LimitRanges, each row marked conditional. An omitted storage class leaves per-class quotas not established.
- "Nothing constrains this template": said only when no row was found, there is no RuntimeClass and no omitted storage class, and both policy lists are conclusive.

Verification

Tests were written to fail first for each module:
- tests/core/test_creation_quantities.py: formatting and unit words.
- tests/core/test_creation_demand.py: 32 tests covering defaulting, conflicts, init containers and sidecars, Pod-level overrides, RuntimeClass, unparsable values, missing fields and QoS.
- tests/core/test_creation_possibilities.py: 54 tests covering every scope row, the selector operators, the exceed boundaries, unit families, required fields, Pod-level resources, stale and unreadable quotas, LimitRange bounds and their exact edges, claims, and the conclusion's preconditions.
Every comparison, guard and branch was mutation-checked, and the helper refuses to report on a failing baseline. Survivors became tests or simpler code. One sidecar candidate path could never win, so I removed it. Three mutants are equivalent:
- two conflict guards in _Defaults: _fill marks conflicts unknown before applying values, so they are redundant but explicit;
- the claim-key skip in the Pod's quota rows: those keys charge zero for a Pod.
Local gate, using the venv's tools behind the corporate mirror:
- scripts/check_source_size.py, ruff check src tests, ruff format --check src tests, mypy src tests/core (339 files) and tach check all passed.
- pytest -n 8: 15347 passed, 41 skipped, 1 failed. The failure is the known local-only test_device_login_prefixes::test_the_measured_release_is_the_installed_one: the venv has litellm 1.100.3 and can't re-sync behind the mirror.

Checklist

This closes an accepted issue in this repository that is assigned to me.
Tests cover the change, written to fail first where behavior changed.
make check passes locally.
User-facing docs and the README match the change, or nothing user-facing changed.
No security invariant is weakened: writes still need a keystroke approval
and a fail-closed audit entry, and sensitive reads are still masked.

Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

core/creation_demand.py applies request defaulting from limits and the LimitRanges' Container defaults, leaves conflicting defaults, unparsable values and RuntimeClass overhead not established, computes the effective Pod request with sidecars and init containers as Kubernetes does, applies Pod-level resources per resource, and keeps each container's missing CPU and memory fields and the Pod's QoS class. Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

core/creation_possibilities.py decides each quota's applicability from its scopes and selectors, leaving it not established without a priorityClassName, for an unknown QoS or for unchecked scopes; reports would-exceed with the remaining amount, required CPU and memory fields per container, Pod counts at their limit, and LimitRange min, max and ratio per container and Pod; checks StatefulSet claims conditionally; and says nothing constrains the template only from conclusive lists with nothing found or left open. Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🟡 Changes recommended

Critical errors in quota accounting, LimitRange validation, and QoS classification can skip applicable constraints or treat unknown values as satisfied, falsely reporting workloads as unconstrained.

9 open issues

What changed in this PR

Implements the pure-Python core of #527, part of #411’s workload creation-constraint analysis. It builds on projected workload templates to identify possible ResourceQuota and LimitRange constraints; UI integration follows separately.

Changes:

Computes Pod demand with defaults, init containers, sidecars, and Pod-level resources.
Evaluates quota applicability, resource bounds, and conditional StatefulSet claim constraints.
Adds quantity formatting, focused tests, and optional-dependency import checks.

File	Description
`tests/test_optional_extras.py`	Checks that both new modules import without optional extras.
`tests/core/test_creation_quantities.py`	Tests quantity formatting and resource unit labels.
`tests/core/test_creation_possibilities.py`	Tests quota, LimitRange, claim, and conclusion handling.
`tests/core/test_creation_demand.py`	Tests demand calculation, defaults, overrides, and QoS.
`src/korvid/core/creation_quantities.py`	Adds computed-quantity formatting and unit labels.
`src/korvid/core/creation_possibilities.py`	Produces possible policy constraints and uncertainty results.
`src/korvid/core/creation_demand.py`	Computes effective Pod demand and missing resource fields.
`docs/superpowers/plans/2026-10-31-creation-possibilities-core.md`	Documents the core implementation and verification plan.

_{Review effort: Balanced}

- Unparsable quota usage, LimitRange bounds and claim requests give not-established rows. - LimitRanges not all read leave missing fields, BestEffort and demands an unseen default could raise not established; an excess already certain says 'needs at least'. - QoS ignores zero values and treats unparsable Pod-level values as unknown; hugepages-<size> keys charge the request; count/persistentvolumeclaims charges one claim. - Ratios are explained exactly instead of rounded. Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🟡 Changes recommended

Incorrect Pod-level defaulting and incomplete LimitRange handling can miss quota violations or produce false findings, while ratio checks incorrectly accept zero limits.

5 open issues

9 resolved since last review

_{Review effort: Balanced}

- An incomplete LimitRange list applies none of the defaults it did read: one it did not read may override them, so explicit values are a floor. - A Pod-level limit stands in for a missing Pod-level request, as the API defaults it, before any check; a Pod-level request still wins. - maxLimitRequestRatio needs a nonzero limit as well as a nonzero request. - Any Pod-level CPU or memory leaves every required field not established, since the cluster may then skip the per-container checks. - A LimitRange min, max or ratio check a default not read could change is not established, while a value already above max, or a ratio only a growing limit could reach, is still reported. Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🟡 Changes recommended

Incomplete quota applicability can produce false limit violations, while conflating Pod-level requests and limits can suppress uncertainty about unread LimitRange defaults.

2 open issues

5 resolved since last review

_{Review effort: Balanced}

my-reviewer-agent

이슈 6건을 인라인 코멘트로 남겼습니다.

- QuotaProjection.scopes_complete records whether a quota's scopes and scope selector were read. A quota whose scopes were not gives only "whether it applies: its scopes could not be read" and no claim row, instead of checking entries it may not apply to. A quota with only an unreadable hard value still reports its readable entries. - PodDemand.pod_level_limits: a Pod-level request no longer stops an unread default from adding a limit, so a LimitRange max on the Pod's limit stays not established rather than "no limit is set". Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🔵 Needs a closer look

Human assessment is needed to evaluate quantity-formatting edge cases affecting storage-unit labels and exact decimal preservation.

No open issues 🎉

2 resolved since last review

_{Review effort: Balanced}

- A StatefulSet creates every claim of an ordinal before its Pod, so each quota entry is now checked against the total of the claims it charges, grouped by storage class for per-class keys. A claim whose class or request is unknown keeps its own not-established row, and the total then "needs at least". A full storage quota says "needs ...; none remaining"; only a claim-count quota with no room says the claims exist. - A LimitRange korvid could not wholly read gives "its constraints could not be read", so it can no longer leave nothing constraining a template. - Tests now cover quotas whose scopes and expressions must all hold, and the limit a Pod-level limit keeps; the plan's QoS wording is corrected. Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

🔵 Needs a closer look

Human assessment is needed because subtle Decimal precision and incomplete LimitRange edge cases can undermine exact formatting and mask definite resource violations.

No open issues 🎉

_{Review effort: Balanced}

hellices and others added 4 commits October 30, 2026 23:20

Format computed quota amounts exactly in their limit's unit family

413fbaf

Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Add the #411 Q2 core implementation plan

90656cf

Part of #527 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI balanced review requested due to automatic review settings October 30, 2026 14:35

hellices added this to the v0.7.0 milestone Oct 30, 2026

hellices added enhancement New feature or request area: k8s Kubernetes clients, resources, operations, and cluster behavior labels Oct 30, 2026

hellices self-assigned this Oct 30, 2026

Copilot started reviewing on behalf of hellices October 30, 2026 14:35

View session