Using component refs to types in generated schema

[mortenlj]

I'm looking at creating a tool to display API documentation for kubernetes types (specifically CRDs in my case), similar to https://kubespec.dev/
Most of the information I need is available in the schema in the cluster, but there is one detail that I haven't found a good solution for.

When different fields in a spec uses the same type, I have no way to detect that and refer to the same type in the documentation. Instead I end up describing the same fields over and over again.

For an instance of what I'm talking about, consider liveness, readiness and startup fields on Deployment. These are all the same Probe type, just located in different places in the schema. In the schemas for the native kubernetes types that kind of thing is solved by using component references for all complex types, which then always point to the same component.
This has the added benefit of naming all the types, which again helps when generating documentation from the schema.

How hard would it be for kube-derive to create components of all structs and use references instead of inlining the schemas?
Is it possible to do today without manually building the entire schema?

If all CRDs did this, kopium could make use of these to generate structs with better names and less duplication too.
Seeing as changing all CRDs is maybe a bit optimistic, making kube-derive do it could be a nice value-add and first step. 🙂

[clux]

How hard would it be for kube-derive to create components of all structs and use references instead of inlining the schemas?

There is a limitation in crd schemas atm; you cannot use $refs to other structs in crd schemas, and you have to inline everything. See links in kube-rs/gateway-api-rs#38 (comment)

Maybe there is some smart property we could use to signal from kube-derive in the mean time, but kube-derive kind of just acts on the root spec struct, so it doesn't really know about what you are reusing in substructs (nested deeply below the spec), so I imagine it'd be awkward to try to solve it there.

If you already have rust code, then presumably the rust code is ideally already deduplicated (i.e. using the same liveness etc structs under the hood) so docs for that case should be fine? The problem is more that kopium doesn't find duplicates, and there's no standard way to signal for them atm. Maybe we could add some kind of brute force algorith that cross-checks "is all fields the same as struct X" with every other struct, and if so "re-use that struct". That could be a nice addition perhaps (we have the skeletons of such code, but it only checks for a few known ones like Condition here). Probably it wouldn't be a particularly heavy operation on (at most) a few hundred kB of schema data. Maybe? WDYT? Happy to take experiments for this in kopium. EDIT: kube-rs/kopium#298

Otherwise, I am silently hoping that gateway api folks can help find a way to signal this. See this issue for context: kube-rs/gateway-api-rs#38 .