feat: collect the placement constraints that stop a workload from moving (ADR 0031)

[kfeofantov]

workload_metadata gains a placement block in its pod scope: the nine pod-spec fields that say where a pod may run and what it costs to move it. No new payload kind, no new informer, no new RBAC — the pod spec was already read in full.

The gap this closes

The agent could say what a workload consumes, what it asked for, and which machine it got. It could not say why it is on that machine and not a cheaper one.

Replicas each sitting on their own large node may need the size — or may be held one-per-node by a required anti-affinity on kubernetes.io/hostname. The usage numbers are identical; the conclusions are opposite. Same for DoNotSchedule across zones, which keeps a workload paying for every zone it spans whether or not the capacity is needed there.

The three payloads now compose: workload_metadata says what was asked for, node_metadata says what machine answered, and this says what forbids a different answer.

Where it lives

In the pod scope, not in a kind of its own. Placement is a pod fact, so it nests where the other pod facts nest (ADR 0014) and repeats across a pod's containers exactly as the replica counts do.

It is taken from the first pod under the key, the way image, resources and ports already are. That is safe here because the key carries the image digest: a rollout that tightens placement produces one record per build, each with its own constraints, rather than whichever pod was seen first speaking for both. The golden shows exactly this — the old build with its selector and spread, the new one with a tightened node affinity and an unschedulable replica.

Reduced, not copied — and the loss is stated

Node affinity is flattened to (key, operator, values, required, weight); pod affinity and anti-affinity keep the topology key and whether the term is required; spread keeps skew, whenUnsatisfiable and minDomains. Label selectors inside pod-affinity and spread terms are dropped.

Flattening loses the OR/AND structure of node affinity, so the scheduler's decision cannot be replayed from this payload — and that is written into the ADR rather than left for a consumer to discover. What survives answers what a workload is pinned on and how hard, which is the question the payload exists for. A faithful copy would carry an arbitrarily nested selector into every record of every container to support an inference the product does not make.

Required and preferred stay apart: only a required term can leave a pod unschedulable.

Bounded strings, and drops that are counted

This is the second place after build settings where free-form strings written by whoever wrote the manifest enter the agent, so it takes ADR 0019's discipline unchanged — bounded at 128 bytes, and anything past a bound dropped whole rather than truncated, because a prefix of an unexpected string is still an unexpected string. A value list past its bound is dropped while its key and operator survive: a partial list would read as a complete one.

placement_values_dropped and placement_terms_dropped reach the coverage report, aggregate and never named. Both sit at zero on an ordinary cluster.

Cluster-wide defaults are not collected

DefaultTolerationSeconds puts not-ready and unreachable at 300s on every pod in the cluster, so carrying them would repeat two identical entries on every record and state nothing. The match is exact on the seconds — a pod that tuned one keeps it, because that deviation is how fast it leaves a failing node. Same for default-scheduler and a 30-second grace period: only the deviation is a fact. An unconstrained pod therefore contributes zero bytes, verified by a test that encodes it and asserts {}.

What is not read

env, args and command sit in the same PodSpec, and this is checked on the encoded bytes rather than on the shape of the struct. Verified negatively: making the reduction leak a container's command fails the test with "scheduler_name":"/bin/app" printed.

volumes are not read at all. A zonal volume does pin a pod, but resolving it runs through the StorageClass — RBAC the agent does not have — and the volume list references Secrets and ConfigMaps by name.

And one fact turned out not to be observable: a pod pinned by hand through spec.nodeName is indistinguishable after scheduling from one the scheduler placed, since every scheduled pod carries the field. It is not reported rather than guessed at.

Verification

make test (17 packages) and make lint (0 issues) green. The golden bytes changed, which is a protocol change and is what makes it one.

🤖 Generated with Claude Code