This has come up a bunch in a lot of small ways, and my mind keeps coming back to this idea, so I want to write it down.
In early early kube API we had desired and actual (or something like that) structs. Since they were the same struct there were a bunch of things in the struct that were things we didn't want users to set (which eventually became status) and other problems. As we changed to spec+status, we lost the concept of "actual" and just folded it into spec.
This conflates a couple of ideas and makes it hard to distinguish what the user actually asked for from what was assigned to them. I am proposing we reinstate that distinction.
I propose that every top-level object (all of them, not just the ones that make sense RIGHT NOW) holds 4 fields (plus ObjectMeta):
metadata - same meaning as todayspec - what the user asked for, with API-defined defaults applied AND NOTHING ELSE. Every field is available to users.actual - the exact same structure as spec, but with other fields populated by the system (e.g. nodeName when scheduled, clusterIP when auto-assigned, and so on)status - same meaning as today
If a user wants to save a pod and move it to another cluster, spec is what they want. If a piece of software wants to know how a pod is operating, actual and status are what they want.
I chose this layout (which changes the meaning of spec because I figured it makes it easier on users to change over, while making it harder for system components (change to actual). This may be wrong, but it's not obvious. An alternative would be that spec means "actual" and request means "what the user asked for"; users write request and the system writes spec. This has the advantage of software that observes state being easier to change over, but means that users have more pain. But it is perhaps better to break users, who actually SEE error messages. Sometimes bigger changes are better because the need to something is obvious (see the bugs people hit with some really subtle v1beta1 -> v1 changes).
It would be nice to make one field writable ONLY by users (create/update) and one field writable only by the system. We've used binding for scheduling, but there are other things (like clusterIP) that are written directly in-process.
We could make this round-trippable by embedding request under status in v1 or even as a new top-level object + sub-resources.
Lastly, there's some question about preserving exactly what the user asked for WITHOUT defaults applied, but I am less sure that is needed or particularly useful.
@bgrant0607 @smarterclayton @lavalamp
This has come up a bunch in a lot of small ways, and my mind keeps coming back to this idea, so I want to write it down.
In early early kube API we had
desiredandactual(or something like that) structs. Since they were the same struct there were a bunch of things in the struct that were things we didn't want users to set (which eventually became status) and other problems. As we changed tospec+status, we lost the concept of "actual" and just folded it intospec.This conflates a couple of ideas and makes it hard to distinguish what the user actually asked for from what was assigned to them. I am proposing we reinstate that distinction.
I propose that every top-level object (all of them, not just the ones that make sense RIGHT NOW) holds 4 fields (plus ObjectMeta):
metadata- same meaning as todayspec- what the user asked for, with API-defined defaults applied AND NOTHING ELSE. Every field is available to users.actual- the exact same structure asspec, but with other fields populated by the system (e.g. nodeName when scheduled, clusterIP when auto-assigned, and so on)status- same meaning as todayIf a user wants to save a pod and move it to another cluster,
specis what they want. If a piece of software wants to know how a pod is operating,actualandstatusare what they want.I chose this layout (which changes the meaning of
specbecause I figured it makes it easier on users to change over, while making it harder for system components (change toactual). This may be wrong, but it's not obvious. An alternative would be thatspecmeans "actual" andrequestmeans "what the user asked for"; users writerequestand the system writesspec. This has the advantage of software that observes state being easier to change over, but means that users have more pain. But it is perhaps better to break users, who actually SEE error messages. Sometimes bigger changes are better because the need to something is obvious (see the bugs people hit with some really subtle v1beta1 -> v1 changes).It would be nice to make one field writable ONLY by users (create/update) and one field writable only by the system. We've used binding for scheduling, but there are other things (like clusterIP) that are written directly in-process.
We could make this round-trippable by embedding
requestunderstatusin v1 or even as a new top-level object + sub-resources.Lastly, there's some question about preserving exactly what the user asked for WITHOUT defaults applied, but I am less sure that is needed or particularly useful.
@bgrant0607 @smarterclayton @lavalamp