✨ Change CRD generation logic to honor k8s:immutable #1216

lalitc375 · 2025-06-18T20:36:59Z

This change adds logic to understand and interpret k8s:immutable tag in controller-gen. This tag is getting introduced for native types in K8s as part of 5073-declarative-validation-with-validation-gen KEP.

On detecting the tag, A CEL validation is added for the corresponding field.

k8s-ci-robot · 2025-06-18T20:37:05Z

[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 assign vincepri for approval. 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

k8s-ci-robot · 2025-06-18T20:37:07Z

Welcome @lalitc375!

It looks like this is your first PR to kubernetes-sigs/controller-tools 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/controller-tools has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2025-06-18T20:37:08Z

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.

alvaroaleman · 2025-06-18T22:25:33Z

pkg/crd/markers/validation.go

+func (Immutable) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
+	schema.XValidations = append(schema.XValidations, apiext.ValidationRule{
+		Message: "Value is immutable",
+		Rule:    "self == oldSelf",


Won't this error out in the create case as oldSelf will be undefined?

It won't, there is always a "oldSelf" since the rule is attached to the field and only takes effect when the field exists.

since the rule is attached to the field and only takes effect when the field exists.

Not quite true, but it's still safe.

Rules that include oldSelf are known as transition rules, and the CEL implementation detects that a rule is a transition rule.

It will only run a transition rule when it has a value for both self and oldSelf. So only on updates, not when the field first appears.

But, you could have a rule without oldSelf, in which case, the rule would run even when the field first appears.

There's also optionalOldSelf which allows transition rules to run when there is no value for oldSelf, but you have to handle those differently.

Which brings me to... The semantic here is that I could have an object with a field we say is immutable. What does it actually mean to be immutable?

There are two interpretations IMO:

Once a value has been set for X, it cannot be changed (omitted -> set is allowed on updated)

Value for X can only be set on create (omitted counts as a value)

This implements the first of those, how does it work in the declarative validation project?

If it is the latter, we would need an optionalOldSelf rule and implement a different validation rule

Thank you @JoelSpeed for providing insights on CEL rules.

+k8s:immutable in Declarative validation project can allow setting empty value to non-empty value during update, but it doesn't allow changing value from one non-empty to another non-empty. So, it is the following interpretation.
Once a value has been set for X, it cannot be changed (omitted -> set is allowed on updated)

It doesn't allow setting non-empty to empty in update. Which the current cel expression will allow. I will see how this can be achieved.

Is there a way for us to have tests that actually test the contents of the CEL rule? This seems pretty easy to get wrong and once we've released something like this, fixing it up will be extremely difficult/impossible

We could set up an envtest style integration suite and create a series of Create/Update calls to test the validations. That would be my preferred route for testing these at least

Which the current cel expression will allow. I will see how this can be achieved.

The only way I've found to do this is to make sure that the nearest required parent has a rule that says if the field exists, it cannot be removed. But there may be something smarter we can do

alvaroaleman · 2025-06-18T22:25:45Z

/ok-to-test

yongruilin

/cc @aaron-prindle
PTAL if this align with stand alone +k8s:immutable tag in latest design.

yongruilin · 2025-06-19T00:22:49Z

pkg/crd/markers/validation.go

+func (Immutable) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
+	schema.XValidations = append(schema.XValidations, apiext.ValidationRule{
+		Message: "Value is immutable",
+		Rule:    "self == oldSelf",


It won't, there is always a "oldSelf" since the rule is attached to the field and only takes effect when the field exists.

k8s-ci-robot · 2025-06-19T00:24:11Z

@yongruilin: GitHub didn't allow me to request PR reviews from the following users: aaron-prindle.

Note that only kubernetes-sigs members and repo collaborators can review this PR, and authors cannot review their own PRs.

In response to this:

/cc @aaron-prindle
PTAL if this align with stand alone +k8s:immutable tag in latest design.

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-06-19T05:41:01Z

cc @JoelSpeed

lalitc375 · 2025-06-20T17:34:05Z

/hold

aaron-prindle · 2025-06-23T20:04:35Z

/cc @aaron-prindle PTAL if this align with stand alone +k8s:immutable tag in latest design.

From the KEP Update:
https://github.com/kubernetes/enhancements/blob/master/keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md#immutability-validation

Related WIP dev-branch PR here: jpbetz/validation-gen#103

The semantics for +k8s:immutable are:

Can be set or unset at creation
Allows ONE transition (if unset): set (unset->set)
Forbids: modify and clear (set->unset)

The semantics for +k8s:frozen are:

Can be set or unset at creation
Forbids: set, modify, and clear (set->unset)

jpbetz · 2025-06-24T16:43:17Z

/cc @aaron-prindle PTAL if this align with stand alone +k8s:immutable tag in latest design.

From the KEP Update: kubernetes/enhancements@master/keps/sig-api-machinery/5073-declarative-validation-with-validation-gen/README.md#immutability-validation

Related WIP dev-branch PR here: jpbetz/validation-gen#103

The semantics for +k8s:immutable are:

Can be set or unset at creation

Allows ONE transition (if unset): set (unset->set)

Forbids: modify and clear (set->unset)

The semantics for +k8s:frozen are:

Can be set or unset at creation

Forbids: set, modify, and clear (set->unset)

+1

Would something along the lines of !optionalOldSelf.hasValue() || optionalOldSelf == optional.of(self) do the trick? We need tests that demonstrate the behavior aligns with jpbetz/validation-gen#103.

EDIT: Modified CEL proposal to account for the fact that our conversion from Go to CEL types already accounts for omitempty.

jpbetz · 2025-06-24T17:16:12Z

pkg/crd/markers/validation.go

@@ -325,6 +328,19 @@ type XIntOrString struct{}
 // to be used only as a last resort.
 type Schemaless struct{}

+// +controllertools:marker:generateHelp:category="CRD validation"
+// Immutable marks a field as immutable.
+// The value of an immutable field may not be changed after creation.


Let's expand the semantics here to clarify what exact transitions are allowed.

Let's use the term "set" instead of "creation" here since immutable fields can set after initial resource creation.

Change CRD generation logic to honor k8s:immutable

cbf0e96

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

k8s-ci-robot requested review from joelanford and vincepri June 18, 2025 20:37

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 Jun 18, 2025

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

alvaroaleman reviewed Jun 18, 2025

View reviewed changes

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 Jun 18, 2025

yongruilin reviewed Jun 19, 2025

View reviewed changes

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jun 20, 2025

lalitc375 marked this pull request as draft June 20, 2025 17:34

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jun 20, 2025

jpbetz reviewed Jun 24, 2025

View reviewed changes

✨ Change CRD generation logic to honor k8s:immutable #1216

Are you sure you want to change the base?

✨ Change CRD generation logic to honor k8s:immutable #1216

Uh oh!

Conversation

lalitc375 commented Jun 18, 2025

Uh oh!

k8s-ci-robot commented Jun 18, 2025

Uh oh!

k8s-ci-robot commented Jun 18, 2025

Uh oh!

k8s-ci-robot commented Jun 18, 2025

Uh oh!

alvaroaleman Jun 18, 2025

Choose a reason for hiding this comment

Uh oh!

yongruilin Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

JoelSpeed Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

lalitc375 Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

alvaroaleman Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

JoelSpeed Jun 23, 2025

Choose a reason for hiding this comment

Uh oh!

alvaroaleman commented Jun 18, 2025

Uh oh!

yongruilin left a comment

Choose a reason for hiding this comment

Uh oh!

yongruilin Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

k8s-ci-robot commented Jun 19, 2025

Uh oh!

sbueringer commented Jun 19, 2025

Uh oh!

lalitc375 commented Jun 20, 2025

Uh oh!

aaron-prindle commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jpbetz commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jpbetz Jun 24, 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!

Uh oh!

aaron-prindle commented Jun 23, 2025 •

edited

Loading

jpbetz commented Jun 24, 2025 •

edited

Loading

jpbetz Jun 24, 2025 •

edited

Loading