refactor: update GatewayConfig controller to remove finalizer management

This commit refactors the GatewayConfig controller to eliminate finalizer management, simplifying the lifecycle handling of GatewayConfig resources. The controller now focuses on notifying referencing Gateways of changes without blocking deletion based on references.

Additionally, the documentation has been updated to reflect these changes, including the removal of finalizer behavior descriptions from the API and capability documentation.

Signed-off-by: Shabab Qaisar <[email protected]>

Author: sqaisar

api/v1alpha1/gateway_config.go

@@ -30,12 +30,6 @@ import (
 // If the same environment variable name exists in both sources, the GatewayConfig
 // value takes precedence.
 //
-// Finalizer Behavior:
-// A finalizer is automatically added to the GatewayConfig when it is first referenced
-// by a Gateway. The finalizer is removed when no Gateways reference it, allowing
-// the GatewayConfig to be deleted. This prevents accidental deletion of configurations
-// that are still in use.
-//
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 // +kubebuilder:object:root=true
@@ -78,8 +72,6 @@ type GatewayConfigExtProc struct {
 	//
 	// Common use cases include:
 	// - OTEL tracing configuration (e.g., OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_ENDPOINT)
-	// - Log level overrides
-	// - Feature flags
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=32

internal/controller/ai_gateway_route.go

@@ -46,9 +46,6 @@ const (
 	// GatewayConfigAnnotationKey is the annotation key used on Gateway objects to reference a GatewayConfig.
 	// The value should be the name of the GatewayConfig resource in the same namespace as the Gateway.
 	GatewayConfigAnnotationKey = "aigateway.envoyproxy.io/gateway-config"
-	// GatewayConfigFinalizerName is the finalizer added to GatewayConfig resources to prevent deletion
-	// while they are still referenced by Gateway objects.
-	GatewayConfigFinalizerName = "aigateway.envoyproxy.io/gateway-config-protection"
 )
 
 // AIGatewayRouteController implements [reconcile.TypedReconciler].

internal/controller/controller.go

@@ -214,7 +214,6 @@ func StartControllers(ctx context.Context, mgr manager.Manager, config *rest.Con
 	// GatewayConfig controller for gateway-scoped configuration.
 	gatewayConfigC := NewGatewayConfigController(c, logger.WithName("gateway-config"), gatewayEventChan)
 	if err = TypedControllerBuilderForCRD(mgr, &aigv1a1.GatewayConfig{}).
-		Watches(&gwapiv1.Gateway{}, handler.EnqueueRequestsFromMapFunc(gatewayConfigC.MapGatewayToGatewayConfig)).
 		Complete(gatewayConfigC); err != nil {
 		return fmt.Errorf("failed to create controller for GatewayConfig: %w", err)
 	}
@@ -282,6 +281,8 @@ const (
 	// k8sClientIndexAIServiceBackendToTargetingBackendSecurityPolicy is the index name that maps from an AIServiceBackend
 	// to the BackendSecurityPolicy whose targetRefs contains the AIServiceBackend.
 	k8sClientIndexAIServiceBackendToTargetingBackendSecurityPolicy = "AIServiceBackendToTargetingBackendSecurityPolicy"
+	// k8sClientIndexGatewayToGatewayConfig maps from a GatewayConfig name to Gateways referencing it.
+	k8sClientIndexGatewayToGatewayConfig = "GatewayToGatewayConfig"
 
 	// Indexes for MCP Gateway
 	//
@@ -313,6 +314,12 @@ func ApplyIndexing(ctx context.Context, indexer func(ctx context.Context, obj cl
 		return fmt.Errorf("failed to index field for BackendSecurityPolicy targetRefs: %w", err)
 	}
 
+	err = indexer(ctx, &gwapiv1.Gateway{},
+		k8sClientIndexGatewayToGatewayConfig, gatewayToGatewayConfigIndexFunc)
+	if err != nil {
+		return fmt.Errorf("failed to create index from GatewayConfig to Gateway: %w", err)
+	}
+
 	// Apply indexes to MCP Gateways.
 	err = indexer(ctx, &aigv1a1.MCPRoute{},
 		k8sClientIndexMCPRouteToAttachedGateway, mcpRouteToAttachedGatewayIndexFunc)
@@ -336,6 +343,18 @@ func mcpRouteToAttachedGatewayIndexFunc(o client.Object) []string {
 	return ret
 }
 
+func gatewayToGatewayConfigIndexFunc(o client.Object) []string {
+	gateway := o.(*gwapiv1.Gateway)
+	if gateway.Annotations == nil {
+		return nil
+	}
+	configName, ok := gateway.Annotations[GatewayConfigAnnotationKey]
+	if !ok || configName == "" {
+		return nil
+	}
+	return []string{configName}
+}
+
 func aiGatewayRouteToAttachedGatewayIndexFunc(o client.Object) []string {
 	aiGatewayRoute := o.(*aigv1a1.AIGatewayRoute)
 	var ret []string

internal/controller/gateway_config.go

@@ -15,7 +15,6 @@ import (
 	"k8s.io/client-go/util/retry"
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/client"
-	ctrlutil "sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
 	"sigs.k8s.io/controller-runtime/pkg/event"
 	"sigs.k8s.io/controller-runtime/pkg/reconcile"
 	gwapiv1 "sigs.k8s.io/gateway-api/apis/v1"
@@ -25,7 +24,7 @@ import (
 
 // GatewayConfigController implements [reconcile.TypedReconciler] for [aigv1a1.GatewayConfig].
 //
-// This handles the GatewayConfig resource and manages finalizers based on Gateway references.
+// This handles the GatewayConfig resource and notifies referencing Gateways of changes.
 //
 // Exported for testing purposes.
 type GatewayConfigController struct {
@@ -78,116 +77,44 @@ func (c *GatewayConfigController) syncGatewayConfig(ctx context.Context, gateway
 		return fmt.Errorf("failed to find referencing Gateways: %w", err)
 	}
 
-	// Handle finalizer based on whether any Gateways reference this GatewayConfig.
 	if gatewayConfig.DeletionTimestamp != nil {
-		// GatewayConfig is being deleted.
-		if len(referencingGateways) > 0 {
-			// Cannot delete yet - Gateways still reference this GatewayConfig.
-			c.logger.Info("GatewayConfig is being deleted but still has referencing Gateways",
-				"namespace", gatewayConfig.Namespace, "name", gatewayConfig.Name,
-				"referencingGateways", len(referencingGateways))
-			return fmt.Errorf("cannot delete GatewayConfig: still referenced by %d Gateway(s)", len(referencingGateways))
-		}
-		// No more references, remove finalizer.
-		if ctrlutil.ContainsFinalizer(gatewayConfig, GatewayConfigFinalizerName) {
-			ctrlutil.RemoveFinalizer(gatewayConfig, GatewayConfigFinalizerName)
-			if err := c.client.Update(ctx, gatewayConfig); err != nil {
-				return fmt.Errorf("failed to remove finalizer: %w", err)
-			}
-			c.logger.Info("Removed finalizer from GatewayConfig",
-				"namespace", gatewayConfig.Namespace, "name", gatewayConfig.Name)
-		}
+		c.notifyReferencingGateways(gatewayConfig, referencingGateways)
 		return nil
 	}
 
-	// GatewayConfig is not being deleted.
-	// Add finalizer if there are referencing Gateways and finalizer is not present.
-	if len(referencingGateways) > 0 && !ctrlutil.ContainsFinalizer(gatewayConfig, GatewayConfigFinalizerName) {
-		ctrlutil.AddFinalizer(gatewayConfig, GatewayConfigFinalizerName)
-		if err := c.client.Update(ctx, gatewayConfig); err != nil {
-			return fmt.Errorf("failed to add finalizer: %w", err)
-		}
-		c.logger.Info("Added finalizer to GatewayConfig",
-			"namespace", gatewayConfig.Namespace, "name", gatewayConfig.Name)
-	}
-
-	// Remove finalizer if no Gateways reference this GatewayConfig.
-	if len(referencingGateways) == 0 && ctrlutil.ContainsFinalizer(gatewayConfig, GatewayConfigFinalizerName) {
-		ctrlutil.RemoveFinalizer(gatewayConfig, GatewayConfigFinalizerName)
-		if err := c.client.Update(ctx, gatewayConfig); err != nil {
-			return fmt.Errorf("failed to remove finalizer: %w", err)
-		}
-		c.logger.Info("Removed finalizer from GatewayConfig (no more references)",
-			"namespace", gatewayConfig.Namespace, "name", gatewayConfig.Name)
-	}
-
 	// Notify all referencing Gateways to reconcile.
-	for _, gw := range referencingGateways {
-		c.logger.Info("Notifying Gateway of GatewayConfig change",
-			"gateway_namespace", gw.Namespace, "gateway_name", gw.Name,
-			"gatewayconfig_name", gatewayConfig.Name)
-		c.gatewayEventChan <- event.GenericEvent{Object: gw}
-	}
+	c.notifyReferencingGateways(gatewayConfig, referencingGateways)
 
 	return nil
 }
 
 // findReferencingGateways finds all Gateways in the same namespace that reference this GatewayConfig.
 func (c *GatewayConfigController) findReferencingGateways(ctx context.Context, gatewayConfig *aigv1a1.GatewayConfig) ([]*gwapiv1.Gateway, error) {
 	var gateways gwapiv1.GatewayList
-	if err := c.client.List(ctx, &gateways, client.InNamespace(gatewayConfig.Namespace)); err != nil {
+	if err := c.client.List(
+		ctx,
+		&gateways,
+		client.InNamespace(gatewayConfig.Namespace),
+		client.MatchingFields{k8sClientIndexGatewayToGatewayConfig: gatewayConfig.Name},
+	); err != nil {
 		return nil, fmt.Errorf("failed to list Gateways: %w", err)
 	}
 
-	var referencingGateways []*gwapiv1.Gateway
+	referencingGateways := make([]*gwapiv1.Gateway, 0, len(gateways.Items))
 	for i := range gateways.Items {
 		gw := &gateways.Items[i]
-		if gw.Annotations == nil {
-			continue
-		}
-		configName, ok := gw.Annotations[GatewayConfigAnnotationKey]
-		if !ok {
-			continue
-		}
-		if configName == gatewayConfig.Name {
-			referencingGateways = append(referencingGateways, gw)
-		}
+		referencingGateways = append(referencingGateways, gw)
 	}
 
 	return referencingGateways, nil
 }
 
-// MapGatewayToGatewayConfig is a handler function that maps Gateway events to GatewayConfig reconcile requests.
-// This is used by the controller builder to watch Gateway resources.
-func (c *GatewayConfigController) MapGatewayToGatewayConfig(_ context.Context, obj client.Object) []reconcile.Request {
-	gateway, ok := obj.(*gwapiv1.Gateway)
-	if !ok {
-		return nil
-	}
-
-	// Check if this Gateway has a GatewayConfig annotation.
-	if gateway.Annotations == nil {
-		return nil
-	}
-
-	configName, ok := gateway.Annotations[GatewayConfigAnnotationKey]
-	if !ok || configName == "" {
-		return nil
-	}
-
-	// Return a reconcile request for the referenced GatewayConfig.
-	// GatewayConfig must be in the same namespace as the Gateway.
-	c.logger.Info("Gateway references GatewayConfig, triggering reconcile",
-		"gateway_namespace", gateway.Namespace, "gateway_name", gateway.Name,
-		"gatewayconfig_name", configName)
-
-	return []reconcile.Request{
-		{
-			NamespacedName: client.ObjectKey{
-				Name:      configName,
-				Namespace: gateway.Namespace,
-			},
-		},
+func (c *GatewayConfigController) notifyReferencingGateways(gatewayConfig *aigv1a1.GatewayConfig, referencingGateways []*gwapiv1.Gateway) {
+	for _, gw := range referencingGateways {
+		c.logger.Info("Notifying Gateway of GatewayConfig change",
+			"gateway_namespace", gw.Namespace, "gateway_name", gw.Name,
+			"gatewayconfig_name", gatewayConfig.Name)
+		c.gatewayEventChan <- event.GenericEvent{Object: gw}
 	}
 }