Release

Announcing Toise 0.12.0 — the pod

2026-08-11

A thirteenth entity type. That sounds like a small thing, and mechanically it is — one constant, no new relation, nothing changed on the wire. What made it interesting is how the decision got made: we argued for it on taxonomy, the producer team said no, and the thing that actually settled it was a measurement nobody could attach anywhere else.

Where a pod does not fit

A Kubernetes pod is the unit of scheduling and of failure: one or more containers sharing a network namespace and a lifetime. It is not a container, not a machine, not a service instance. Modelling it as a container would be worse than not modelling it — a pod with three containers would either collide with them or count them three times.

So the honest options were two: add a type, or leave the pod out and keep its name as an attribute on each container. The producer team recommended leaving it out, and their reasoning was sound on its face: the pod's only relations would be "contains these containers" and "runs on this node", both already derivable. The cost of a missing node is a query the consumer writes; the cost of a wrong node is a graph nobody trusts.

The argument we made, and the better one we got back

We pushed back on the premise. "This container is in that pod", carried as a string attribute on the container, is not a join. It is the same shape that made IP addresses untraversable in this graph until network.address became a node of its own: a value transported next to a thing instead of an edge pointing at it. Answering what else runs in this pod stops being a query and becomes a scan with string comparison. A human can do that. A model has to pull the whole collection first, which is exactly the legibility we are trying not to lose.

That argument is right, and it is not the one that decided it. The producer team came back with a better one, taken from a contract they had written themselves a week earlier: the network namespace is shared per pod, so pod-scoped network measurements describe the pod and nothing else. Their own rule says a type that owns telemetry needs an entity to attach it to — otherwise those measurements have no subject.

We prefer their version. Ours rests on a judgement about what reads well; theirs falls out of a rule already agreed, and nobody has to be persuaded of anything. When a vocabulary decision can be settled by a rule instead of a preference, that is the one to use.

What it looks like

The type is pod, identified by the UID Kubernetes assigns — never namespace/name, which is mutable and reused. A deployment deleted and recreated under the same name is a different deployment, and the UID says so where the name would lie. It is the same reasoning that stopped databases from collapsing into each other two weeks ago.

No new relation type was needed:

container --runs_on--> pod --runs_on--> host

runs_on already propagates failure from target to source, so a node draining takes its pods, which take their containers — transitively, with no extra code. Asking what a node failing would affect returns the pods and their containers the day the first one arrives. And for a consumer, "what runs in this pod" is one hop.

Two versions, and they are not interchangeable

This is the first vocabulary addition since the type set stopped being something producers retype by hand. The constant ships as wire.TypePod in pkg/emit/v0.7.0, and Toise's own registry derives from that same constant.

Which creates a sequencing a producer needs to know about: the SDK tag lets you compile, this release lets you emit. Toise's boundary refuses types it does not know under the default strict vocabulary, so pods sent to an older instance are rejected per record. The split is not packaging clumsiness — the engine resolves the SDK from its published version, so a constant cannot be registered before it is tagged.

It is worth saying that this constraint is the guarantee working. The producer team hit it first: their vocabulary now derives from ours, so pod simply would not compile on their side until we published it. They told us they would not work around it. That is the point of putting the vocabulary in a package both sides compile against.

Get it

go install github.com/toise-dev/toise/cmd/toise-server@v0.12.0

Binaries for linux and darwin (amd64 / arm64) are on the release, each with a checksum, and the container image is on GHCR. See the 0.12.0 docs and the changelog. Producers pick up the type with pkg/emit/v0.7.0.