Document how to use list-type and list-keys in a CRD, including in existing clusters.

[erictune]

I'm told that 1.16 supports interpreting a CRD which has x-kubernetes-list-map-type and x-kubernetes-list-map-keys properties.

Please document somewhere an example of a CRD that uses these, so the syntax is clear.

Please also document what happens if I have an already-installed CRD with existing CR state, and I am already using SSA, and I update a property of my CRD from not having x-kubernetes-list-* annotations to having them. That is, what happens if an existing user adopts this nice new feature? Does it DTRT or explode?
For existing CRs that have been applied before. That haven't? For new CRs?

@apelisse we just discussed this.

[apelisse]

I have done or plan on doing:

• Split into multiple tasks and added to the umbrella issue
• Documented in the KEP Apply KEP: Document toplogy kubernetes/enhancements#1320
• Created a PR to add support in kubebuilder ✨ Add support for ListType, ListMapKeys, MapType and StructType controller-tools#347
• Implement +mapType and +structType in kube-openapi (https://github.com/kubernetes/kube-openapi/blob/master/pkg/generators/extension.go#L38-L57): Support +mapType, +structType markers kubernetes/kube-openapi#178
• Document how removing list/map items work for CRD and Built-in types with SSA: Within Server-side apply, document map and list merging behaviors. kubernetes/website#16725
• Document difference between marker and tags in built-in types (see [WIP] Document patch strategy markers in api-conventions kubernetes/community#4218 (comment))
• Update API Conventions api-conventions.md should explain patchStrategy kubernetes/community#3752
• Created a new section in CRD docs for topology (no PR yet)
• Topology compatibility:
  • Understand how changing the topology affects API compatibility
  • Document these guarantees/limitations
  • Write tests to validate the guarantees
• Make sure that atomic is properly documented as recursive
• Make sure that sets and map keys are documented as scalar or atomic
• +listType has both associative and map in different places: pick one and apply everywhere
• Document list keys have to be "scalar"
• Try to guess good keys if we find one on a list Suggest listType=map if we can guess good key options kubernetes/kubernetes#87674

[mariantalla]

(as discussed on #wg-apply)
/assign

[apelisse]

I just found some documentation for this here: https://github.com/kubernetes/kube-openapi/blob/master/pkg/idl/doc.go

I have no memory of writing this, but sure. Also I don't think +mapTypeand +structType are implemented in this repo, so I'm adding an extra item to the plan.

[apelisse]

https://github.com/kubernetes/kube-openapi/blob/master/pkg/generators/extension.go#L38-L57

This is probably doing most of the work, so updating this should be straightforward.

[mariantalla]

Thanks for the links @apelisse 👌 I'm starting with kube-openapi support and will move on to kubebuilder after (will update with issue refs shortly)

[apelisse]

That sounds like a great plan! Thanks!

[mariantalla]

Support for +mapType and +structType in kube-openapi is covered (I think) with: kubernetes/kube-openapi#178.

[mariantalla]

...and support for x-kubernetes-map-type in controller-tools: apelisse/controller-tools#1 (which should land with kubernetes-sigs/controller-tools#347)

[apelisse]

Thanks @mariantalla I'll update my comment

[mariantalla]

WIP PR to api-conventions: kubernetes/community#4218