Understanding Kubernetes' Design (Question about the Kubernetes Resource Model)

I have been using Kubernetes for a few years now (and loving it!) and today I came across the Kubernetes Resource Model. There was a bullet under the section called Additional Resource Model Properties that I want to make sure I understand:

  • The current status is represented using as many properties as necessary, rather than being modeled by state machines with explicit, enumerated states. Such state machines are not extensible (states can neither be added nor removed), and they encourage inference of implicit properties from the states rather than representing the properties explicitly.

Would one example of this be the way that pod status is modeled? Specifically that in addition to having a “phase” field that reflects the current status of the pod there is a list of conditions where the status of all conditions is always visible?

Also, I don’t understand what is meant by “they encourage inference of implicit properties from the states”. In the Pod example does that mean that if only the “phase” field existed then we would have to infer the status of things like network connectivity or the readiness of individual containers?

The reason I’m asking is that I’m in the middle of designing a metadata API that needs to communicate system state and I feel like this bullet point is a pearl of wisdom worth understanding.

Thanks!

Phase was probably a mistake.

Describing your API as a state machine makes it hard to change (clients encode the same state machine, which means any change is potentially breaking), and people infer a state to mean the sum of all observable properties. Better to track discrete, orthogonal statements, even when some of those intersections are “impossible”.

Thank you! And for anyone coming to this thread later, this issue also includes a good explanation.