:seedling: Deprecate the scheme builder by alvaroaleman · Pull Request #3461 · kubernetes-sigs/controller-runtime

alvaroaleman · 2026-02-25T12:55:00Z

Controller-Runtime should never be imported into api packages and the scheme builder is only useful in those, so deprecate it.

alvaroaleman · 2026-02-25T12:55:43Z

 // SchemeBuilder builds a new Scheme for mapping go types to Kubernetes GroupVersionKinds.
-type SchemeBuilder = scheme.Builder
+//
+// Deprecated: Controller-Runtime should not be imported in api packages and this


We could also word this stronger and mention that api packages should not import anything other than other api packages and apimachinery

Fine for me. Or we phrase it more generically and write that folks should be extremely careful with any dependency they add to their API (packages).

E.g. having dependencies on corev1.ObjectReference is an extremely bad idea. Similarly embeddeding any external API types into an API needs careful consideration as it couples APIs (somewhat fine with k/k v1 APIs, but even then there are non-trivial trade-offs in my opinion like inheriting all changes that are made to these APIs elsewhere)

@JoelSpeed Do you have some input for how we should phrase this?
I think this is deprecation warning is a good place to share some guidance. I wouldn't go into too much detail but some high-level points could be good here

Or we phrase it more generically and write that folks should be extremely careful with any dependency they add to their API (packages).

This sounds like a good way to frame it

I would target this message to APIs should import minimal dependencies. Maybe something along the lines of:

// API Packages should import minimal dependencies, typically including only k8s.io/apimachinery sub-packages and standard library packages. // Importing additional packages affects consumers of your API and adds complexity to their dependency management.

I've reworded it mostly based on Joels suggestion with the addition that importing other API packages is also fine, let me know what you think

The way you phrased it sounds good to me.

I had my share of problems with importing API packages in API packages so now I'm extremely careful with those.

Problems there can be:

Importing types that don't actually fit the use case, example metav1.ObjectReference (that one even has a godoc comment that it should not be used)

Inheriting changes of the imported types including schema changes

Making it necessary to cut a new apiVersion because the referenced apiVersion was bumped to avoid breaking changes (e.g. if a v1beta1 type is embedded into another API and then that type is bumped to v1beta2)

So at that point I only consider it safe to embed external API types if:

the lifecycles align (e.g. some k/k v1 type or something that is bumped in lock step with the API the type is embedded in)

the use case perfectly fits (that means the fields, godoc and schema validation perfectly fits any one of those might diverge already or might diverge over time)

All that being said, I'm fine with the current wording. We don't have to be too detailed here :) (just sharing some context)

I think that comment really just tries to explain what is okay to have as a dependency. If it actually makes sense to depend on other apis is yet another question that IMHO we shouldn't try to answer here.

From an API review perspective, we only generally allow importing other API packages if you are "passing through" the data. E.g. you have a type with an embedded pod spec and you then just copy that directly onto another type

Stefan's write up is detailed enough that I don't need to add anymore, but I am fine with the current wording

troy0820 · 2026-02-25T16:37:11Z

/lgtm

I know this isn't the removal yet, but we may want to allow @camilamacedo86 to be aware of the changes if they wish to get in front of this with kubebuilder.

/hold

k8s-ci-robot · 2026-02-25T16:37:20Z

LGTM label has been added.

Details

Git tree hash: e675826794effe86010581339f6382e8bcf9a074

sbueringer · 2026-02-28T07:39:37Z

 // SchemeBuilder builds a new Scheme for mapping go types to Kubernetes GroupVersionKinds.
-type SchemeBuilder = scheme.Builder
+//
+// Deprecated: Controller-Runtime should not be imported in api packages and this


Fine for me. Or we phrase it more generically and write that folks should be extremely careful with any dependency they add to their API (packages).

E.g. having dependencies on corev1.ObjectReference is an extremely bad idea. Similarly embeddeding any external API types into an API needs careful consideration as it couples APIs (somewhat fine with k/k v1 APIs, but even then there are non-trivial trade-offs in my opinion like inheriting all changes that are made to these APIs elsewhere)

@JoelSpeed Do you have some input for how we should phrase this?
I think this is deprecation warning is a good place to share some guidance. I wouldn't go into too much detail but some high-level points could be good here

sbueringer

Last nit

Controller-Runtime should never be imported into api packages and the scheme builder is only useful in those, so deprecate it.

k8s-ci-robot · 2026-03-05T19:21:42Z

@alvaroaleman: The following test failed, say /retest to rerun all failed tests or /retest-required to rerun all mandatory failed tests:

Test name	Commit	Details	Required	Rerun command
pull-controller-runtime-apidiff	`5257194`	link	false	`/test pull-controller-runtime-apidiff`

Full PR test history. Your PR dashboard. Please help us cut down on flakes by linking to an open issue when you hit one in your PR.

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. I understand the commands that are listed here.

sbueringer · 2026-03-05T19:57:47Z

Thx!

/lgtm
/approve

Keeping the hold so @JoelSpeed can take another look

k8s-ci-robot · 2026-03-05T19:57:56Z

LGTM label has been added.

Details

Git tree hash: 3ebffa234fe07f7a11cfd93cdabcff21067c5ee7

k8s-ci-robot · 2026-03-05T19:57:56Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: alvaroaleman, sbueringer

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [alvaroaleman,sbueringer]

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

sbueringer · 2026-03-11T12:46:16Z

I think we're fine, let's move on

/hold cancel

Bump k8s.io/* to v0.36.0. That version preserves API compatibility, which keeps the migration small (kubernetes/kubernetes#137298). controller-runtime v0.24.0 deprecated its SchemeBuilder in favor of the apimachinery one (kubernetes-sigs/controller-runtime#3461), so api/v1 is migrated accordingly. The Go directive moves to 1.26.0 because controller-runtime v0.24.0 requires it. The k8s.io/streaming migration is test-only. The regenerated Pooler CRD picks up the upstream PodSpec rename workloadRef -> schedulingGroup; both shapes are alpha and have no user-visible impact. Closes #10592 Signed-off-by: Jonathan Gonzalez V. <jonathan.gonzalez@enterprisedb.com>

Bump k8s.io/* to v0.36.0. That version preserves API compatibility, which keeps the migration small (kubernetes/kubernetes#137298). controller-runtime v0.24.0 deprecated its SchemeBuilder in favor of the apimachinery one (kubernetes-sigs/controller-runtime#3461), so api/v1 is migrated accordingly. The Go directive moves to 1.26.0 because controller-runtime v0.24.0 requires it. The k8s.io/streaming migration is test-only. The regenerated Pooler CRD picks up the upstream PodSpec rename workloadRef -> schedulingGroup; both shapes are alpha and have no user-visible impact. Closes #10592 Signed-off-by: Jonathan Gonzalez V. <jonathan.gonzalez@enterprisedb.com> (cherry picked from commit 490938f)

…36.0. That version preserves API compatibility,%0Awhich keeps the migration small%0A(kubernetes/kubernetes#137298 v0.24.0 deprecated its SchemeBuilder in favor of the%0Aapimachinery one%0A(kubernetes-sigs/controller-runtime#3461), so%0Aapi/v1 is migrated accordingly.%0A%0AThe Go directive moves to 1.26.0 because controller-runtime v0.24.0%0Arequires it. The k8s.io/streaming migration is test-only. The%0Aregenerated Pooler CRD picks up the upstream PodSpec rename workloadRef%0A-> schedulingGroup; both shapes are alpha and have no user-visible%0Aimpact.%0A%0ACloses #10592%0A%0ASigned-off-by: Jonathan Gonzalez V. <jonathan.gonzalez@enterprisedb.com> cloudnative-pg/cloudnative-pg@refs/heads/main

…36.0. That version preserves API compatibility,%0Awhich keeps the migration small%0A(kubernetes/kubernetes#137298 v0.24.0 deprecated its SchemeBuilder in favor of the%0Aapimachinery one%0A(kubernetes-sigs/controller-runtime#3461), so%0Aapi/v1 is migrated accordingly.%0A%0AThe Go directive moves to 1.26.0 because controller-runtime v0.24.0%0Arequires it. The k8s.io/streaming migration is test-only. The%0Aregenerated Pooler CRD picks up the upstream PodSpec rename workloadRef%0A-> schedulingGroup; both shapes are alpha and have no user-visible%0Aimpact.%0A%0ACloses #10592%0A%0ASigned-off-by: Jonathan Gonzalez V. <jonathan.gonzalez@enterprisedb.com>%0A(cherry picked from commit 490938f9fd7cf688f643eab1098ea36ea1b6e149) cloudnative-pg/cloudnative-pg@refs/heads/release-1.29

…36.0. That version preserves API compatibility,%0Awhich keeps the migration small%0A(kubernetes/kubernetes#137298 v0.24.0 deprecated its SchemeBuilder in favor of the%0Aapimachinery one%0A(kubernetes-sigs/controller-runtime#3461), so%0Aapi/v1 is migrated accordingly.%0A%0AThe Go directive moves to 1.26.0 because controller-runtime v0.24.0%0Arequires it. The k8s.io/streaming migration is test-only. The%0Aregenerated Pooler CRD picks up the upstream PodSpec rename workloadRef%0A-> schedulingGroup; both shapes are alpha and have no user-visible%0Aimpact.%0A%0ACloses #10592%0A%0ASigned-off-by: Jonathan Gonzalez V. <jonathan.gonzalez@enterprisedb.com>%0A(cherry picked from commit 490938f9fd7cf688f643eab1098ea36ea1b6e149) cloudnative-pg/cloudnative-pg@refs/heads/release-1.28

…36.0. That version preserves API compatibility,%0Awhich keeps the migration small%0A(kubernetes/kubernetes#137298 v0.24.0 deprecated its SchemeBuilder in favor of the%0Aapimachinery one%0A(kubernetes-sigs/controller-runtime#3461), so%0Aapi/v1 is migrated accordingly.%0A%0AThe Go directive moves to 1.26.0 because controller-runtime v0.24.0%0Arequires it. The k8s.io/streaming migration is test-only. The%0Aregenerated Pooler CRD picks up the upstream PodSpec rename workloadRef%0A-> schedulingGroup; both shapes are alpha and have no user-visible%0Aimpact.%0A%0ACloses #10592%0A%0ASigned-off-by: Jonathan Gonzalez V. <jonathan.gonzalez@enterprisedb.com>%0A(cherry picked from commit 490938f9fd7cf688f643eab1098ea36ea1b6e149) cloudnative-pg/cloudnative-pg@refs/heads/release-1.25

Description: - Dependabot PRs are failing because the latest version of `controller-runtime` has deprecated `scheme.Builder` (https://github.com/alphagov/govuk-job-request-operator/actions/runs/26217422184/job/77143291873?pr=6) ``` Error: api/v1/groupversion_info.go:36:19: SA1019: scheme.Builder is deprecated: This helper is only useful in api packages, but api packages should be easy to import and hence have minimal dependencies. Typically, these dependencies include only the standard library, k8s.io/apimachinery and other api packages. (staticcheck) ``` - kubernetes-sigs/controller-runtime#3461 was used to make the changes

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Feb 25, 2026

k8s-ci-robot requested review from troy0820 and vincepri February 25, 2026 12:55

k8s-ci-robot added approved Indicates a PR has been approved by an approver from all required OWNERS files. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Feb 25, 2026

alvaroaleman commented Feb 25, 2026

View reviewed changes

alvaroaleman requested a review from sbueringer February 25, 2026 12:56

alvaroaleman force-pushed the deprecate-scheme branch from d20babd to 98044dc Compare February 25, 2026 13:16

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

k8s-ci-robot assigned troy0820 Feb 25, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 25, 2026

sbueringer reviewed Feb 28, 2026

View reviewed changes

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

alvaroaleman force-pushed the deprecate-scheme branch from 98044dc to 4a10519 Compare March 4, 2026 19:56

k8s-ci-robot removed lgtm "Looks good to me", indicates that a PR is ready to be merged. needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. labels Mar 4, 2026

sbueringer reviewed Mar 5, 2026

View reviewed changes

Comment thread pkg/scheme/scheme.go

🌱 Deprecate the scheme builder

5257194

Controller-Runtime should never be imported into api packages and the scheme builder is only useful in those, so deprecate it.

alvaroaleman force-pushed the deprecate-scheme branch from 4a10519 to 5257194 Compare March 5, 2026 19:16

k8s-ci-robot assigned sbueringer Mar 5, 2026

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 5, 2026

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Mar 11, 2026

k8s-ci-robot merged commit 37c380b into kubernetes-sigs:main Mar 11, 2026
8 of 9 checks passed

sxd mentioned this pull request May 2, 2026

chore: update to Kubernetes 0.36.0 cloudnative-pg/cloudnative-pg#10593

Merged

This was referenced May 3, 2026

fix(deps): update go-dependencies (non-major) - autoclosed grafana/grafana-operator#2660

Closed

chore(deps): move remaining dep updates from 2660 and fix related code grafana/grafana-operator#2673

Merged

diillson mentioned this pull request May 4, 2026

refactor(operator): migrate SchemeBuilder to apimachinery pattern diillson/chatcli#878

Merged

3 tasks

claude Bot mentioned this pull request May 14, 2026

build(deps): Bump the gomod group with 6 updates inference-gateway/operator#54

Merged

nimalank7 mentioned this pull request May 21, 2026

BAU - Deprecate scheme builder alphagov/govuk-job-request-operator#24

Merged

Conversation

alvaroaleman commented Feb 25, 2026

Uh oh!

alvaroaleman Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

sbueringer Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

JoelSpeed Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

alvaroaleman Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

sbueringer Mar 5, 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!

alvaroaleman Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

JoelSpeed Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

troy0820 commented Feb 25, 2026

Uh oh!

k8s-ci-robot commented Feb 25, 2026

Uh oh!

Uh oh!

sbueringer Feb 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sbueringer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

k8s-ci-robot commented Mar 5, 2026

Uh oh!

sbueringer commented Mar 5, 2026

Uh oh!

k8s-ci-robot commented Mar 5, 2026

Uh oh!

k8s-ci-robot commented Mar 5, 2026

Uh oh!

sbueringer commented Mar 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

sbueringer Mar 5, 2026 •

edited

Loading