Explain workload creation failures with ResourceQuota and LimitRange evidence #411

Problem

A Deployment can exist, or its replica count can increase, while child Pods are rejected before creation. Node capacity alone does not explain namespace quotas, resource-count limits, or LimitRange requirements. Operators currently have to connect controller events and namespace policy objects themselves.

Goal and first-version scope

Provide a read-only, namespace-scoped explanation for a selected workload's creation constraints:

• Display ResourceQuota hard/used values and relevant scopes, separating CPU/memory requests and limits, storage quantities, and object counts.
• Display LimitRange defaults and minimum/maximum constraints with their applicability.
• Correlate UID-bound Deployment/ReplicaSet/Job creation-failure events with the relevant namespace policy evidence where the recorded rejection supports that connection.
• Distinguish a recorded admission rejection from a potentially relevant current constraint and from missing evidence.

No LLM is required. Keep timestamps, source identities, coverage, and the current workload/namespace visible.

Compatibility and evidence boundary

Depends on #409. The baseline uses ResourceQuota and LimitRange core/v1 APIs, controller status, and supported event APIs. Optional observability, modern scheduling APIs, and cluster-wide permissions are not prerequisites.

Quota status is a non-atomic observation, not a capacity reservation or a guarantee that the next create will succeed. Handle multiple quotas, quota scopes/selectors, stale status, and concurrent usage without inventing an exact number of schedulable Pods.

Show configured defaults, but do not attribute every difference between a workload template and an admitted Pod to LimitRange; other admission components may mutate a Pod. Old events and present quota values must not be presented as one atomic historical snapshot.

Use bounded authorized namespace reads. This workflow does not submit probe Pods, dry-run writes, or alter quotas, limits, replicas, or admission policy.

Acceptance criteria

• A user can inspect a workload with no created Pods and see recorded creation failures alongside relevant namespace quotas and LimitRanges.
• CPU, memory, storage, and count quantities render correctly without naive string comparison or misleading unit conversion.
• Recorded denial, current possible constraint, no relevant standard policy observed, and unknown/partial evidence remain distinct.
• Missing APIs, denied reads, expired events, multiple scoped quotas, missing/stale quota status, and truncated lists do not yield a false success or definitive root-cause claim.
• Tests cover unit conversions, defaults, min/max restrictions, scoped/multiple quotas, changing status, mismatched event UIDs, and recreated workloads.
• Reads are bounded/cancellable and context-safe; no mutation, Secret payload retrieval, or automatic external-model call occurs.

Planning and related work

Scheduled for v0.7.0 after the shared foundation #409. Existing v0.5.0 and v0.6.0 release scopes remain unchanged. No release date is committed. Complements #405 by explaining a class of failed convergence; it does not duplicate the post-action observation state machine. Results can feed the existing #389 attention surface without creating a second monitoring subsystem.

Upstream references

• Resource quotas
• Limit ranges