:sparkles: Add option to omit controller-gen version in generated output by pedjak · Pull Request #1437 · kubernetes-sigs/controller-tools

pedjak · 2026-06-17T16:10:18Z

What does this do, and why do we need it?

When controller-gen runs, it embeds its version into generated files:

CRD manifests include a controller-gen.kubebuilder.io/version annotation
ApplyConfiguration Go files include the binary name (which may contain a version suffix) in the Code generated by comment header

When a team upgrades controller-gen, every generated file shows a diff even though the actual schema, RBAC rules, or deepcopy logic is unchanged. This creates large, noisy pull requests that obscure real changes and complicate code review.

This PR adds per-generator options to opt out of including version information:

crd:omitToolVersion=true — omits the controller-gen.kubebuilder.io/version annotation from CRD manifests
applyconfiguration:omitToolVersion=true — normalizes the generator name to controller-gen in the Code generated by comment, preventing version-suffixed binary names from leaking into output

Both options default to false, preserving current behavior.

Fixes #1436

k8s-ci-robot · 2026-06-17T16:10:26Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: pedjak
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.

Details

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 · 2026-06-17T16:10:30Z

Hi @pedjak. 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.

Tip

We noticed you've done this a few times! Consider joining the org to skip this step and gain /lgtm and other bot rights. We recommend asking approvers on your previous PRs to sponsor you.

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.

Details

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.

pedjak · 2026-06-17T16:15:00Z

/assign @sbueringer @alvaroaleman @camilamacedo86

pedjak · 2026-06-17T16:16:23Z

/unassign @sbueringer @alvaroaleman @camilamacedo86
/cc @sbueringer @alvaroaleman @camilamacedo86

camilamacedo86 · 2026-06-17T17:41:31Z

+	// (controller-gen.kubebuilder.io/version) should be added to the CRD.
+	//
+	// Left unspecified, the default is true.
+	AddToolVersionAnnotation *bool `marker:",optional"`


The current behaviour is to have that by default so should not be skip something like?
I do not think we would like to change the default behaviour.

@camilamacedo86 Agreed, the default behavior stays unchanged — the annotation is always added unless you explicitly opt out.

Would you prefer a naming like SkipToolVersionAnnotation (default false, set to true to opt out)? Or do you have another suggestion in mind?

Done — renamed to SkipToolVersionAnnotation (default false, set to true to opt out). Also renamed the applyconfiguration field to SkipToolVersion for consistency.

kubernetes-prow · 2026-06-26T15:37:37Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: pedjak
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.

Details

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

camilamacedo86 · 2026-06-28T16:44:29Z

+	// (controller-gen.kubebuilder.io/version) should be skipped when generating the CRD.
+	//
+	// Left unspecified, the default is false.
+	SkipToolVersionAnnotation *bool `marker:",optional"`


Why not keep the same name for both places ?
Why not SkipToolVersion here as well?

WDYT?

Done — renamed to OmitToolVersion in both generators for consistency.

camilamacedo86 · 2026-06-28T16:52:22Z

 	ExternalApplyConfigurations []string `marker:",optional"`
+
+	// SkipToolVersion specifies if the tool version should be excluded from the
+	// "Code generated by" comment header. When true, the generator name is


helpgen only uses the first physical line of a field comment as the summary. Since the first sentence wraps onto a second line, the generated summary gets cut off:

Summary: "specifies if the tool version should be excluded from the"

That is what controller-gen applyconfiguration -w shows, so the help text looks truncated.

Could we make the first line a complete sentence and move the extra explanation into the details in both one? For example:

For CRD

// OmitToolVersion omits the controller-gen version annotation from the generated CRD. // // When set, the controller-gen.kubebuilder.io/version annotation is not written // to the CRD's metadata. This only affects that annotation; the generated schema // is unchanged. Left unspecified, the default is false.

And For Here:

// OmitToolVersion omits the tool version from the "Code generated by" file header. // // When set, the generator name in the header is normalized to "controller-gen" // regardless of the binary name, instead of any version-bearing name. This only // affects the header comment; no annotations are involved. Left unspecified, the // default is false.

Also, it makes clear what it does.

Good catch — restructured the godoc so the first line is a complete sentence in both generators. The generated help summaries now read cleanly.

camilamacedo86 · 2026-06-28T16:56:11Z

+
+		Expect(string(content)).To(HavePrefix("// Code generated by controller-gen. DO NOT EDIT."))
+	})
+})


I think this test should also cover the default case.

Right now it only checks that the generated header is:

// Code generated by controller-gen. DO NOT EDIT.

That passes because the marker changes the generator name to controller-gen. But the test does not prove that the marker caused the change.

Could we add a second case that runs without skipToolVersion=true and checks that the header is not controller-gen?

It("should leave the generator name unchanged when SkipToolVersion is unset", func() { // run without skipToolVersion=true Expect(string(content)).NotTo(HavePrefix( "// Code generated by controller-gen. DO NOT EDIT.", )) })

Then the existing test can keep checking the marker case:

It("should normalize the generator name when SkipToolVersion is true", func() { // run with skipToolVersion=true Expect(string(content)).To(HavePrefix( "// Code generated by controller-gen. DO NOT EDIT.", )) })

Together, these prove that SkipToolVersion is what changes the generated header, instead of the test passing because of the test binary name.

Added a default-case test that verifies the header preserves the original generator name when OmitToolVersion is unset. Also added os.RemoveAll(tmpDir) to AfterEach to clean up the temp directory.

camilamacedo86 · 2026-06-28T17:03:28Z

+	// When SkipToolVersion is true, override os.Args[0] so that gengo's
+	// GoBoilerplate (which reads filepath.Base(os.Args[0])) emits a
+	// version-free "Code generated by controller-gen" header.
+	if d.SkipToolVersion != nil && *d.SkipToolVersion {


WDYT about OmitToolVersion?
Omit seems to be a bette verb, wdyt?

Agreed — renamed to OmitToolVersion everywhere. Much clearer.

camilamacedo86

/ok-to-test

camilamacedo86 · 2026-08-03T08:21:36Z

+
+		By("searching for version annotation")
+		Expect(out.buf.String()).NotTo(ContainSubstring("controller-gen.kubebuilder.io/version"))
+	})


Could we have the other way around here?
Should add the version annotation by default when omittoolversion is not informed at all.

camilamacedo86 · 2026-08-03T08:38:57Z

Hi @pedjak,

./hack/verify-boilerplate.sh
Boilerplate header is wrong for: /home/prow/go/src/sigs.k8s.io/controller-tools/pkg/applyconfiguration/applyconfiguration_integration_test.go

The current error message is not clear. The actual fix is to remove the existing year from the header of applyconfiguration_integration_test.go.

This failure is caused by the new Python check introduced by @sbueringer and @alvaroaleman here:
#1451

@sbueringer @alvaroaleman, honestly, the Python implementation seems more complex than necessary for this requirement, and it does not appear to correctly ignore files that existed before the check was introduced.

The most straightforward fix would be to remove the year from all existing license headers. Otherwise, we will continue to see inconsistent failures in files that were not changed.

The check should also clearly explain that the year must be removed. The current error message does not identify the actual problem.

sbueringer · 2026-08-03T10:37:35Z

The most straightforward fix would be to remove the year from all existing license headers. Otherwise, we will continue to see inconsistent failures in files that were not changed.

No, we should not modify existing copyright headers to remove the year, see:

Their guidance is not to modify existing copyright lines in existing files, but to start using the new line for all new file contributions.
This is because attribution notices shouldn't be removed or replaced, rather just added to, without a very specific and legal reviewed reason.
kubernetes/steering#299

The issue here is not that the boilerplate verification somehow didn't check this file before. It always verifies all files.

The reason why this check fails now is because we intentionally have different rules for generated and not generated files:

For generated files the year should be not there
For not generated files we tolerate the year until 2026, afterwards the year should not be there

The problem here in this PR is that we are introducing the "DO NOT EDIT" string into this file. Because of that the file is now detected as a generated file and accordingly we are now getting a hint that we should remove the year.

I see two options on how to resolve this:

avoid using "DO NOT EDIT" in the unit test

add the test file to this list in boilerplate.py (requires a rebase onto main first)

# list all the files contain 'DO NOT EDIT', but are not generated
skipped_ungenerated_files = ['hack/boilerplate/boilerplate.py']

Add per-generator options to control whether controller-gen version information is included in generated files: - crd:omitToolVersion — omits the controller-gen.kubebuilder.io/version annotation from CRD manifests - applyconfiguration:omitToolVersion — omits the tool version from the "Code generated by" comment header Both default to false, preserving current behavior.

pedjak · 2026-08-06T10:41:50Z

@camilamacedo86 @sbueringer — rebased onto main and went with option 2.

k8s-ci-robot added the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Jun 17, 2026

k8s-ci-robot requested review from JoelSpeed and joelanford June 17, 2026 16:10

k8s-ci-robot added needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Jun 17, 2026

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Jun 17, 2026

pedjak force-pushed the feat/optional-tool-version branch from 0350788 to 20bbcde Compare June 17, 2026 16:14

k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Jun 17, 2026

k8s-ci-robot assigned alvaroaleman, camilamacedo86 and sbueringer Jun 17, 2026

k8s-ci-robot unassigned sbueringer, alvaroaleman and camilamacedo86 Jun 17, 2026

k8s-ci-robot requested review from alvaroaleman, camilamacedo86 and sbueringer June 17, 2026 16:16

camilamacedo86 reviewed Jun 17, 2026

View reviewed changes

pedjak changed the title ~~✨ Add options to suppress controller-gen version in generated output~~ ✨ Add options to skip controller-gen version in generated output Jun 26, 2026

pedjak force-pushed the feat/optional-tool-version branch from 20bbcde to f79d4d5 Compare June 26, 2026 15:37

camilamacedo86 reviewed Jun 28, 2026

View reviewed changes

pedjak force-pushed the feat/optional-tool-version branch from f79d4d5 to 1a7e9ad Compare June 29, 2026 14:19

pedjak changed the title ~~✨ Add options to skip controller-gen version in generated output~~ ✨ Add option to omit controller-gen version in generated output Jun 29, 2026

camilamacedo86 reviewed Aug 3, 2026

View reviewed changes

kubernetes-prow Bot 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 Aug 3, 2026

camilamacedo86 reviewed Aug 3, 2026

View reviewed changes

pedjak force-pushed the feat/optional-tool-version branch from 1a7e9ad to 90a5751 Compare August 6, 2026 10:41

Uh oh!

Conversation

pedjak commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this do, and why do we need it?

Uh oh!

k8s-ci-robot commented Jun 17, 2026

Uh oh!

k8s-ci-robot commented Jun 17, 2026

Uh oh!

pedjak commented Jun 17, 2026

Uh oh!

pedjak commented Jun 17, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kubernetes-prow Bot commented Jun 26, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 Jun 28, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camilamacedo86 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pedjak Aug 6, 2026 • 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!

camilamacedo86 commented Aug 3, 2026

Uh oh!

sbueringer commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pedjak commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

pedjak commented Jun 17, 2026 •

edited

Loading

camilamacedo86 Jun 28, 2026 •

edited

Loading

pedjak Aug 6, 2026 •

edited

Loading

sbueringer commented Aug 3, 2026 •

edited

Loading

pedjak commented Aug 6, 2026 •

edited

Loading