✨ Add k8s:required and k8s:optional markers #1247

lalitc375 · 2025-07-28T23:28:42Z

This commit introduces two new markers, k8s:required and k8s:optional, to allow marking fields in CRDs as required or
optional.

These IDL tags are introduced as part of the KEP for declarative validation: https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md

Adding this in controller-gen will allow understanding native types much better in CRDs.

k8s-ci-robot · 2025-07-28T23:28:52Z

Hi @lalitc375. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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-sigs/prow repository.

sbueringer · 2025-07-29T05:40:28Z

/assign @JoelSpeed
/ok-to-test

JoelSpeed · 2025-07-29T09:03:17Z

Adding this in controller-gen will allow understanding native types much better in CRDs.

Is the intention in native types that this will replace the existing +optional and +required tags, or are they intended to supplement them?

Do we expect to see only +k8s:optional and that to be sufficient, or, would we also expect +optional alongside?

I'm keen to see that the community settle on choices that bring consistency, but that also includes among codebases. In the [kube-api-linter](https://github.com/kubernetes-sigs/kube-api-linter] project, we recommend folks to replace +kubebuilder:validation:Optional with +optional at present so that their codebase is consistent. I'd like to know how this would fit in, if we decide to start supporting it here.

CC @yongruilin

lalitc375 · 2025-07-29T16:57:20Z

Adding this in controller-gen will allow understanding native types much better in CRDs.

Is the intention in native types that this will replace the existing +optional and +required tags, or are they intended to supplement them?

+optional and +required tags for native type are used to set/unset the openapi required field, it doesn't do any server side validation to enforce it. +k8s:required and +k8s:optional as of today, generate go code to perform server side validation. The working group also has a plan to set/unset the openAPI required property on seeing these new tags.

So, +optional/+required are not the same as of +k8s:optional/+k8s:required for native types. But these are the same for CRD's.

We will the same situation while adding support for k8s:listType and k8s:listMapKey

Do we expect to see only +k8s:optional and that to be sufficient, or, would we also expect +optional alongside?

For CRD's, both are the same thing, so one is sufficient. We can recommend devs to use the new ones only. For native types, we have to make sure the +k8s:optional/+k8s:required has the same behaviour as of existing ones for the openAPI required property, before making that recommendation.

I'm keen to see that the community settle on choices that bring consistency, but that also includes among codebases. In the [kube-api-linter]([https://github.com/kubernetes-sigs/kube-api-linter]](https://github.com/kubernetes-sigs/kube-api-linter%5D) project, we recommend folks to replace +kubebuilder:validation:Optional with +optional at present so that their codebase is consistent. I'd like to know how this would fit in, if we decide to start supporting it here.

I totally agree with you on the consistency part, Kubelinter should recommend the new ones, once the features are complete.

JoelSpeed · 2025-07-30T08:27:03Z

I totally agree with you on the consistency part, Kubelinter should recommend the new ones, once the features are complete.

Do we have an estimated timeline for the declarative validation project to be stable enough that there's no going back? I understand at the moment that it's all gated and could all be taken out should the project stall.

If we add these markers to controller-tools now, I'd expect we do something similar where we have an easy way to back out of the declarative validation markers in the future, could we put them behind a feature flag for now?

lalitc375 · 2025-08-01T17:52:29Z

we have an estimated timeline for the declarative validation project to be stable enough that there's no going back? I understand at the moment that it's all gated and could all be taken out should the project stall.

If we add these markers to controller-tools now, I'd expect we do something similar where we have an easy way to back out of the declarative validation markers in the future, could we put them behind a feature flag for now?

The DV Working group is working to get go/no-go from the API reviewers. We will soon have clarity on the decision. I will wait for this to happen, If it takes longer, I will feature-gate k8s:* tag related changes.

JoelSpeed · 2025-10-13T09:59:14Z

Based on recent updates to the DV EP, I can see that these markers are now marked as beta. I think given the direction of the project upstream, we are able to move forward now with implementing support for beta DV markers

@lalitc375 would you be able to get this rebased please?

k8s-ci-robot · 2025-10-13T23:38:36Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: lalitc375
Once this PR has been reviewed and has the lgtm label, please ask for approval from joelspeed. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

lalitc375 · 2025-10-13T23:42:36Z

@lalitc375 would you be able to get this rebased please?

done

This commit introduces `k8s:required` and `k8s:optional` markers to align with the declarative validation KEP. These markers serve as a Kubernetes-style alternative to the existing `+required` and `+optional` markers for marking CRD fields. This change allows controller-gen to better understand native types in CRDs, improving the declarative validation process. Reference: https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md

JoelSpeed · 2025-10-17T09:58:40Z

pkg/crd/markers/zz_generated.markerhelp.go

 	"sigs.k8s.io/controller-tools/pkg/markers"
 )

+func (AtLeastOneOf) Help() *markers.DefinitionHelp {


Huh, this doesn't seem related 🤔 Was the PR introducing this incorrect and didn't have this generated?

I would not be surprised if we don't enforce that this is regenerated

Until I fixed it it wasn't even enforced that go.mod files are up-to-date..

This is an autogenerated file. Seems like we missed it in the past. What are risks with checking in these changes now?

These are generated by running go generate in cmd/controller-gen

What are risks with checking in these changes now?

No risks, all good from my side

JoelSpeed · 2025-10-17T09:59:15Z

pkg/crd/markers/zz_generated.markerhelp.go

 		Category: "CRD validation",
 		DetailedHelp: markers.DetailedHelp{
-			Summary: "Default sets the default value for this field.",
+			Summary: "sets the default value for this field.",


Any idea why these are changing?

Note: generated :-)

These are generated by running go generate in cmd/controller-gen. Looks like missed in the past.

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jul 28, 2025

k8s-ci-robot requested review from alvaroaleman and chrischdi July 28, 2025 23:28

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Jul 28, 2025

k8s-ci-robot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Jul 28, 2025

lalitc375 force-pushed the k8s-required branch from 8c252b3 to fb957de Compare July 28, 2025 23:33

k8s-ci-robot assigned JoelSpeed Jul 29, 2025

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jul 29, 2025

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Sep 17, 2025

lalitc375 force-pushed the k8s-required branch from fb957de to 9b6a7d7 Compare October 13, 2025 23:38

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Oct 13, 2025

lalitc375 force-pushed the k8s-required branch from 9b6a7d7 to d7b3369 Compare October 13, 2025 23:44

lalitc375 force-pushed the k8s-required branch from d7b3369 to 8093c7e Compare October 13, 2025 23:45

JoelSpeed reviewed Oct 17, 2025

View reviewed changes

✨ Add k8s:required and k8s:optional markers #1247

Are you sure you want to change the base?

✨ Add k8s:required and k8s:optional markers #1247

Conversation

lalitc375 commented Jul 28, 2025

Uh oh!

k8s-ci-robot commented Jul 28, 2025

Uh oh!

sbueringer commented Jul 29, 2025

Uh oh!

JoelSpeed commented Jul 29, 2025

Uh oh!

lalitc375 commented Jul 29, 2025

Uh oh!

JoelSpeed commented Jul 30, 2025

Uh oh!

lalitc375 commented Aug 1, 2025

Uh oh!

JoelSpeed commented Oct 13, 2025

Uh oh!

k8s-ci-robot commented Oct 13, 2025

Uh oh!

lalitc375 commented Oct 13, 2025

Uh oh!

JoelSpeed Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

sbueringer Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

sbueringer Oct 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lalitc375 Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

sbueringer Oct 18, 2025

Choose a reason for hiding this comment

Uh oh!

JoelSpeed Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

chrischdi Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

lalitc375 Oct 17, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

sbueringer Oct 17, 2025 •

edited

Loading