✨ crd/marker: add AtMostOneOf and ExactlyOneOf constraints (#1212)

* crd/marker: add AtMostOneOf and ExactlyOneOf constraints

Adds the following validation markers to enforce oneof fields
on Types:

- AtMostOneOf: allows at most one of the specified fields,
  thereby allowing exactly 1 or no fields to be set.
  The marker may be repeated to allow mutually exclusive oneof
  constraints.

- ExactlyOneOf: allows exactly one of the specified fields,
  thereby requiring exactly 1 field to be set.
  The marker may be repeated to allow mutually exclusive oneof
  constraints.

Examples:
```
allow at most oneof foo,bar on a Type to be set
+kubebuilder:validation:AtMostOneOf=foo;bar

allow at most oneof foo,bar and oneof baz,qux to be set
+kubebuilder:validation:AtMostOneOf=foo;ba
+kubebuilder:validation:AtMostOneOf=baz;qux

allow exactly oneof foo,bar on a Type to be set
+kubebuilder:validation:ExactlyOneOf=foo;bar

allow exactly oneof foo,bar and oneof baz,qux to be set
+kubebuilder:validation:ExactlyOneOf=foo;ba
+kubebuilder:validation:ExactlyOneOf=baz;qux
```

* switch to cel

Author: shashankram

.gitignore

@@ -16,6 +16,7 @@
 *.swp
 *.swo
 *~
+.vscode/
 
 # Tools binaries.
 out

go.mod

@@ -16,21 +16,34 @@ require (
 	k8s.io/api v0.33.1
 	k8s.io/apiextensions-apiserver v0.33.1
 	k8s.io/apimachinery v0.33.1
+	k8s.io/apiserver v0.33.1
 	k8s.io/code-generator v0.33.1
 	k8s.io/gengo/v2 v2.0.0-20250207200755-1244d31929d7
 	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738
 	sigs.k8s.io/yaml v1.4.0
 )
 
 require (
+	cel.dev/expr v0.19.1 // indirect
+	github.com/antlr4-go/antlr/v4 v4.13.0 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/blang/semver/v4 v4.0.0 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fsnotify/fsnotify v1.7.0 // indirect
 	github.com/fxamacker/cbor/v2 v2.7.0 // indirect
 	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/go-openapi/jsonpointer v0.21.0 // indirect
 	github.com/go-openapi/jsonreference v0.20.2 // indirect
 	github.com/go-openapi/swag v0.23.0 // indirect
 	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/google/cel-go v0.23.2 // indirect
 	github.com/google/gnostic-models v0.6.9 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.24.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
@@ -39,18 +52,43 @@ require (
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
 	github.com/nxadm/tail v1.4.8 // indirect
+	github.com/prometheus/client_golang v1.22.0 // indirect
+	github.com/prometheus/client_model v0.6.1 // indirect
+	github.com/prometheus/common v0.62.0 // indirect
+	github.com/prometheus/procfs v0.15.1 // indirect
+	github.com/stoewer/go-strcase v1.3.0 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
+	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.58.0 // indirect
+	go.opentelemetry.io/otel v1.33.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.33.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.33.0 // indirect
+	go.opentelemetry.io/otel/metric v1.33.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.33.0 // indirect
+	go.opentelemetry.io/otel/trace v1.33.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.4.0 // indirect
+	golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 // indirect
 	golang.org/x/mod v0.25.0 // indirect
 	golang.org/x/net v0.41.0 // indirect
+	golang.org/x/oauth2 v0.27.0 // indirect
 	golang.org/x/sync v0.15.0 // indirect
 	golang.org/x/sys v0.33.0 // indirect
+	golang.org/x/term v0.32.0 // indirect
 	golang.org/x/text v0.26.0 // indirect
+	golang.org/x/time v0.9.0 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20241209162323-e6fa225c2576 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20241209162323-e6fa225c2576 // indirect
+	google.golang.org/grpc v1.68.1 // indirect
 	google.golang.org/protobuf v1.36.5 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 // indirect
+	k8s.io/client-go v0.33.1 // indirect
+	k8s.io/component-base v0.33.1 // indirect
 	k8s.io/klog/v2 v2.130.1 // indirect
 	k8s.io/kube-openapi v0.0.0-20250318190949-c8a335a9a2ff // indirect
+	sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.31.2 // indirect
 	sigs.k8s.io/json v0.0.0-20241010143419-9aa6b5e7a4b3 // indirect
 	sigs.k8s.io/randfill v1.0.0 // indirect
 	sigs.k8s.io/structured-merge-diff/v4 v4.6.0 // indirect

go.sum

@@ -31,6 +31,9 @@ const (
 
 	SchemalessName        = "kubebuilder:validation:Schemaless"
 	ValidationItemsPrefix = validationPrefix + "items:"
+
+	ValidationExactlyOneOfPrefix = validationPrefix + "ExactlyOneOf"
+	ValidationAtMostOneOfPrefix  = validationPrefix + "AtMostOneOf"
 )
 
 // ValidationMarkers lists all available markers that affect CRD schema generation,
@@ -75,6 +78,14 @@ var ValidationMarkers = mustMakeAllWithPrefix(validationPrefix, markers.Describe
 	XValidation{},
 )
 
+// TypeOnlyMarkers list type-specific validation markers (i.e. those markers that don't make sense on a field, and thus aren't in ValidationMarkers or FieldOnlyMarkers).
+var TypeOnlyMarkers = []*definitionWithHelp{
+	must(markers.MakeDefinition(ValidationAtMostOneOfPrefix, markers.DescribesType, AtMostOneOf(nil))).
+		WithHelp(markers.SimpleHelp("CRD validation", "specifies a list of field names that must conform to the AtMostOneOf constraint.")),
+	must(markers.MakeDefinition(ValidationExactlyOneOfPrefix, markers.DescribesType, ExactlyOneOf(nil))).
+		WithHelp(markers.SimpleHelp("CRD validation", "specifies a list of field names that must conform to the ExactlyOneOf constraint.")),
+}
+
 // FieldOnlyMarkers list field-specific validation markers (i.e. those markers that don't make
 // sense on a type, and thus aren't in ValidationMarkers).
 var FieldOnlyMarkers = []*definitionWithHelp{
@@ -141,6 +152,7 @@ func init() {
 	}
 
 	AllDefinitions = append(AllDefinitions, FieldOnlyMarkers...)
+	AllDefinitions = append(AllDefinitions, TypeOnlyMarkers...)
 	AllDefinitions = append(AllDefinitions, ValidationIshMarkers...)
 }
 
@@ -352,6 +364,18 @@ type XValidation struct {
 	OptionalOldSelf   *bool  `marker:"optionalOldSelf,optional"`
 }
 
+// +controllertools:marker:generateHelp:category="CRD validation"
+// AtMostOneOf adds a validation constraint that allows at most one of the specified fields.
+//
+// This marker may be repeated to specify multiple AtMostOneOf constraints that are mutually exclusive.
+type AtMostOneOf []string
+
+// +controllertools:marker:generateHelp:category="CRD validation"
+// ExactlyOneOf adds a validation constraint that allows at exactly one of the specified fields.
+//
+// This marker may be repeated to specify multiple ExactlyOneOf constraints that are mutually exclusive.
+type ExactlyOneOf []string
+
 func (m Maximum) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
 	if !hasNumericType(schema) {
 		return fmt.Errorf("must apply maximum to a numeric value, found %s", schema.Type)
@@ -635,3 +659,44 @@ func (m XValidation) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
 	})
 	return nil
 }
+
+func (fields AtMostOneOf) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
+	if len(fields) == 0 {
+		return nil
+	}
+	rule := fieldsToOneOfCelRuleStr(fields)
+	xvalidation := XValidation{
+		Rule:    fmt.Sprintf("%s <= 1", rule),
+		Message: fmt.Sprintf("at most one of the fields in %v may be set", fields),
+	}
+	return xvalidation.ApplyToSchema(schema)
+}
+
+func (fields ExactlyOneOf) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
+	if len(fields) == 0 {
+		return nil
+	}
+	rule := fieldsToOneOfCelRuleStr(fields)
+	xvalidation := XValidation{
+		Rule:    fmt.Sprintf("%s == 1", rule),
+		Message: fmt.Sprintf("exactly one of the fields in %v must be set", fields),
+	}
+	return xvalidation.ApplyToSchema(schema)
+}
+
+// fieldsToOneOfCelRuleStr converts a slice of field names to a string representation
+// [has(self.field1),has(self.field1),...].filter(x, x == true).size()
+func fieldsToOneOfCelRuleStr(fields []string) string {
+	var list strings.Builder
+	list.WriteString("[")
+	for i, f := range fields {
+		if i > 0 {
+			list.WriteString(",")
+		}
+		list.WriteString("has(self.")
+		list.WriteString(f)
+		list.WriteString(")")
+	}
+	list.WriteString("].filter(x,x==true).size()")
+	return list.String()
+}

pkg/crd/markers/validation.go

@@ -52,7 +52,6 @@ func packageErrors(pkg *loader.Package, filterKinds ...packages.ErrorKind) error
 
 var _ = Describe("CRD Generation From Parsing to CustomResourceDefinition", func() {
 	Context("should properly generate and flatten the rewritten schemas", func() {
-
 		var (
 			prevCwd   string
 			pkgPaths  []string
@@ -177,6 +176,31 @@ var _ = Describe("CRD Generation From Parsing to CustomResourceDefinition", func
 			})
 		})
 
+		Context("OneOf API", func() {
+			BeforeEach(func() {
+				pkgPaths = []string{"./oneof/..."}
+				expPkgLen = 1
+			})
+			It("should successfully generate the CRD with OneOf validation constraints", func() {
+				assertCRD(pkgs[0], "Oneof", "testdata.kubebuilder.io_oneofs.yaml")
+			})
+		})
+
+		Context("OneOf API with invalid marker", func() {
+			BeforeEach(func() {
+				pkgPaths = []string{"./oneof_error/..."}
+				expPkgLen = 1
+			})
+			It("should generate an error with nested field in marker", func() {
+				kind := "Oneof"
+				groupKind := schema.GroupKind{Kind: kind, Group: "testdata.kubebuilder.io"}
+				parser.NeedCRDFor(groupKind, nil)
+
+				expectedErr := "kubebuilder:validation:AtMostOneOf: cannot reference nested fields: field.foo,field.bar"
+				Expect(packageErrors(pkgs[0])).To(MatchError(ContainSubstring(expectedErr)))
+			})
+		})
+
 		Context("CronJob API with Wrong Annotation Format", func() {
 			BeforeEach(func() {
 				pkgPaths = []string{"./wrong_annotation_format"}
@@ -338,5 +362,4 @@ var _ = Describe("CRD Generation From Parsing to CustomResourceDefinition", func
 		By("comparing the two")
 		Expect(parser.CustomResourceDefinitions[groupKind]).To(Equal(crd), "type not as expected, check pkg/crd/testdata/README.md for more details.\n\nDiff:\n\n%s", cmp.Diff(parser.CustomResourceDefinitions[groupKind], crd))
 	})
-
 })

pkg/crd/markers/zz_generated.markerhelp.go

@@ -26,6 +26,7 @@ import (
 	"strings"
 
 	apiext "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
+	"k8s.io/apimachinery/pkg/util/sets"
 	crdmarkers "sigs.k8s.io/controller-tools/pkg/crd/markers"
 	"sigs.k8s.io/controller-tools/pkg/loader"
 	"sigs.k8s.io/controller-tools/pkg/markers"
@@ -397,6 +398,8 @@ func mapToSchema(ctx *schemaContext, mapType *ast.MapType) *apiext.JSONSchemaPro
 
 // structToSchema creates a schema for the given struct.  Embedded fields are placed in AllOf,
 // and can be flattened later with a Flattener.
+//
+//nolint:gocyclo
 func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSONSchemaProps {
 	props := &apiext.JSONSchemaProps{
 		Type:       "object",
@@ -408,6 +411,17 @@ func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSON
 		return props
 	}
 
+	exactlyOneOf, err := oneOfValuesToSet(ctx.info.Markers[crdmarkers.ValidationExactlyOneOfPrefix])
+	if err != nil {
+		ctx.pkg.AddError(loader.ErrFromNode(err, structType))
+		return props
+	}
+	atMostOneOf, err := oneOfValuesToSet(ctx.info.Markers[crdmarkers.ValidationAtMostOneOfPrefix])
+	if err != nil {
+		ctx.pkg.AddError(loader.ErrFromNode(err, structType))
+		return props
+	}
+
 	for _, field := range ctx.info.Fields {
 		// Skip if the field is not an inline field, ignoreUnexportedFields is true, and the field is not exported
 		if field.Name != "" && ctx.ignoreUnexportedFields && !ast.IsExported(field.Name) {
@@ -449,18 +463,30 @@ func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSON
 		case field.Markers.Get("kubebuilder:validation:Optional") != nil:
 			// explicitly optional - kubebuilder
 		case field.Markers.Get("kubebuilder:validation:Required") != nil:
+			if exactlyOneOf.Has(fieldName) || atMostOneOf.Has(fieldName) {
+				ctx.pkg.AddError(loader.ErrFromNode(fmt.Errorf("field %s is part of OneOf constraint and cannot be marked as required", fieldName), structType))
+				return props
+			}
 			// explicitly required - kubebuilder
 			props.Required = append(props.Required, fieldName)
 		case field.Markers.Get("optional") != nil:
 			// explicitly optional - kubernetes
 		case field.Markers.Get("required") != nil:
+			if exactlyOneOf.Has(fieldName) || atMostOneOf.Has(fieldName) {
+				ctx.pkg.AddError(loader.ErrFromNode(fmt.Errorf("field %s is part of OneOf constraint and cannot be marked as required", fieldName), structType))
+				return props
+			}
 			// explicitly required - kubernetes
 			props.Required = append(props.Required, fieldName)
 
 		// if this package isn't set to optional default...
 		case defaultMode == "required":
 			// ...everything that's not inline / omitempty is required
 			if !inline && !omitEmpty {
+				if exactlyOneOf.Has(fieldName) || atMostOneOf.Has(fieldName) {
+					ctx.pkg.AddError(loader.ErrFromNode(fmt.Errorf("field %s is part of OneOf constraint and must have omitempty tag", fieldName), structType))
+					return props
+				}
 				props.Required = append(props.Required, fieldName)
 			}
 
@@ -490,6 +516,41 @@ func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSON
 	return props
 }
 
+func oneOfValuesToSet(oneOfGroups []any) (sets.Set[string], error) {
+	set := sets.New[string]()
+	for _, oneOf := range oneOfGroups {
+		switch vals := oneOf.(type) {
+		case crdmarkers.ExactlyOneOf:
+			if err := validateOneOfValues(vals...); err != nil {
+				return nil, fmt.Errorf("%s: %w", crdmarkers.ValidationExactlyOneOfPrefix, err)
+			}
+			set.Insert(vals...)
+		case crdmarkers.AtMostOneOf:
+			if err := validateOneOfValues(vals...); err != nil {
+				return nil, fmt.Errorf("%s: %w", crdmarkers.ValidationAtMostOneOfPrefix, err)
+			}
+			set.Insert(vals...)
+		default:
+			return nil, fmt.Errorf("expected ExactlyOneOf or AtMostOneOf, got %T", oneOf)
+		}
+	}
+	return set, nil
+}
+
+func validateOneOfValues(fields ...string) error {
+	var invalid []string
+	for _, field := range fields {
+		if strings.Contains(field, ".") {
+			// nested fields are not allowed in OneOf validation markers
+			invalid = append(invalid, field)
+		}
+	}
+	if len(invalid) > 0 {
+		return fmt.Errorf("cannot reference nested fields: %s", strings.Join(invalid, ","))
+	}
+	return nil
+}
+
 // builtinToType converts builtin basic types to their equivalent JSON schema form.
 // It *only* handles types allowed by the kubernetes API standards. Floats are not
 // allowed unless allowDangerousTypes is true