Some people who might be interested in this: @bgrant0607 @smarterclayton @mbohlool @thockin

Ref #4855, #30819

@lavalamp I assume this approach would not allow the same field name to be used at different stages with different types.

I was thinking we'd use the tags to specify finer-grain versions, either API minor/patch versions or releases.

I don't understand this proposal. What do those versions mean? What
literally happens because of them? How do we overlap alpha/beta and
beta/ga ?

On Mon, Oct 10, 2016 at 7:44 PM, Brian Grant notifications@github.com
wrote:

@lavalamp https://github.com/lavalamp I assume this approach would not
allow the same field name to be used at different stages with different
types.

I was thinking we'd use the tags to specify finer-grain versions, either
API minor/patch versions or releases.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#34508 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AFVgVGZIp3Z7BWhii1g77PlgXF7J_bUYks5qyvgRgaJpZM4KTGnt
.

@thockin I asked @lavalamp to keep it short. I'll write up more tomorrow.

Imagine we had actual distinct API versions containing the alpha, beta, and GA fields corresponding to some feature. They could all use the same internal rep, clients could request the API version containing the version of the field they understood, and users could use kubectl convert to upgrade their manifests.

Now assuming we don't really want to do that, how could we accomplish the equivalent in a single types.go file?

Ignoring whether we use comments or tags or something else to specify information on the fields, we'd put the fields in the same versioned types.go:

        AlphaFeature *bool `json:"alphaFeature,omitempty"`
        BetaFeature *bool `json:"betaFeature,omitempty"`
        Feature *bool `json:"feature,omitempty"`

Only the most mature version of the field would be serialized in etcd and only one of these fields would be visible to any client at a time.

@lavalamp proposed we use the proposal from #33900 to enable the client to request the desired field version. Another possibility is that we use the existing API version mechanism, using the apiVersion field and path.

With multiple different fields as above, rather than @lavalamp's syntax for specifying the level of maturity, I'd just specify the maturity level (alpha/beta/GA) of the field (e.g., so we could disable all alpha fields by default) and the range of "versions" that it was at that level of maturity.

If we used an extension of the existing API version mechanism, I'd add minor version, such as v1beta1.1 for the version following what's currently v1beta1, or v1.0.0-beta.1.1 if we want to go with actual semver. If we used headers as in #33900, we could use releases, such as 1.5.0-alpha.3. Either way, in the comment or tag, we'd specify a range of versions, such as 1.4.0-alpha.3..1.5.0-alpha.7.

Note that relying on a new mechanism, such as #33900, won't work for any existing clients.

One disadvantage of using release versions is that some projects that embed K8s (e.g., Openshift) have their own release numbers.

Anyway, I'm inclined to use a single versioning scheme for the API.

It wasn't clear from my initial post, but these were intended to be api versions, not release versions. The patch version will rapidly diverge from the release patch version. We could make this more obvious, by prefixing with something other than "v". We could also not use semver and just have a clock that counts up with each api change--I didn't recommend that because we probably should produce semvers at some point, and it is easiest if we just keep them in that format to begin with.

I assume this approach would not allow the same field name to be used at different stages with different types.

Right, you have to actually make a separate "real" api version for that. (Arguably this is a feature.)

rather than @lavalamp's syntax for specifying the level of maturity, I'd just specify the maturity level (alpha/beta/GA) of the field (e.g., so we could disable all alpha fields by default) and the range of "versions" that it was at that level of maturity.

My suggestion is a superset of this. I was thinking you need to know what semantics the client is expecting to get, that it doesn't matter if the server has moved on. I'll have to think about it more, but I still think it is better to track the history and not just the current status.

1.4.0-alpha.3..1.5.0-alpha.7

You can specify multiple versions in Accept headers. I'm not sure a range really gets you any benefit over that, unless you want to specify it separately and have it apply to all the things in the Accept header. (to avoid combinatorial explosion)

What do those versions mean?

These provide an API history, and if a client gives a range or a version, we'd know:

• which fields are new to that client
• which fields the client will think are alpha/beta/ga.
• which fields the client thinks exist which actually don't anymore.

The most recent alpha/beta/stable/marker determines the current state of the field. We can then stuff e.g. alpha fields into the list of alpha features automatically and allow them to be toggled on and off.

What literally happens because of them?

Swagger:

• Check global alpha flag before adding alpha fields to the spec.
• Produce schemas from the perspective of the client, i.e., previous points in time.

Conversion:

• We could e.g. track an "unset" bit for fields when we know the client doesn't understand them, which are useful in update. Additionally we could just not deliver fields to clients if we know the client won't understand them.

Update:

• Values for fields the client wasn't aware of can be automatically ignored in update requests.

Validation:

• If validation rules change, we can validate as of the version the client knew of (and automatically fix items that would now be invalid, if possible)

Defaulting:

• I think no changes necessary.

How do we overlap alpha/beta and beta/ga ?

This proposal doesn't overlap them from the perspective of the server. Each field is one of alpha, beta, or stable in any given fully specified version number.

@lavalamp I think we need a mechanism that does permit the representation to change. Otherwise we really are introducing hoops for no good reason.

The reason for ranges was to support multiple fields for the same feature, which is needed in order to support representation changes. The specification of maturity of the field similarly assumed there would be multiple fields, so it would capture history, not just current status.

I know you weren't proposing we use release versions, but was just pointing out that alternative.

I agree on semver.

I suppose differing representations could be handled by allowing fields
with different go names to have the same json tag, and then generating json
parsers that are aware of this (would be a good reason to tear out ugorji).
However I don't think that makes any sense for the proto
representation--any given field number in the proto messages can't change
representation.

On Tue, Oct 11, 2016 at 2:08 PM, Brian Grant notifications@github.com
wrote:

@lavalamp https://github.com/lavalamp I think we need a mechanism that
does permit the representation to change. Otherwise we really are
introducing hoops for no good reason.

The reason for ranges was to support multiple fields for the same feature,
which is needed in order to support representation changes. The
specification of maturity of the field similarly assumed there would be
multiple fields, so it would capture history, not just current status.

I know you weren't proposing we use release versions, but was just
pointing out that alternative.

I agree on semver.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#34508 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAngllUSciBNwARfrXSypduKaGCSgZe8ks5qy_rhgaJpZM4KTGnt
.

I think having json names that reflect the particular state and
representation of a field is a feature. The only problem we have is
supporting multiple representations, which is really a problem when
you have three levels rather than two.

If we are backwards compatible in major versions, why not simply
collapse this into two states.

1. Alpha (no back compat)
2. Beta (back compat, no breaks)

All users eventually have to change beta to GA, which is not a magic
change (eventually deployments hits v1 and we drop v1beta1).

For existing GA objects, why have beta fields at all? Why not say
that beta = GA API but possibly not GA behavior? I don't really like
having "maybe backwards compatibility" - why not just have alpha until
we are ready to finalize API and then if we get it wrong make it ugly
in that API version and fix it in the next? We're trying really hard
not to create v2 API, but I think that's the wrong way to think (minor
and semver implicitly require us to start revving API objects more).

Added this to the agenda for today's API Machinery SIG.

A couple questions:

1. Am I correct in assuming that we have field level versions that are distinct for each API GroupVersion since that's the finest granularity where they are used and that would allow different groups to proceed at their own pace. Then it seems like I'd want different minor versions per-API GroupVersion so they can patch and pick changes separately.
2. Will we use this information server-side to preserve fields that an old client stripped because it didn't recognize that they were present during update flows?
3. How will I specify the version I used to create a particular object manifest which may be used by clients with different schema versions?

1. Yes, each group has its own version.
2. Yes, that's one goal.
3. The most obvious way would be to extend the version in the APIVersion field. It should be OK unless clients are using that to blindly construct URL paths.

It should be OK unless clients are using that to blindly construct URL paths.

As I recall, that was actually pitched as a benefit of not adding an apiGroup field to TypeMeta. I'd prefer to have a separate field for separate information. Old clients that interpret the object and drop it weren't going to understand what to do with it anyway, so I don't think that lack of roundtripping on old clients is different than current behavior for existing fields today.

/cc @davidopp @aveshagarwal

@derekwaynecarr

The eternal damnation of any and all badly chosen names makes me sad.

On the plus side, it does mean we can use some great GIFs...

More seriously, to clarify (also left a comment as such on the above community PR):

If we're working with a new alpha field Quuxer, and, while still in alpha, we want to change the value type from int to resource.Quantity, we have to abandon the name Quuxer forever, and use QuxxerQuantity instead?

That seems like it's going to cause a decent amount of redundant or strange-looking API names...

@DirectXMan12 That's my main concern. I can buy that beta fields should not be renamed, so beta -> GA is smooth, but I suspect alpha fields will have a lower success rate. I guess we'll wait and see.

Additionally, there's no indication that you're using a beta field, which I dislike. But alas, there are not enough hours in the week to hold strong opinions on everything, so I put my trust in the SIG.

/cc @ncdc

[MILESTONENOTIFIER] Milestone Labels Complete

@lavalamp

Issue label settings:

• sig/api-machinery: Issue will be escalated to these SIGs if needed.
• priority/important-soon: Escalate to the issue owners and SIG owner; move out of milestone after several unsuccessful escalation attempts.
• kind/cleanup: Adding tests, refactoring, fixing old bugs.

@lavalamp @ncdc @thockin @timothysc @liggitt Is there anything else we need to do for 1.8 here? Can we please move the milestone if not? (or close the issue)

@lavalamp @ncdc @thockin @timothysc @liggitt this is a daily and friendly ping from release team. Is this still relevant to 1.8? If yes, who is actively working on it?

Removing from milestone.

👍

/lifecycle frozen

/remove-kind design
/kind feature

kind/design will soon be removed from k/k in favor of kind/feature. Relevant discussion can be found here: kubernetes/community#5641

/sig architecture
too