Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

KEP-2887: Enum Types for OpenAPI #2888

Merged
merged 21 commits into from
Sep 9, 2021
Merged

KEP-2887: Enum Types for OpenAPI #2888

merged 21 commits into from
Sep 9, 2021

Conversation

jiahuif
Copy link
Member

@jiahuif jiahuif commented Aug 20, 2021 •
edited
Loading

  • One-line PR description: This PR creates design for KEP-2887
  • Other comments:

/label tide/merge-method-squash

@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/kep Categorizes KEP tracking issues and PRs modifying the KEP directory labels Aug 20, 2021
@k8s-ci-robot k8s-ci-robot added sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels Aug 20, 2021
@jiahuif jiahuif force-pushed the kep/2887-enum-types-for-openapi branch 2 times, most recently from cc9d300 to 377b574 Compare September 2, 2021 21:49
@jiahuif jiahuif changed the title [WIP] KEP-2887 Enum Types for OpenAPI KEP-2887 Enum Types for OpenAPI Sep 2, 2021
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Sep 2, 2021
@jiahuif jiahuif force-pushed the kep/2887-enum-types-for-openapi branch from 377b574 to 260d1ec Compare September 2, 2021 21:51
@jiahuif jiahuif changed the title KEP-2887 Enum Types for OpenAPI KEP-2887: Enum Types for OpenAPI Sep 2, 2021
@jiahuif jiahuif force-pushed the kep/2887-enum-types-for-openapi branch from 260d1ec to 3d73130 Compare September 2, 2021 21:53
@jiahuif
Copy link
Member Author

jiahuif commented Sep 2, 2021

/assign @jpbetz @apelisse

Could you take a look?

@jiahuif
Copy link
Member Author

jiahuif commented Sep 2, 2021

/assign @deads2k

For PRR.

@jiahuif jiahuif force-pushed the kep/2887-enum-types-for-openapi branch from 3d73130 to 2eeafee Compare September 2, 2021 22:23
jpbetz
jpbetz reviewed Sep 3, 2021
View reviewed changes
Copy link
Contributor

@jpbetz jpbetz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One minor comment. Looks good to me otherwise.
(disclaimer: I've seen a preview of this, so already got a chance to provide some feedback).

keps/sig-api-machinery/2887-openapi-enum-types/README.md Outdated Show resolved Hide resolved
@jiahuif jiahuif force-pushed the kep/2887-enum-types-for-openapi branch from 2eeafee to c7dc0ff Compare September 8, 2021 18:39
@jiahuif jiahuif force-pushed the kep/2887-enum-types-for-openapi branch from c7dc0ff to 9e09352 Compare September 8, 2021 18:47
@jiahuif jiahuif force-pushed the kep/2887-enum-types-for-openapi branch 3 times, most recently from 61fe574 to 747dee2 Compare September 8, 2021 20:02
@jpbetz
Copy link
Contributor

jpbetz commented Sep 8, 2021

/lgtm
(disclaimer: I've reviewed this in it's pre-KEP format a couple times so already had the opportunity to give feedback)

@deads2k
Copy link
Contributor

deads2k commented Sep 9, 2021

The approach suggested here that allows for improving openapi v2 suggests to me that this could be delivered separately of the main openapi v3. The PRR and pruning approach look reasonable.

/approve

I think @lavalamp has the last remaining comments.
/assign @lavalamp

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Sep 9, 2021
apelisse
apelisse reviewed Sep 9, 2021
View reviewed changes
keps/prod-readiness/sig-api-machinery/2887.yaml
@@ -0,0 +1,3 @@
kep-number: 2887
alpha:
approver: "@deads2k"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How come you're missing so many fields here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's the PRR, scroll down a bit for the main KEP YAML.

keps/sig-api-machinery/2887-openapi-enum-types/README.md
- Add a marker that indicates a field as an enum.
- Make the Kubernetes OpenAPI generator recognize the marker.
- Deduce values of an enum type from its Go type definition.
- Detect and annotate enum types in all built-in types.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is this a one time thing? We'll use a one time script to annotation to all types once, review the PR and then forget about the script?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is the "linter" thing that is also under discussion. The plan is to run the linter for the first time expecting tons of warnings, then check each to see if it is right or false positive. Afterwards, it checks for enums in new types.

keps/sig-api-machinery/2887-openapi-enum-types/README.md Outdated Show resolved Hide resolved
keps/sig-api-machinery/2887-openapi-enum-types/README.md
When generating OpenAPI schema, the de facto enum types should be reflected as enums in the resulting schema.

We define enum types with following properties:
- All enum types are closed, i.e., the type includes a finite number of possible values.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They are closed from a server-side perspective (server won't allow any unknown value). Clients, for backwards compatibility reasons, should consider it open (new values are possible).

keps/sig-api-machinery/2887-openapi-enum-types/README.md Outdated Show resolved Hide resolved
@lavalamp
Copy link
Member

lavalamp commented Sep 9, 2021

/lgtm
/approve
/hold

Hold for minor language tweaks, lgtm because I'll be afk for a few hours and don't want to hold anything up.

@k8s-ci-robot k8s-ci-robot added do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. lgtm "Looks good to me", indicates that a PR is ready to be merged. labels Sep 9, 2021
@k8s-ci-robot
Copy link
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: deads2k, jiahuif, lavalamp

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@k8s-ci-robot k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 9, 2021
@jpbetz
Copy link
Contributor

jpbetz commented Sep 9, 2021

/lgtm

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 9, 2021
@jiahuif
Copy link
Member Author

jiahuif commented Sep 9, 2021

/hold cancel

For having got approval from all requested reviewers.

@k8s-ci-robot k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Sep 9, 2021
@k8s-ci-robot k8s-ci-robot merged commit bc9d6c9 into kubernetes:master Sep 9, 2021
@k8s-ci-robot k8s-ci-robot added this to the v1.23 milestone Sep 9, 2021
rikatz pushed a commit to rikatz/enhancements that referenced this pull request Feb 1, 2022
@jiahuif @lavalamp @rikatz
KEP-2887: Enum Types for OpenAPI (kubernetes#2888)
7799418 
* [PRR] KEP-2887 Enum Type for OpenAPI

* KEP-2887: OpenAPI Enum Types

* annotation -> marker

* reword value auto-detection.

* kube-builder syntax compatibility.

* re-target to OpenAPI v2.

* field pruning for disabling this feature.

* goal: unify with kubebuilder.

* Update keps/sig-api-machinery/2887-openapi-enum-types/README.md

Co-authored-by: Daniel Smith <[email protected]>

* rewrite non-goals.

* Update keps/sig-api-machinery/2887-openapi-enum-types/README.md

Co-authored-by: Daniel Smith <[email protected]>

* reword enum field pruning.

* preprocessor for these don't want enums.

* update TOC.

* Update keps/sig-api-machinery/2887-openapi-enum-types/README.md

Co-authored-by: Daniel Smith <[email protected]>

* polish assumptions on impl.

* Update keps/sig-api-machinery/2887-openapi-enum-types/README.md

Co-authored-by: Daniel Smith <[email protected]>

* reword non-goal

* allow client open enum.

* omit the enum linter.

may add it back later.

* update TOC.

Co-authored-by: Daniel Smith <[email protected]>
@palnabarun palnabarun mentioned this pull request Jun 12, 2022
Closed
@palnabarun palnabarun mentioned this pull request Jul 26, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@jpbetz jpbetz jpbetz left review comments

@lavalamp lavalamp lavalamp left review comments

@sttts sttts sttts left review comments

@apelisse apelisse apelisse left review comments

@deads2k deads2k deads2k left review comments

@leilajal leilajal Awaiting requested review from leilajal

Assignees

@jpbetz jpbetz

@lavalamp lavalamp

@apelisse apelisse

@deads2k deads2k

Labels
approved Indicates a PR has been approved by an approver from all required OWNERS files. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/kep Categorizes KEP tracking issues and PRs modifying the KEP directory lgtm "Looks good to me", indicates that a PR is ready to be merged. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges.
Projects
None yet
Milestone
v1.23
Development

Successfully merging this pull request may close these issues.
7 participants
@jiahuif @jpbetz @deads2k @lavalamp @k8s-ci-robot @sttts @apelisse