kubernetes-sigs · alvaroaleman · Feb 25, 2026
diff --git a/alias.go b/alias.go
@@ -49,7 +49,36 @@ type Manager = manager.Manager
 type Options = manager.Options
 
 // SchemeBuilder builds a new Scheme for mapping go types to Kubernetes GroupVersionKinds.
-type SchemeBuilder = scheme.Builder
+//
+// 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.
+//
+// Use the apimachinery builder instead:
+//
+//	import (
+//		metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+//		"k8s.io/apimachinery/pkg/runtime"
+//		"k8s.io/apimachinery/pkg/runtime/schema"
+//	)
+//
+//	const GroupName = ""
+//
+//	var (
+//		SchemeGroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1"}
+//		SchemeBuilder 		 = runtime.NewSchemeBuilder(addKnownTypes)
+//		AddToScheme   		 = SchemeBuilder.AddToScheme
+//	)
+//
+//	func addKnownTypes(scheme *runtime.Scheme) error {
+//		scheme.AddKnownTypes(SchemeGroupVersion,
+//			&Pod{},
+//		)
+//
+//		metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
+//		return nil
+//	}
+type SchemeBuilder = scheme.Builder //nolint:staticcheck // this is the deprecation alias
 
 // GroupVersion contains the "group" and the "version", which uniquely identifies the API.
 type GroupVersion = schema.GroupVersion

diff --git a/examples/crd/pkg/groupversion_info.go b/examples/crd/pkg/groupversion_info.go
@@ -20,17 +20,27 @@ limitations under the License.
 package pkg
 
 import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
 	"k8s.io/apimachinery/pkg/runtime/schema"
-	"sigs.k8s.io/controller-runtime/pkg/scheme"
 )
 
 var (
 	// SchemeGroupVersion is group version used to register these objects
 	SchemeGroupVersion = schema.GroupVersion{Group: "chaosapps.metamagical.io", Version: "v1"}
 
 	// SchemeBuilder is used to add go types to the GroupVersionKind scheme
-	SchemeBuilder = &scheme.Builder{GroupVersion: SchemeGroupVersion}
+	SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes)
 
 	// AddToScheme is required by pkg/client/...
 	AddToScheme = SchemeBuilder.AddToScheme
 )
+
+func addKnownTypes(scheme *runtime.Scheme) error {
+	scheme.AddKnownTypes(SchemeGroupVersion,
+		&ChaosPod{},
+		&ChaosPodList{},
+	)
+	metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
+	return nil
+}
diff --git a/examples/crd/pkg/resource.go b/examples/crd/pkg/resource.go
@@ -55,7 +55,3 @@ type ChaosPodList struct {
 	metav1.ListMeta `json:"metadata,omitempty"`
 	Items           []ChaosPod `json:"items"`
 }
-
-func init() {
-	SchemeBuilder.Register(&ChaosPod{}, &ChaosPodList{})
-}
diff --git a/pkg/builder/controller_test.go b/pkg/builder/controller_test.go
@@ -44,7 +44,6 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/manager"
 	"sigs.k8s.io/controller-runtime/pkg/predicate"
 	"sigs.k8s.io/controller-runtime/pkg/reconcile"
-	"sigs.k8s.io/controller-runtime/pkg/scheme"
 	"sigs.k8s.io/controller-runtime/pkg/source"
 )
 
@@ -377,10 +376,11 @@ var _ = Describe("application", func() {
 			Expect(err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testDefaultValidatorGVK.GroupVersion()}
-			builder.Register(&TestDefaultValidator{}, &TestDefaultValidatorList{})
-			err = builder.AddToScheme(m.GetScheme())
-			Expect(err).NotTo(HaveOccurred())
+			m.GetScheme().AddKnownTypes(testDefaultValidatorGVK.GroupVersion(),
+				&TestDefaultValidator{},
+				&TestDefaultValidatorList{},
+			)
+			metav1.AddToGroupVersion(m.GetScheme(), testDefaultValidatorGVK.GroupVersion())
 
 			By("creating the 1st controller")
 			ctrl1, err := ControllerManagedBy(m).

diff --git a/pkg/builder/webhook_test.go b/pkg/builder/webhook_test.go
@@ -37,7 +37,6 @@ import (
 	logf "sigs.k8s.io/controller-runtime/pkg/log"
 	"sigs.k8s.io/controller-runtime/pkg/log/zap"
 	"sigs.k8s.io/controller-runtime/pkg/manager"
-	"sigs.k8s.io/controller-runtime/pkg/scheme"
 	"sigs.k8s.io/controller-runtime/pkg/webhook/admission"
 )
 
@@ -90,10 +89,7 @@ func runTests(admissionReviewVersion string) {
 			ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testDefaulterGVK.GroupVersion()}
-			builder.Register(&TestDefaulterObject{}, &TestDefaulterList{})
-			err = builder.AddToScheme(m.GetScheme())
-			ExpectWithOffset(1, err).NotTo(HaveOccurred())
+			addToScheme(m.GetScheme())
 
 			webhookBuilder := WebhookManagedBy(m, &TestDefaulterObject{})
 			build(webhookBuilder)
@@ -174,10 +170,7 @@ func runTests(admissionReviewVersion string) {
 			ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testDefaulterGVK.GroupVersion()}
-			builder.Register(&TestDefaulterObject{}, &TestDefaulterList{})
-			err = builder.AddToScheme(m.GetScheme())
-			ExpectWithOffset(1, err).NotTo(HaveOccurred())
+			addToScheme(m.GetScheme())
 
 			customPath := "/custom-defaulting-path"
 			webhookBuilder := WebhookManagedBy(m, &TestDefaulterObject{})
@@ -261,10 +254,7 @@ func runTests(admissionReviewVersion string) {
 			ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testDefaulterGVK.GroupVersion()}
-			builder.Register(&TestDefaulterObject{}, &TestDefaulterList{})
-			err = builder.AddToScheme(m.GetScheme())
-			ExpectWithOffset(1, err).NotTo(HaveOccurred())
+			addToScheme(m.GetScheme())
 
 			webhookBuilder := WebhookManagedBy(m, &TestDefaulterObject{})
 			build(webhookBuilder)
@@ -332,10 +322,7 @@ func runTests(admissionReviewVersion string) {
 			ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testValidatorGVK.GroupVersion()}
-			builder.Register(&TestValidatorObject{}, &TestValidatorList{})
-			err = builder.AddToScheme(m.GetScheme())
-			ExpectWithOffset(1, err).NotTo(HaveOccurred())
+			addToScheme(m.GetScheme())
 
 			webhook := WebhookManagedBy(m, &TestValidatorObject{})
 			build(webhook)
@@ -457,10 +444,7 @@ func runTests(admissionReviewVersion string) {
 			ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testValidatorGVK.GroupVersion()}
-			builder.Register(&TestValidatorObject{}, &TestValidatorList{})
-			err = builder.AddToScheme(m.GetScheme())
-			ExpectWithOffset(1, err).NotTo(HaveOccurred())
+			addToScheme(m.GetScheme())
 
 			customPath := "/custom-validating-path"
 			webhookBuilder := WebhookManagedBy(m, &TestValidatorObject{})
@@ -544,10 +528,7 @@ func runTests(admissionReviewVersion string) {
 			ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testValidatorGVK.GroupVersion()}
-			builder.Register(&TestValidatorObject{}, &TestValidatorList{})
-			err = builder.AddToScheme(m.GetScheme())
-			ExpectWithOffset(1, err).NotTo(HaveOccurred())
+			addToScheme(m.GetScheme())
 
 			webhookBuilder := WebhookManagedBy(m, &TestValidatorObject{})
 			build(webhookBuilder)
@@ -617,10 +598,7 @@ func runTests(admissionReviewVersion string) {
 			ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testValidatorGVK.GroupVersion()}
-			builder.Register(&TestValidatorObject{}, &TestValidatorList{})
-			err = builder.AddToScheme(m.GetScheme())
-			ExpectWithOffset(1, err).NotTo(HaveOccurred())
+			addToScheme(m.GetScheme())
 
 			webhookBuilder := WebhookManagedBy(m, &TestValidatorObject{})
 			build(webhookBuilder)
@@ -715,10 +693,7 @@ func runTests(admissionReviewVersion string) {
 			ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testValidatorGVK.GroupVersion()}
-			builder.Register(&TestDefaultValidator{}, &TestDefaultValidatorList{})
-			err = builder.AddToScheme(m.GetScheme())
-			ExpectWithOffset(1, err).NotTo(HaveOccurred())
+			addToScheme(m.GetScheme())
 
 			webhookBuilder := WebhookManagedBy(m, &TestDefaultValidator{})
 			build(webhookBuilder)
@@ -815,10 +790,7 @@ func runTests(admissionReviewVersion string) {
 			ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
 			By("registering the type in the Scheme")
-			builder := scheme.Builder{GroupVersion: testValidatorGVK.GroupVersion()}
-			builder.Register(&TestDefaultValidator{}, &TestDefaultValidatorList{})
-			err = builder.AddToScheme(m.GetScheme())
-			ExpectWithOffset(1, err).NotTo(HaveOccurred())
+			addToScheme(m.GetScheme())
 
 			validatingCustomPath := "/custom-validating-path"
 			defaultingCustomPath := "/custom-defaulting-path"
@@ -936,10 +908,7 @@ func runTests(admissionReviewVersion string) {
 		m, err := manager.New(cfg, manager.Options{})
 		ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
-		builder := scheme.Builder{GroupVersion: testDefaulterGVK.GroupVersion()}
-		builder.Register(&TestDefaulterObject{}, &TestDefaulterList{})
-		err = builder.AddToScheme(m.GetScheme())
-		ExpectWithOffset(1, err).NotTo(HaveOccurred())
+		addToScheme(m.GetScheme())
 
 		err = WebhookManagedBy(m, &TestDefaulterObject{}).
 			WithDefaulter(&testDefaulter{}).
@@ -952,10 +921,7 @@ func runTests(admissionReviewVersion string) {
 		m, err := manager.New(cfg, manager.Options{})
 		ExpectWithOffset(1, err).NotTo(HaveOccurred())
 
-		builder := scheme.Builder{GroupVersion: testValidatorGVK.GroupVersion()}
-		builder.Register(&TestValidatorObject{}, &TestValidatorList{})
-		err = builder.AddToScheme(m.GetScheme())
-		ExpectWithOffset(1, err).NotTo(HaveOccurred())
+		addToScheme(m.GetScheme())
 
 		err = WebhookManagedBy(m, &TestValidatorObject{}).
 			WithValidator(&testValidator{}).
@@ -978,6 +944,18 @@ type TestDefaulterObject struct {
 
 var testDefaulterGVK = schema.GroupVersionKind{Group: "foo.test.org", Version: "v1", Kind: testDefaulterKind}
 
+func addToScheme(scheme *runtime.Scheme) {
+	scheme.AddKnownTypes(testDefaulterGVK.GroupVersion(),
+		&TestDefaulterObject{},
+		&TestDefaulterList{},
+		&TestValidatorObject{},
+		&TestValidatorList{},
+		&TestDefaultValidator{},
+		&TestDefaultValidatorList{},
+	)
+	metav1.AddToGroupVersion(scheme, testDefaulterGVK.GroupVersion())
+}
+
 func (d *TestDefaulterObject) GetObjectKind() schema.ObjectKind { return d }
 func (d *TestDefaulterObject) DeepCopyObject() runtime.Object {
 	return &TestDefaulterObject{

diff --git a/pkg/cache/informer_cache_unit_test.go b/pkg/cache/informer_cache_unit_test.go
@@ -29,7 +29,6 @@ import (
 
 	"sigs.k8s.io/controller-runtime/pkg/cache/internal"
 	"sigs.k8s.io/controller-runtime/pkg/controller/controllertest"
-	crscheme "sigs.k8s.io/controller-runtime/pkg/scheme"
 )
 
 const (
@@ -86,14 +85,9 @@ var _ = Describe("ip.objectTypeForListObject", func() {
 	It("should find the object type of a list with a slice of pointers items field", func() {
 		By("registering the type", func() {
 			ip.scheme = runtime.NewScheme()
-			err := (&crscheme.Builder{
-				GroupVersion: schema.GroupVersion{Group: itemPointerSliceTypeGroupName, Version: itemPointerSliceTypeVersion},
-			}).
-				Register(
-					&controllertest.UnconventionalListType{},
-					&controllertest.UnconventionalListTypeList{},
-				).AddToScheme(ip.scheme)
-			Expect(err).ToNot(HaveOccurred())
+			gv := schema.GroupVersion{Group: itemPointerSliceTypeGroupName, Version: itemPointerSliceTypeVersion}
+			ip.scheme.AddKnownTypes(gv, &controllertest.UnconventionalListType{}, &controllertest.UnconventionalListTypeList{})
+			metav1.AddToGroupVersion(ip.scheme, gv)
 		})
 
 		By("calling objectTypeForListObject", func() {

diff --git a/pkg/client/fake/client_test.go b/pkg/client/fake/client_test.go
@@ -54,7 +54,6 @@ import (
 
 	"sigs.k8s.io/controller-runtime/pkg/client"
 	"sigs.k8s.io/controller-runtime/pkg/client/interceptor"
-	"sigs.k8s.io/controller-runtime/pkg/scheme"
 )
 
 const (
@@ -1848,10 +1847,8 @@ var _ = Describe("Fake client", func() {
 	})
 
 	It("should allow SSA apply on status without object has changed issues", func(ctx SpecContext) {
-		schemeBuilder := &scheme.Builder{GroupVersion: schema.GroupVersion{Group: "chaosapps.metamagical.io", Version: "v1"}}
-		schemeBuilder.Register(&ChaosPod{})
 		testScheme := runtime.NewScheme()
-		Expect(schemeBuilder.AddToScheme(testScheme)).NotTo(HaveOccurred())
+		addChaosPodToScheme(testScheme)
 
 		customResource := &ChaosPod{
 			TypeMeta: metav1.TypeMeta{
@@ -1898,10 +1895,8 @@ var _ = Describe("Fake client", func() {
 	})
 
 	It("should block SSA apply on status when passing the wrong non empty resource version", func(ctx SpecContext) {
-		schemeBuilder := &scheme.Builder{GroupVersion: schema.GroupVersion{Group: "chaosapps.metamagical.io", Version: "v1"}}
-		schemeBuilder.Register(&ChaosPod{})
 		testScheme := runtime.NewScheme()
-		Expect(schemeBuilder.AddToScheme(testScheme)).NotTo(HaveOccurred())
+		addChaosPodToScheme(testScheme)
 
 		customResource := &ChaosPod{
 			TypeMeta: metav1.TypeMeta{
@@ -1958,11 +1953,10 @@ var _ = Describe("Fake client", func() {
 	})
 
 	It("should Unmarshal the schemaless object with int64 to preserve ints", func(ctx SpecContext) {
-		schemeBuilder := &scheme.Builder{GroupVersion: schema.GroupVersion{Group: "test", Version: "v1"}}
-		schemeBuilder.Register(&WithSchemalessSpec{})
-
+		gv := schema.GroupVersion{Group: "test", Version: "v1"}
 		scheme := runtime.NewScheme()
-		Expect(schemeBuilder.AddToScheme(scheme)).NotTo(HaveOccurred())
+		scheme.AddKnownTypes(gv, &WithSchemalessSpec{})
+		metav1.AddToGroupVersion(scheme, gv)
 
 		spec := Schemaless{
 			"key": int64(1),
@@ -1983,11 +1977,10 @@ var _ = Describe("Fake client", func() {
 	})
 
 	It("should Unmarshal the schemaless object with float64 to preserve ints", func(ctx SpecContext) {
-		schemeBuilder := &scheme.Builder{GroupVersion: schema.GroupVersion{Group: "test", Version: "v1"}}
-		schemeBuilder.Register(&WithSchemalessSpec{})
-
+		gv := schema.GroupVersion{Group: "test", Version: "v1"}
 		scheme := runtime.NewScheme()
-		Expect(schemeBuilder.AddToScheme(scheme)).NotTo(HaveOccurred())
+		scheme.AddKnownTypes(gv, &WithSchemalessSpec{})
+		metav1.AddToGroupVersion(scheme, gv)
 
 		spec := Schemaless{
 			"key": 1.1,
@@ -2008,11 +2001,10 @@ var _ = Describe("Fake client", func() {
 	})
 
 	It("works with types that have an embedded struct pointer", func(ctx SpecContext) {
-		schemeBuilder := &scheme.Builder{GroupVersion: schema.GroupVersion{Group: "test", Version: "v1"}}
-		schemeBuilder.Register(&EmbeddedPointerStructCRD{})
-
+		gv := schema.GroupVersion{Group: "test", Version: "v1"}
 		scheme := runtime.NewScheme()
-		Expect(schemeBuilder.AddToScheme(scheme)).NotTo(HaveOccurred())
+		scheme.AddKnownTypes(gv, &EmbeddedPointerStructCRD{})
+		metav1.AddToGroupVersion(scheme, gv)
 
 		c := NewClientBuilder().WithScheme(scheme).Build()
 
@@ -3531,6 +3523,13 @@ func (in *EmbeddedPointerStructCRD) DeepCopyObject() runtime.Object {
 	return &out
 }
 
+var chaosPodGV = schema.GroupVersion{Group: "chaosapps.metamagical.io", Version: "v1"}
+
+func addChaosPodToScheme(scheme *runtime.Scheme) {
+	scheme.AddKnownTypes(chaosPodGV, &ChaosPod{})
+	metav1.AddToGroupVersion(scheme, chaosPodGV)
+}
+
 // ChaosPod is a custom resource type used for testing SSA apply operations
 // on custom resources with status subresources.
 type ChaosPod struct {