Standardize a +feature-gate tag in APIs?

[Tim Hockin]

Hi all, API reviewers in particular.

I am tired of forgetting to specify which gate governs a field when I review APIs (or hunthing through the comment for it).  I propose we add a new tag:

```

// +feature-gate: MyGateName

```

This isn't required (since most fields are ungated) but just calling it a norm means we can get people to start being clearer in their API comments.

Objections?

Tim

[Antoine Pelisse]

Is this strictly for documentation or do you expect a specific behavior to happen? Should the field automatically be cleared when the feature-gate is disabled? Should we expose that in the OpenAPI?

--
You received this message because you are subscribed to the Google Groups "kubernetes-sig-architecture" group.
To unsubscribe from this group and stop receiving emails from it, send an email to kubernetes-sig-arch...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/CAO_RewYL3V7NkyysGgrmQCvBizh8W2zzxA09txY%3DOYzUYm87vg%40mail.gmail.com.

[Tim Hockin]

I was thinking docs at first and then see what we can do with it - openAPI, codegen, etc.

[Clayton Coleman]

This seems reasonable.  Also, I would expect automation based on this for fields to be given alpha/beta labels.

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/CAO_RewbaAT-R3iMfopSXP9TJPxt7_VpnuQGT4NiPE_OartJ18A%40mail.gmail.com.

[Stephen Augustus]

If this is exposed, it's something we could teach KEPs how to interpret as well!

I know having more information about a feature gate earlier in the dev cycle was something HH was interested in for conformance.

-- Stephen

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/CAH16ShLmWx1b8Ka0UZQ8kbZ-SPSonBhLjJ0%3Diw6exkHqqbfPrA%40mail.gmail.com.

[Wojciech Tyczyński]

 +1 for having that and start building more different automation based on that.

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/CAOqU-DQ2_AMCiiT9dJJ8ZaicLHEVEE%3DJ_ptQWVivon1SSMOxZg%40mail.gmail.com.

[Jordan Liggitt]

+1 for annotating feature-gated fields and using that info in more places. I played with letting field feature annotations inform openapi publishing a while back in case there's anything useful in there someone wants to grab.

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/CAPgfqyXgiiKCDwkSMGi7ansPsj9xacnVaeqELGoSn%2BsO8Cv6Dg%40mail.gmail.com.

[David Eads]

Annotating sounds like a good idea, but do we really want to leave it completely open or do we want to have a verify script that requires someone to make a choice even if the choice is ungated as it would be for APIs making their first graduations?

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/CAMBP-pJqLGAVSkOv3EFpWUi76VYXaFn%3DdaAWkDDdwtOweh1f-Q%40mail.gmail.com.

[Hippie Hacker]

While KEPs are a great place to discuss and checklist features+operations, I do think the definitive source should be the openapi spec. 

We have great OpenAPI tooling used to generate docs, conformance, etc. If we update the spec generation to include a per operationID featureflag and alpha/beta/GA levels we'll go a long way to providing clarity to our ecosystem.

For example a script could compare this openapi metadata with via kepctl and friends to curate a list of alpha/beta operations/feature flags lacking a KEP (or at least a KEP with the correct metadata) to help sync our enhancements process.

It would also help greatly with Conformance and help us have a clear understanding of GA apis vs beta/alpha.

Related keps/NNNN-kep-template/kep.yaml PRs:

- https://github.com/kubernetes/enhancements/pull/1844 merged to supported tracking feature gates
- https://github.com/kubernetes/enhancements/pull/2146 open to add alpha, beta, GA tracking to openAPI/operationIds

Cheers,
Hippie Hacker

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/CAFS1MjJ3DUCkiUdFJJD7a7oydZK2Y3sdYiMmV7%3DrPtEhXV1oHQ%40mail.gmail.com.

[Daniel Smith]

On Mon, Feb 8, 2021 at 1:31 PM Hippie Hacker <h...@ii.coop> wrote:

While KEPs are a great place to discuss and checklist features+operations, I do think the definitive source should be the openapi spec. 

There is not really a way we could get that information into the OpenAPI spec without adding the mechanism Tim started the thread off with, or one significantly like it. OpenAPI is generated, it's output not input. The proposal here makes it more likely we could add markers to the OpenAPI spec.

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/CACpe13n0PcuD1E-s%2BFgeQkPMJDmaki_1H8BVacpcurL0T8JWeg%40mail.gmail.com.

[Hippie Hacker]

I’m on board the creation of additional markers in the OpenAPI spec, as outlined by Tim:

```
// +feature-gate: MyGateName
```

And expanded upon by Clayton "for fields to be given alpha/beta labels”:

```
// +level: alpha
```

Are there existing examples/patterns for existing markers exported to OpenAPI we want to follow within the codebase already?

Are there things we would do differently due to what was learned from previous attempts?

It seems we have a pretty good consensus that this is a an overall good idea.

What should the next step.. a google doc precursor to a KEP?

> On 9/02/2021, at 10:58 AM, Daniel Smith <dbs...@google.com> wrote:
>
> On Mon, Feb 8, 2021 at 1:31 PM Hippie Hacker <h...@ii.coop> wrote:
> While KEPs are a great place to discuss and checklist features+operations, I do think the definitive source should be the openapi spec.
>
> There is not really a way we could get that information into the OpenAPI spec without adding the mechanism Tim started the thread off with, or one significantly like it.

Also should we look at learning from or resurrecting some previous related attempts?

WIP - Conditional openapi POC #70187
https://github.com/kubernetes/kubernetes/pull/70187
"This is an exploratory PR looking into what it would take to let maturity level and feature enablement inform our openapi and decoding pipelines.”

Field-level versioning #34508
https://github.com/kubernetes/kubernetes/issues/34508
https://docs.google.com/document/d/1wuoSqHkeT51mQQ7dIFhUKrdi3-1wbKrNWeIL4cKb9zU/edit#heading=h.3sjjx2gvn9hz

[Tim Hockin]

On my heap of backlog is "write this KEP".  It should be a small one.  I am very open to help or handing it off entirely, if you are wanting it Hippie :)

[Daniel Smith]

On Tue, Feb 16, 2021 at 10:23 PM 'Tim Hockin' via kubernetes-sig-architecture <kubernetes-si...@googlegroups.com> wrote:

On my heap of backlog is "write this KEP".  It should be a small one.

I'm not sure, the request is small but the implementation isn't totally straightforward. To be successful I think it's more important to line up implementers and reviewers. There's not that many folks who can review changes to this stack and they tend to be pretty busy. So in addition to the prioritization question (we're already completely subscribed for the upcoming release), we'd of course prefer implementers who will pay it forward by sticking around and help improve our review bandwidth in the future :)

 

--

You received this message because you are subscribed to the Google Groups "kubernetes-sig-architecture" group.
To unsubscribe from this group and stop receiving emails from it, send an email to kubernetes-sig-arch...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/CAO_RewZP6G1qwva%2B7yDDOSdrobtGELXaZwESOkOmRd58k-ODYQ%40mail.gmail.com.

[Tim Bannister]

If someone starts a KEP for this improvement and puts in at least the headings, I can try to flesh out how I think it could work.

(My perspective is about wanting to consume this data for https://k8s.io/docs/)

[h...@ii.coop]

nikhita is creating a very early POC for https://github.com/kubernetes/kubernetes/pull/99307.

I'm on board with this, though wanted to ensure other sig-arch folks had eyes on it as well.

[Tim Hockin]

KEP: https://github.com/kubernetes/enhancements/issues/2558

PR: https://github.com/kubernetes/kubernetes/pull/99902

To view this discussion on the web visit https://groups.google.com/d/msgid/kubernetes-sig-architecture/63e1d924-4020-4451-900b-a1615bb3b27an%40googlegroups.com.