feat: Enhance RBAC feature gates with multiple gate support

Based on feedback from PR kubernetes-sigs#1259 review comments, enhance RBAC feature gates with:

- Support for complex feature gate expressions using OR (|) and AND (&) logic
- Enhanced documentation with clear usage examples
- Validation for feature gate expressions with proper error handling
- Comprehensive test coverage for multiple gate scenarios

New feature gate syntax:
- Single gate: featureGate=alpha
- OR logic: featureGate=alpha|beta (enabled if ANY gate is true)
- AND logic: featureGate=alpha&beta (enabled if ALL gates are true)

Examples:
// +kubebuilder:rbac:featureGate=alpha|beta,groups=apps,resources=deployments,verbs=get;list
// +kubebuilder:rbac:featureGate=alpha&beta,groups="",resources=services,verbs=get;list

Addresses maintainer feedback on expression validation, multiple gate support,
and improved documentation clarity.

Author: sami-wazery

pkg/rbac/advanced_feature_gates_test.go

@@ -0,0 +1,143 @@
+package rbac
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/onsi/gomega"
+	"sigs.k8s.io/controller-tools/pkg/genall"
+	"sigs.k8s.io/controller-tools/pkg/loader"
+	"sigs.k8s.io/controller-tools/pkg/markers"
+	rbacv1 "k8s.io/api/rbac/v1"
+)
+
+func TestAdvancedFeatureGates(t *testing.T) {
+	g := gomega.NewWithT(t)
+
+	// Load test packages
+	pkgs, err := loader.LoadRoots("./testdata/advanced_feature_gates")
+	g.Expect(err).NotTo(gomega.HaveOccurred())
+
+	// Set up generation context
+	reg := &markers.Registry{}
+	g.Expect(reg.Register(RuleDefinition)).To(gomega.Succeed())
+	
+	ctx := &genall.GenerationContext{
+		Collector: &markers.Collector{Registry: reg},
+		Roots:     pkgs,
+	}
+
+	tests := []struct {
+		name           string
+		featureGates   string
+		expectedRules  int
+		shouldContain  []string
+		shouldNotContain []string
+	}{
+		{
+			name:         "OR logic - alpha enabled",
+			featureGates: "alpha=true,beta=false",
+			expectedRules: 3, // always-on + OR rule (alpha|beta)
+			shouldContain: []string{"pods", "configmaps", "secrets"},
+			shouldNotContain: []string{"services"},
+		},
+		{
+			name:         "OR logic - beta enabled",
+			featureGates: "alpha=false,beta=true",
+			expectedRules: 3, // always-on + OR rule (alpha|beta)
+			shouldContain: []string{"pods", "configmaps", "secrets"},
+			shouldNotContain: []string{"services"},
+		},
+		{
+			name:         "OR logic - both enabled",
+			featureGates: "alpha=true,beta=true",
+			expectedRules: 4, // always-on + OR rule + AND rule
+			shouldContain: []string{"pods", "configmaps", "secrets", "services"},
+			shouldNotContain: []string{},
+		},
+		{
+			name:         "OR logic - neither enabled",
+			featureGates: "alpha=false,beta=false",
+			expectedRules: 2, // only always-on
+			shouldContain: []string{"pods", "configmaps"},
+			shouldNotContain: []string{"secrets", "services"},
+		},
+		{
+			name:         "AND logic - only alpha enabled",
+			featureGates: "alpha=true,beta=false",
+			expectedRules: 3, // always-on + OR rule (alpha|beta)
+			shouldContain: []string{"pods", "configmaps", "secrets"},
+			shouldNotContain: []string{"services"},
+		},
+		{
+			name:         "AND logic - both enabled",
+			featureGates: "alpha=true,beta=true",
+			expectedRules: 4, // always-on + OR rule + AND rule
+			shouldContain: []string{"pods", "configmaps", "secrets", "services"},
+			shouldNotContain: []string{},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			g := gomega.NewWithT(t)
+			
+			objs, err := GenerateRoles(ctx, "test-role", tt.featureGates)
+			g.Expect(err).NotTo(gomega.HaveOccurred())
+			g.Expect(objs).To(gomega.HaveLen(1))
+
+			role, ok := objs[0].(rbacv1.ClusterRole)
+			g.Expect(ok).To(gomega.BeTrue())
+			g.Expect(role.Rules).To(gomega.HaveLen(tt.expectedRules))
+
+			// Convert rules to string for easier checking
+			rulesStr := ""
+			for _, rule := range role.Rules {
+				rulesStr += strings.Join(rule.Resources, ",") + " "
+			}
+
+			for _, resource := range tt.shouldContain {
+				g.Expect(rulesStr).To(gomega.ContainSubstring(resource), 
+					"Expected resource %s to be present", resource)
+			}
+
+			for _, resource := range tt.shouldNotContain {
+				g.Expect(rulesStr).NotTo(gomega.ContainSubstring(resource),
+					"Expected resource %s to be absent", resource)
+			}
+		})
+	}
+}
+
+func TestFeatureGateValidation(t *testing.T) {
+	tests := []struct {
+		name        string
+		expression  string
+		shouldError bool
+	}{
+		{name: "empty expression", expression: "", shouldError: false},
+		{name: "single gate", expression: "alpha", shouldError: false},
+		{name: "OR expression", expression: "alpha|beta", shouldError: false},
+		{name: "AND expression", expression: "alpha&beta", shouldError: false},
+		{name: "mixed operators", expression: "alpha&beta|gamma", shouldError: true},
+		{name: "invalid character", expression: "alpha@beta", shouldError: true},
+		{name: "hyphenated gate", expression: "feature-alpha", shouldError: false},
+		{name: "underscore gate", expression: "feature_alpha", shouldError: false},
+		{name: "numeric gate", expression: "v1beta1", shouldError: false},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := validateFeatureGateExpression(tt.expression)
+			if tt.shouldError {
+				if err == nil {
+					t.Errorf("Expected error for expression %s, but got none", tt.expression)
+				}
+			} else {
+				if err != nil {
+					t.Errorf("Expected no error for expression %s, but got: %v", tt.expression, err)
+				}
+			}
+		})
+	}
+}

pkg/rbac/parser.go

@@ -60,9 +60,11 @@ type Rule struct {
 	// If not set, the Rule belongs to the generated ClusterRole.
 	// If set, the Rule belongs to a Role, whose namespace is specified by this field.
 	Namespace string `marker:",optional"`
-	// FeatureGate specifies the feature gate that controls this RBAC rule.
+	// FeatureGate specifies the feature gate(s) that control this RBAC rule.
 	// If not set, the rule is always included.
-	// If set, the rule is only included when the specified feature gate is enabled.
+	// If set to a single gate (e.g., "alpha"), the rule is included when that gate is enabled.
+	// If set to multiple gates separated by "|" (e.g., "alpha|beta"), the rule is included when ANY of the gates are enabled (OR logic).
+	// If set to multiple gates separated by "&" (e.g., "alpha&beta"), the rule is included when ALL of the gates are enabled (AND logic).
 	FeatureGate string `marker:"featureGate,optional"`
 }
 
@@ -176,6 +178,8 @@ type Generator struct {
 
 	// FeatureGates is a comma-separated list of feature gates to enable (e.g., "alpha=true,beta=false").
 	// Only RBAC rules with matching feature gates will be included in the generated output.
+	// Feature gates not explicitly listed are treated as disabled.
+	// Usage: controller-gen 'rbac:roleName=manager,featureGates="alpha=true,beta=false"' paths=./...
 	FeatureGates string `marker:",optional"`
 }
 
@@ -211,15 +215,70 @@ func parseFeatureGates(featureGates string) FeatureGateMap {
 	return gates
 }
 
+// validateFeatureGateExpression validates the syntax of a feature gate expression
+func validateFeatureGateExpression(expr string) error {
+	if expr == "" {
+		return nil
+	}
+
+	// Check for invalid characters (only allow alphanumeric, hyphens, underscores, &, |)
+	for _, char := range expr {
+		if !((char >= 'a' && char <= 'z') || (char >= 'A' && char <= 'Z') || 
+			 (char >= '0' && char <= '9') || char == '-' || char == '_' || 
+			 char == '&' || char == '|') {
+			return fmt.Errorf("invalid character '%c' in feature gate expression: %s", char, expr)
+		}
+	}
+
+	// Check for mixing AND and OR operators
+	hasAnd := strings.Contains(expr, "&")
+	hasOr := strings.Contains(expr, "|")
+	if hasAnd && hasOr {
+		return fmt.Errorf("cannot mix '&' and '|' operators in feature gate expression: %s", expr)
+	}
+
+	return nil
+}
+
 // shouldIncludeRule determines if an RBAC rule should be included based on feature gates
+// Supports multiple gate logic:
+// - Single gate: "alpha" - included if alpha=true
+// - OR logic: "alpha|beta" - included if either alpha=true OR beta=true
+// - AND logic: "alpha&beta" - included if both alpha=true AND beta=true
 func shouldIncludeRule(rule *Rule, enabledGates FeatureGateMap) bool {
 	if rule.FeatureGate == "" {
 		// No feature gate specified, always include
 		return true
 	}
 
-	// Check if the feature gate is enabled
-	enabled, exists := enabledGates[rule.FeatureGate]
+	featureGateExpr := rule.FeatureGate
+
+	// Handle AND logic (all gates must be enabled)
+	if strings.Contains(featureGateExpr, "&") {
+		gates := strings.Split(featureGateExpr, "&")
+		for _, gate := range gates {
+			gate = strings.TrimSpace(gate)
+			if enabled, exists := enabledGates[gate]; !exists || !enabled {
+				return false
+			}
+		}
+		return true
+	}
+
+	// Handle OR logic (any gate can be enabled)
+	if strings.Contains(featureGateExpr, "|") {
+		gates := strings.Split(featureGateExpr, "|")
+		for _, gate := range gates {
+			gate = strings.TrimSpace(gate)
+			if enabled, exists := enabledGates[gate]; exists && enabled {
+				return true
+			}
+		}
+		return false
+	}
+
+	// Single gate logic
+	enabled, exists := enabledGates[featureGateExpr]
 	return exists && enabled
 }
 
@@ -238,6 +297,11 @@ func GenerateRoles(ctx *genall.GenerationContext, roleName string, featureGates
 		for _, markerValue := range markerSet[RuleDefinition.Name] {
 			rule := markerValue.(Rule)
 
+			// Validate feature gate expression syntax
+			if err := validateFeatureGateExpression(rule.FeatureGate); err != nil {
+				return nil, fmt.Errorf("invalid feature gate expression in RBAC rule: %w", err)
+			}
+			
 			// Apply feature gate filtering
 			if !shouldIncludeRule(&rule, enabledGates) {
 				continue

pkg/rbac/testdata/advanced_feature_gates/controller.go

@@ -0,0 +1,17 @@
+package testdata
+
+// Always included RBAC rule
+// +kubebuilder:rbac:groups="",resources=pods,verbs=get;list;watch
+
+// Another always included rule
+// +kubebuilder:rbac:groups="",resources=configmaps,verbs=get;list
+
+// OR logic: alpha OR beta feature gate RBAC rule
+// +kubebuilder:rbac:featureGate=alpha|beta,groups="",resources=secrets,verbs=get;list;create
+
+// AND logic: alpha AND beta feature gate RBAC rule  
+// +kubebuilder:rbac:featureGate=alpha&beta,groups="",resources=services,verbs=get;list;create;update;delete
+
+func main() {
+	// Test file for advanced RBAC feature gates
+}