improvement(dev-ex): include code-generator specific metadata in CRDs

[the-wondersmith]

Opening this to facilitate discussion of issues #38 and #39 on the kube-rs/gateway-api-rs repo.

In short:

• issue 38 details a proposed improvement to the code auto-generated from the Gateway API CRDs that would ensure compatible/identical types are defined once and automatically reused where ever possible
• issue 39 (spiritually) follows on and proposes that the CRDs serve as the single source of truth for constant values, enabling reduced maintenance burden in the golang code base and a similar enhancement in auto-generated code (i.e. gateway-api-rs)

I initially discussed the idea with @shaneutt and @kflynn, and all agreed that the CRDs would likely be the best place for the alterations to be made (as they can and should serve as the ultimate source of truth).

[shaneutt]

CRDs definitely seem to be a potential place we could put hints for code generators [for other languages]. As I understand it Google has a Java client for Gateway API as well: @robscott do you think such hints could be helpful for that?

[robscott]

I'm not sure - what would these hints look like?

[shaneutt]

It's completely open to interpretation, but at a high level we might consider generating unique identifiers for types so that when emitted in multiple places a code generator for other languages can do a surface level correlation (instead of needing to do deep inspection and comparison).

It's plausible we could have these identifiers be human-readable and look like helpful hints to people as well. We can also consider whether we would emit these on the standard published manifests, or if we would have a separate emission for developer manifests which include these annotations. The slight "jank factor" of this is definitely not lost on me, so right now it's mostly about floating the general ideas out to see if anyone has some strong support (also needs this) or has some strong arguments against.

In the Rust world we have kopium (which, importantly is what gateway-api-rs utilizes under the hood) and with that tool we (as in Rust users) at least technically have another way we could do the type correlations. However, if we find the need is greater and there are more groups out there with more languages all trying to do Gateway API stuff like we are right now, it might ultimately just make sense to have provisions for this sort of development activity upstream?

[the-wondersmith]

@shaneutt that's a good point about kopium - changes may (likely) need to be made in any given code generation tool, but the CRDs would (should) still need to provide the relevant information to be acted on to begin with.

To field at least a partial answer @robscott's question: I haven't had the time to fully chase it down but when Shane originally brought up the idea of adding the relevant metadata to the CRDs, I immediately thought of how the OpenAPI schema/syntax allows for explicit references and thought there might be some room to play with there by leveraging the components field of a CRDs OpenAPI-formatted spec (i.e. code generators would be able to determine if a given type is reused based on whether it's uniquely defined or is a $ref in the spec). I think a similar trick might serve for hinting constant values, but again time and tide 🥲.

I'm working on getting a POC whacked together, FWIW

[shaneutt]

@kflynn, @robscott, @the-wondersmith: I think we should make one more push to discuss this in a community sync, but I'm inclined to think nobody else out there really has this need. Normally for new features and changes we would want multiple different groups to have a need and be invested, but this is a bit of an unusual case. If nobody is strongly opposed, since our changes would just be decorations that could be ignored on CRDs I'm wondering if it would be reasonable to try it? Alternatively, we could just look and see if we wanna try the kopium route.

[robscott]

If we can find a way to add these kinds of decorations in a way that are also ignored via any user-facing docs, I'm good. The problem is that historically the contents of this have been used for reference docs and to drive things like kubectl explain. We've found ways to keep godocs out of CRDs with our custom CRD generation, but I think your current method of generating clients requires these hints to be in CRDs, and I can't think of a good place to hide these kinds of hints.

[kflynn]

@the-wondersmith @shaneutt Yeah, I think more than anything else we need to know what this would look like (to the developer and to the end user)...

[shaneutt]

I believe @the-wondersmith is going to put it on the agenda for discussion at an upcoming community sync. I'm cool with us doing that, and then maybe following up with a brainstorming session with any interested parties?

[kflynn]

@shaneutt We talked about it a bit at yesterday's Gateway API meeting, actually, though unfortunately you'd had to drop before we got to it. 🙂