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.

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

Generated clients using closed enums from an openapi snapshot are not forwards compatible #109177

Open
liggitt opened this issue Mar 31, 2022 · 13 comments
Assignees
Labels
kind/bug Categorizes issue or PR as related to a bug. lifecycle/frozen Indicates that an issue or PR should not be auto-closed due to staleness. priority/important-longterm Important over the long term, but may not be staffed and/or may need multiple releases to complete. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. triage/accepted Indicates an issue or PR is ready to be actively worked on.

Comments

@liggitt
Copy link
Member

liggitt commented Mar 31, 2022

Related to generating clients using closed language-level enums based on kubernetes/enhancements#2887

Some of the currently marked +enum fields are documented to allow expansion in the future, which would break clients generated against earlier openapi schemas:

  • // CompletionMode specifies how Pod completions of a Job are tracked.
    // +enum
    type CompletionMode string
    
      // More completion modes can be added in the future.
    
  • These are only well-known types, other types are allowed:

    // RequestConditionType is the type of a CertificateSigningRequestCondition
    // +enum
    type RequestConditionType string
    
  • This makes explicit reference to a future value we want to add:

    // +enum
    type TaintEffect string
      // NOT YET IMPLEMENTED. TODO: Uncomment field once it is implemented.
      // Like TaintEffectNoSchedule, but additionally do not allow pods submitted to
      // Kubelet without going through the scheduler to start.
      // Enforced by Kubelet and the scheduler.
      // TaintEffectNoScheduleNoAdmit TaintEffect = "NoScheduleNoAdmit"
    
  • We've regularly added new resourcequota scopes:

    // A ResourceQuotaScope defines a filter that must match each object tracked by a quota
    // +enum
    type ResourceQuotaScope string
    
  • Docs reference "currently supported" values, which sounds like there could be expansion in the future:

    // AddressType represents the type of address referred to by an endpoint.
    // +enum
    type AddressType string
    
    The following address types are currently supported:
      // * IPv4: Represents an IPv4 Address.
      // * IPv6: Represents an IPv6 Address.
      // * FQDN: Represents a Fully Qualified Domain Name.
    

More concerning, this breaks deserialization of new values by old generated clients using enums. I didn't see this aspect discussed in the KEP at all, and it's fairly significant.

Originally posted by @liggitt in #105057 (comment)

@k8s-ci-robot k8s-ci-robot added needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Mar 31, 2022
@liggitt
Copy link
Member Author

liggitt commented Mar 31, 2022

/cc @jiahuif

@liggitt liggitt changed the title OpenAPIEnums produce generated clients that are not forwards compatible Generated clients using enums from an openapi snapshot are not forwards compatible Mar 31, 2022
@liggitt liggitt added kind/bug Categorizes issue or PR as related to a bug. priority/important-soon Must be staffed and worked on either currently, or very soon, ideally in time for the next release. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. and removed kind/bug Categorizes issue or PR as related to a bug. labels Mar 31, 2022
@k8s-ci-robot k8s-ci-robot removed the needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. label Mar 31, 2022
@dims
Copy link
Member

dims commented Mar 31, 2022

/milestone v1.24
/priority critical-urgent

@k8s-ci-robot k8s-ci-robot added the priority/critical-urgent Highest priority. Must be actively worked on as someone's top priority right now. label Mar 31, 2022
@k8s-ci-robot
Copy link
Contributor

@dims: The provided milestone is not valid for this repository. Milestones in this repository: [next-candidate, v1.16, v1.17, v1.18, v1.19, v1.20, v1.21, v1.22, v1.23, v1.24, v1.25, v1.26]

Use /milestone clear to clear the milestone.

In response to this:

/milestone v.124
/priority critical-urgent

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

@dims dims added this to the v1.24 milestone Mar 31, 2022
@fedebongio
Copy link
Contributor

/cc @leilajal
/triage accepted

@k8s-ci-robot k8s-ci-robot added triage/accepted Indicates an issue or PR is ready to be actively worked on. and removed needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Mar 31, 2022
@liggitt liggitt changed the title Generated clients using enums from an openapi snapshot are not forwards compatible Generated clients using closed enums from an openapi snapshot are not forwards compatible Mar 31, 2022
@liggitt
Copy link
Member Author

liggitt commented Mar 31, 2022

Changes for 1.24 are merged, lowering priority and removing from milestone

@liggitt liggitt added priority/important-longterm Important over the long term, but may not be staffed and/or may need multiple releases to complete. and removed priority/critical-urgent Highest priority. Must be actively worked on as someone's top priority right now. labels Mar 31, 2022
@liggitt liggitt removed this from the v1.24 milestone Mar 31, 2022
@liggitt
Copy link
Member Author

liggitt commented Mar 31, 2022

This still needs to be addressed in the KEP and coordinated with generated clients before the feature hits GA and our static snapshot unconditionally contains enum info

@liggitt liggitt added lifecycle/frozen Indicates that an issue or PR should not be auto-closed due to staleness. and removed priority/important-soon Must be staffed and worked on either currently, or very soon, ideally in time for the next release. labels Mar 31, 2022
@k8s-triage-robot
Copy link

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

  • Confirm that this issue is still relevant with /triage accepted (org members only)
  • Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

@k8s-ci-robot k8s-ci-robot added needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. and removed triage/accepted Indicates an issue or PR is ready to be actively worked on. labels Apr 5, 2023
@cici37
Copy link
Contributor

cici37 commented Apr 6, 2023

/triage accepted
/cc @jiahuif Just to make sure you are aware of this one^^

@k8s-ci-robot k8s-ci-robot added triage/accepted Indicates an issue or PR is ready to be actively worked on. and removed needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Apr 6, 2023
@apelisse
Copy link
Member

apelisse commented Aug 8, 2023

Discussed this with Alex. Enum is not a type here, the type is still string, int, or whatever. Clients should accept values that they don't know about since they might not know about the most recent versions. We need to work with client generators so that they don't generate enums that can't be be extended.

@jiahuif
Copy link
Member

jiahuif commented Aug 8, 2023

My plan is to create a CLI tool to remove enum tags from openapi specs for generated clients. The trade-off is that such clients are not aware of the enums in any way unless they fetch the schema from the api server and parse themselves. How do you think of it? @apelisse

@apelisse
Copy link
Member

apelisse commented Aug 8, 2023

I think that's wrong. It's not that clients shouldn't be aware of enums, they should be doing the right thing. They have plenty of options.

If I was building a rust client, I would generate the following:

enum Color {
    Red,
    Blue,
    Green,
    Unknown(color),
}

And clients should be able to generate such a thing.

@jiahuif
Copy link
Member

jiahuif commented Aug 8, 2023

Because client generation uses standard OpenAPI client generator for each language, and there does not seem to be a "enum mode" switch, I guess the plan would be hack the generator for each language.

@apelisse
Copy link
Member

apelisse commented Aug 8, 2023

Because client generation uses standard OpenAPI client generator for each language, and there does not seem to be a "enum mode" switch, I guess the plan would be hack the generator for each language.

😞 . You're right. Then yeah, maybe a tool to filter out the enum is the right way to go, though another option might be to talk to some of these standard openapi client generator to see if we can make that work? I still think it's a little weird to block any updates to enums.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind/bug Categorizes issue or PR as related to a bug. lifecycle/frozen Indicates that an issue or PR should not be auto-closed due to staleness. priority/important-longterm Important over the long term, but may not be staffed and/or may need multiple releases to complete. sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. triage/accepted Indicates an issue or PR is ready to be actively worked on.
Projects
None yet
Development

No branches or pull requests

8 participants