Kubebuilder docs should more clearly state the interaction between kubebuilder:validation:Required and omitempty

[jmeyers35]

What broke? What's expected?

This is purely a docs ask. I've run into the behavior noted in kubernetes-sigs/controller-tools#599 a handful of times, and I think that it can be pretty surprising. The most recent time I've hit this, it caused us to break backwards compatibility in a user's CRD when we removed an omitempty tag on a field. I think that the interaction between the required tag and omitempty should be more explicitly stated in the documentation (and maybe a warning added at generation time: you probably don't actually want both required and omitempty).

Reproducing this issue

No response

KubeBuilder (CLI) Version

N/A

PROJECT version

No response

Plugin versions

No response

Other versions

No response

Extra Labels

/kind documentation

[camilamacedo86]

Hi @jmeyers35,

Thank you for raising this one.

However, note that all documentation in kubebuilder is generated automatically via what is the doc in the source code of controller-tools. Therefore:

• a) Can you please transfer this issue to the controller-tools repo. Your request cannot be addressed via Kubebuilder repo/code source or project

• b) WDYT about open a pull request for controller-tools with the changes that you suggest. Therefore, when a new controller-tool release is made with it, the Kubebuilder docs will be updated.

Thank you for attention.

@vincepri @joelanford (could you please move this issue to controller-tools if the owner be unable to do so?)

[jmeyers35]

I'm happy to open a PR for this at some point, but I wanted to flag this in case someone can get around to it before I can. I also could've been a bit more specific - when I said "documentation", I really meant the book, which I believe is indeed in this repo. But this is probably worth noting in the generated docs as well.

[camilamacedo86]

Hi @jmeyers35,

That is great. I see, the info that you would like to add in the docs is:

Update:
The omitempty tag in Foo string json:"foo,omitempty" had more precedence than the kubebuilder marker +kubebuilder:validation:Required therefore making the resultant generated crd field to be optional.

The +kubebuilder:validation:Required marker does works as desired when omitempty is not used.

I am not able to recall if docs(https://book.kubebuilder.io/) mentions it, but I hope it does.

With that I mark this issue to be closed.

Following some examples that I hope that help you:

• If you want to update the info in: https://book.kubebuilder.io/reference/markers/crd-validation then, I belive that the change must to be in: https://github.com/kubernetes-sigs/controller-tools/blob/master/pkg/crd/markers/validation.go#L77

• if you want to add something in https://book.kubebuilder.io/reference/markers.html?highlight=omitempty#markers-for-configcode-generation then, it lives in this repo.

Please feel free to open a PR with your suggestion on where you see that it should fit, and then we can move forward from there. Thank you for your collaboration 🥇

[camilamacedo86]

Hi @jmeyers35

After share above the info to you, do you think that it still requiring further explanation?
Would you like to contribute with this one?