Add feature gate marker support for conditional CRD field inclusion

Implements +kubebuilder:feature-gate=<gate-name> marker that allows
fields to be conditionally included in generated CRDs based on
enabled feature gates.

- Add FeatureGate marker type in pkg/crd/markers/featuregate.go
- Register feature gate markers in marker registry
- Add CLI parameter crd:featureGates=gate1=true,gate2=false
- Implement conditional field inclusion in schema generation
- Add feature gate context to Parser struct

Addresses #1238

Author: wazery

pkg/crd/gen.go

@@ -32,6 +32,46 @@ import (
 	"sigs.k8s.io/controller-tools/pkg/version"
 )
 
+// FeatureGateMap represents a map of feature gate names to their enabled status.
+type FeatureGateMap map[string]bool
+
+// parseFeatureGates parses a feature gates string in the format "gate1=true,gate2=false"
+// and returns a FeatureGateMap.
+func parseFeatureGates(featureGatesStr string) (FeatureGateMap, error) {
+	gates := make(FeatureGateMap)
+	if featureGatesStr == "" {
+		return gates, nil
+	}
+
+	pairs := strings.Split(featureGatesStr, ",")
+	for _, pair := range pairs {
+		parts := strings.Split(strings.TrimSpace(pair), "=")
+		if len(parts) != 2 {
+			return nil, fmt.Errorf("invalid feature gate format: %s (expected format: gate1=true,gate2=false)", pair)
+		}
+
+		name := strings.TrimSpace(parts[0])
+		valueStr := strings.TrimSpace(parts[1])
+
+		switch valueStr {
+		case "true":
+			gates[name] = true
+		case "false":
+			gates[name] = false
+		default:
+			return nil, fmt.Errorf("invalid feature gate value for %s: %s (must be 'true' or 'false')", name, valueStr)
+		}
+	}
+
+	return gates, nil
+}
+
+// isFeatureGateEnabled checks if a feature gate is enabled.
+func (fg FeatureGateMap) isEnabled(gateName string) bool {
+	enabled, exists := fg[gateName]
+	return exists && enabled
+}
+
 // The identifier for v1 CustomResourceDefinitions.
 const v1 = "v1"
 
@@ -85,6 +125,11 @@ type Generator struct {
 	// Year specifies the year to substitute for " YEAR" in the header file.
 	Year string `marker:",optional"`
 
+	// FeatureGates specifies which feature gates are enabled for conditional field inclusion.
+	//
+	// Format: "gate1=true,gate2=false"
+	FeatureGates string `marker:",optional"`
+
 	// DeprecatedV1beta1CompatibilityPreserveUnknownFields indicates whether
 	// or not we should turn off field pruning for this resource.
 	//
@@ -124,6 +169,11 @@ func transformPreserveUnknownFields(value bool) func(map[string]interface{}) err
 }
 
 func (g Generator) Generate(ctx *genall.GenerationContext) error {
+	featureGates, err := parseFeatureGates(g.FeatureGates)
+	if err != nil {
+		return fmt.Errorf("invalid feature gates: %w", err)
+	}
+
 	parser := &Parser{
 		Collector: ctx.Collector,
 		Checker:   ctx.Checker,
@@ -132,6 +182,7 @@ func (g Generator) Generate(ctx *genall.GenerationContext) error {
 		AllowDangerousTypes:    g.AllowDangerousTypes != nil && *g.AllowDangerousTypes,
 		// Indicates the parser on whether to register the ObjectMeta type or not
 		GenerateEmbeddedObjectMeta: g.GenerateEmbeddedObjectMeta != nil && *g.GenerateEmbeddedObjectMeta,
+		FeatureGates:               featureGates,
 	}
 
 	AddKnownTypes(parser)

pkg/crd/markers/featuregate.go

@@ -0,0 +1,53 @@
+/*
+Copyright 2025 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package markers
+
+import (
+	apiext "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
+	"sigs.k8s.io/controller-tools/pkg/markers"
+)
+
+// +controllertools:marker:generateHelp:category="CRD feature gates"
+// FeatureGate marks a field or type to be conditionally included based on feature gate enablement.
+// The field will only be included in generated CRDs when the specified feature gate is enabled.
+type FeatureGate string
+
+// ApplyToSchema implements SchemaMarker interface.
+// This marker doesn't directly modify the schema - it's used by the generator
+// to conditionally include/exclude fields during CRD generation.
+func (m FeatureGate) ApplyToSchema(schema *apiext.JSONSchemaProps) error {
+	// Feature gate markers don't modify the schema directly.
+	// They are processed by the generator to conditionally include/exclude fields.
+	return nil
+}
+
+// Help returns the help information for this marker.
+func (FeatureGate) Help() *markers.DefinitionHelp {
+	return &markers.DefinitionHelp{
+		Category: "CRD feature gates",
+		DetailedHelp: markers.DetailedHelp{
+			Summary: "marks a field to be conditionally included based on feature gate enablement",
+			Details: "Fields marked with +kubebuilder:feature-gate will only be included in generated CRDs when the specified feature gate is enabled via --feature-gates flag.",
+		},
+		FieldHelp: map[string]markers.DetailedHelp{
+			"": {
+				Summary: "the name of the feature gate that controls this field",
+				Details: "The feature gate name should match gates passed via --feature-gates=gate1=true,gate2=false",
+			},
+		},
+	}
+}

pkg/crd/markers/validation.go

@@ -132,6 +132,13 @@ var ValidationIshMarkers = []*definitionWithHelp{
 func init() {
 	AllDefinitions = append(AllDefinitions, ValidationMarkers...)
 
+	// Add FeatureGate markers
+	featureGateMarkers := []*definitionWithHelp{
+		must(markers.MakeDefinition("kubebuilder:feature-gate", markers.DescribesField, FeatureGate(""))).WithHelp(FeatureGate("").Help()),
+		must(markers.MakeDefinition("kubebuilder:feature-gate", markers.DescribesType, FeatureGate(""))).WithHelp(FeatureGate("").Help()),
+	}
+	AllDefinitions = append(AllDefinitions, featureGateMarkers...)
+
 	for _, def := range ValidationMarkers {
 		typDef := def.clone()
 		typDef.Target = markers.DescribesType

pkg/crd/parser.go

@@ -92,6 +92,9 @@ type Parser struct {
 
 	// GenerateEmbeddedObjectMeta specifies if any embedded ObjectMeta should be generated
 	GenerateEmbeddedObjectMeta bool
+
+	// FeatureGates specifies which feature gates are enabled for conditional field inclusion
+	FeatureGates FeatureGateMap
 }
 
 func (p *Parser) init() {
@@ -172,7 +175,7 @@ func (p *Parser) NeedSchemaFor(typ TypeIdent) {
 	// avoid tripping recursive schemata, like ManagedFields, by adding an empty WIP schema
 	p.Schemata[typ] = apiext.JSONSchemaProps{}
 
-	schemaCtx := newSchemaContext(typ.Package, p, p.AllowDangerousTypes, p.IgnoreUnexportedFields)
+	schemaCtx := newSchemaContext(typ.Package, p, p.AllowDangerousTypes, p.IgnoreUnexportedFields, p.FeatureGates)
 	ctxForInfo := schemaCtx.ForInfo(info)
 
 	pkgMarkers, err := markers.PackageMarkers(p.Collector, typ.Package)

pkg/crd/schema.go

@@ -72,17 +72,19 @@ type schemaContext struct {
 
 	allowDangerousTypes    bool
 	ignoreUnexportedFields bool
+	featureGates          FeatureGateMap
 }
 
 // newSchemaContext constructs a new schemaContext for the given package and schema requester.
 // It must have type info added before use via ForInfo.
-func newSchemaContext(pkg *loader.Package, req schemaRequester, allowDangerousTypes, ignoreUnexportedFields bool) *schemaContext {
+func newSchemaContext(pkg *loader.Package, req schemaRequester, allowDangerousTypes, ignoreUnexportedFields bool, featureGates FeatureGateMap) *schemaContext {
 	pkg.NeedTypesInfo()
 	return &schemaContext{
 		pkg:                    pkg,
 		schemaRequester:        req,
 		allowDangerousTypes:    allowDangerousTypes,
 		ignoreUnexportedFields: ignoreUnexportedFields,
+		featureGates:          featureGates,
 	}
 }
 
@@ -95,6 +97,7 @@ func (c *schemaContext) ForInfo(info *markers.TypeInfo) *schemaContext {
 		schemaRequester:        c.schemaRequester,
 		allowDangerousTypes:    c.allowDangerousTypes,
 		ignoreUnexportedFields: c.ignoreUnexportedFields,
+		featureGates:          c.featureGates,
 	}
 }
 
@@ -428,6 +431,17 @@ func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSON
 			continue
 		}
 
+		// Check feature gate markers - skip field if feature gate is not enabled
+		if featureGateMarker := field.Markers.Get("kubebuilder:feature-gate"); featureGateMarker != nil {
+			if featureGate, ok := featureGateMarker.(crdmarkers.FeatureGate); ok {
+				gateName := string(featureGate)
+				if !ctx.featureGates.isEnabled(gateName) {
+					// Skip this field as its feature gate is not enabled
+					continue
+				}
+			}
+		}
+
 		jsonTag, hasTag := field.Tag.Lookup("json")
 		if !hasTag {
 			// if the field doesn't have a JSON tag, it doesn't belong in output (and shouldn't exist in a serialized type)

pkg/crd/schema_test.go

@@ -64,7 +64,7 @@ func transform(t *testing.T, expr string) *apiext.JSONSchemaProps {
 	pkg.NeedTypesInfo()
 	failIfErrors(t, pkg.Errors)
 
-	schemaContext := newSchemaContext(pkg, nil, true, false).ForInfo(&markers.TypeInfo{})
+	schemaContext := newSchemaContext(pkg, nil, true, false, FeatureGateMap{}).ForInfo(&markers.TypeInfo{})
 	// yick: grab the only type definition
 	definedType := pkg.Syntax[0].Decls[0].(*ast.GenDecl).Specs[0].(*ast.TypeSpec).Type
 	result := typeToSchema(schemaContext, definedType)