Replace ReferencingServers with structured ReferencingWorkloads on MCPOIDCConfig

RFC-0023 specifies a structured referencingWorkloads list with kind and
name fields rather than plain strings. This replaces the
ReferencingServers []string field on MCPOIDCConfig with
ReferencingWorkloads []WorkloadReference, a new type with Kind and Name
fields that explicitly identifies each referencing workload.

The WorkloadReference type supports MCPServer, VirtualMCPServer, and
MCPRemoteProxy kinds, making the data model self-describing and
type-safe. The MCPServer controller and MCPOIDCConfig controller are
updated to use the new structured type throughout: reference tracking,
deletion protection, watch handlers, and status updates.

The same migration is needed for MCPToolConfig, MCPTelemetryConfig, and
MCPExternalAuthConfig — tracked in #4491.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ChrisJBurns

cmd/thv-operator/api/v1alpha1/mcpoidcconfig_types.go

@@ -132,6 +132,20 @@ type InlineOIDCSharedConfig struct {
 	InsecureAllowHTTP bool `json:"insecureAllowHTTP"`
 }
 
+// WorkloadReference identifies a workload that references a shared configuration resource.
+// Namespace is implicit — cross-namespace references are not supported.
+type WorkloadReference struct {
+	// Kind is the type of workload resource
+	// +kubebuilder:validation:Enum=MCPServer;VirtualMCPServer;MCPRemoteProxy
+	// +kubebuilder:validation:Required
+	Kind string `json:"kind"`
+
+	// Name is the name of the workload resource
+	// +kubebuilder:validation:Required
+	// +kubebuilder:validation:MinLength=1
+	Name string `json:"name"`
+}
+
 // MCPOIDCConfigStatus defines the observed state of MCPOIDCConfig
 type MCPOIDCConfigStatus struct {
 	// Conditions represent the latest available observations of the MCPOIDCConfig's state
@@ -146,9 +160,10 @@ type MCPOIDCConfigStatus struct {
 	// +optional
 	ConfigHash string `json:"configHash,omitempty"`
 
-	// ReferencingServers is a list of MCPServer resources that reference this MCPOIDCConfig
+	// ReferencingWorkloads is a list of workload resources that reference this MCPOIDCConfig.
+	// Each entry identifies the workload by kind and name.
 	// +optional
-	ReferencingServers []string `json:"referencingServers,omitempty"`
+	ReferencingWorkloads []WorkloadReference `json:"referencingWorkloads,omitempty"`
 }
 
 // +kubebuilder:object:root=true

cmd/thv-operator/api/v1alpha1/zz_generated.deepcopy.go

@@ -124,12 +124,12 @@ func (r *MCPOIDCConfigReconciler) Reconcile(ctx context.Context, req ctrl.Reques
 		return ctrl.Result{}, nil
 	}
 
-	// Refresh ReferencingServers list
-	referencingServers, err := r.findReferencingServers(ctx, oidcConfig)
+	// Refresh ReferencingWorkloads list
+	referencingWorkloads, err := r.findReferencingWorkloads(ctx, oidcConfig)
 	if err != nil {
-		logger.Error(err, "Failed to find referencing servers")
-	} else if !slices.Equal(oidcConfig.Status.ReferencingServers, referencingServers) {
-		oidcConfig.Status.ReferencingServers = referencingServers
+		logger.Error(err, "Failed to find referencing workloads")
+	} else if !slices.Equal(oidcConfig.Status.ReferencingWorkloads, referencingWorkloads) {
+		oidcConfig.Status.ReferencingWorkloads = referencingWorkloads
 		conditionChanged = true
 	}
 
@@ -160,26 +160,26 @@ func (r *MCPOIDCConfigReconciler) handleDeletion(
 	logger := log.FromContext(ctx)
 
 	if controllerutil.ContainsFinalizer(oidcConfig, OIDCConfigFinalizerName) {
-		// Check if any MCPServers still reference this config
-		referencingServers, err := r.findReferencingServers(ctx, oidcConfig)
+		// Check if any workloads still reference this config
+		referencingWorkloads, err := r.findReferencingWorkloads(ctx, oidcConfig)
 		if err != nil {
-			logger.Error(err, "Failed to check referencing servers during deletion")
+			logger.Error(err, "Failed to check referencing workloads during deletion")
 			return ctrl.Result{}, err
 		}
 
-		if len(referencingServers) > 0 {
-			logger.Info("MCPOIDCConfig is still referenced by MCPServers, blocking deletion",
+		if len(referencingWorkloads) > 0 {
+			logger.Info("MCPOIDCConfig is still referenced by workloads, blocking deletion",
 				"oidcConfig", oidcConfig.Name,
-				"referencingServers", referencingServers)
+				"referencingWorkloads", referencingWorkloads)
 
 			meta.SetStatusCondition(&oidcConfig.Status.Conditions, metav1.Condition{
 				Type:               "DeletionBlocked",
 				Status:             metav1.ConditionTrue,
-				Reason:             "ReferencedByServers",
-				Message:            fmt.Sprintf("Cannot delete: referenced by MCPServers: %v", referencingServers),
+				Reason:             "ReferencedByWorkloads",
+				Message:            fmt.Sprintf("Cannot delete: referenced by workloads: %v", referencingWorkloads),
 				ObservedGeneration: oidcConfig.Generation,
 			})
-			oidcConfig.Status.ReferencingServers = referencingServers
+			oidcConfig.Status.ReferencingWorkloads = referencingWorkloads
 			if updateErr := r.Status().Update(ctx, oidcConfig); updateErr != nil {
 				logger.Error(updateErr, "Failed to update status during deletion block")
 			}
@@ -199,32 +199,32 @@ func (r *MCPOIDCConfigReconciler) handleDeletion(
 	return ctrl.Result{}, nil
 }
 
-// findReferencingServers returns the names of MCPServer resources that reference
-// this MCPOIDCConfig via their OIDCConfigRef field.
-func (r *MCPOIDCConfigReconciler) findReferencingServers(
+// findReferencingWorkloads returns the workload resources (MCPServer)
+// that reference this MCPOIDCConfig via their OIDCConfigRef field.
+func (r *MCPOIDCConfigReconciler) findReferencingWorkloads(
 	ctx context.Context,
 	oidcConfig *mcpv1alpha1.MCPOIDCConfig,
-) ([]string, error) {
+) ([]mcpv1alpha1.WorkloadReference, error) {
 	mcpServerList := &mcpv1alpha1.MCPServerList{}
 	if err := r.List(ctx, mcpServerList, client.InNamespace(oidcConfig.Namespace)); err != nil {
 		return nil, fmt.Errorf("failed to list MCPServers: %w", err)
 	}
 
-	var refs []string
+	var refs []mcpv1alpha1.WorkloadReference
 	for _, server := range mcpServerList.Items {
 		if server.Spec.OIDCConfigRef != nil && server.Spec.OIDCConfigRef.Name == oidcConfig.Name {
-			refs = append(refs, server.Name)
+			refs = append(refs, mcpv1alpha1.WorkloadReference{Kind: "MCPServer", Name: server.Name})
 		}
 	}
 	return refs, nil
 }
 
 // SetupWithManager sets up the controller with the Manager.
-// Watches MCPServer changes to maintain accurate ReferencingServers status.
+// Watches MCPServer changes to maintain accurate ReferencingWorkloads status.
 func (r *MCPOIDCConfigReconciler) SetupWithManager(mgr ctrl.Manager) error {
-	// Watch MCPServer changes to update ReferencingServers on referenced MCPOIDCConfigs.
+	// Watch MCPServer changes to update ReferencingWorkloads on referenced MCPOIDCConfigs.
 	// This handler enqueues both the currently-referenced MCPOIDCConfig AND any
-	// MCPOIDCConfig that still lists this server in ReferencingServers (covers the
+	// MCPOIDCConfig that still lists this server in ReferencingWorkloads (covers the
 	// case where a server removes its oidcConfigRef — the previously-referenced
 	// config needs to reconcile and clean up the stale entry).
 	mcpServerHandler := handler.EnqueueRequestsFromMapFunc(
@@ -248,7 +248,7 @@ func (r *MCPOIDCConfigReconciler) SetupWithManager(mgr ctrl.Manager) error {
 			}
 
 			// Also enqueue any MCPOIDCConfig that still lists this server in
-			// ReferencingServers — handles ref-removal and server-deletion cases.
+			// ReferencingWorkloads — handles ref-removal and server-deletion cases.
 			oidcConfigList := &mcpv1alpha1.MCPOIDCConfigList{}
 			if err := r.List(ctx, oidcConfigList, client.InNamespace(server.Namespace)); err != nil {
 				log.FromContext(ctx).Error(err, "Failed to list MCPOIDCConfigs for MCPServer watch")
@@ -259,8 +259,8 @@ func (r *MCPOIDCConfigReconciler) SetupWithManager(mgr ctrl.Manager) error {
 				if _, already := seen[nn]; already {
 					continue
 				}
-				for _, ref := range cfg.Status.ReferencingServers {
-					if ref == server.Name {
+				for _, ref := range cfg.Status.ReferencingWorkloads {
+					if ref.Kind == "MCPServer" && ref.Name == server.Name {
 						requests = append(requests, reconcile.Request{NamespacedName: nn})
 						break
 					}

cmd/thv-operator/controllers/mcpoidcconfig_controller.go

@@ -2085,9 +2085,9 @@ func (r *MCPServerReconciler) handleOIDCConfig(ctx context.Context, m *mcpv1alph
 		return fmt.Errorf("%s", msg)
 	}
 
-	// Update ReferencingServers on the MCPOIDCConfig status
-	if err := r.updateOIDCConfigReferencingServers(ctx, oidcConfig, m.Name); err != nil {
-		ctxLogger.Error(err, "Failed to update MCPOIDCConfig ReferencingServers")
+	// Update ReferencingWorkloads on the MCPOIDCConfig status
+	if err := r.updateOIDCConfigReferencingWorkloads(ctx, oidcConfig, m.Name); err != nil {
+		ctxLogger.Error(err, "Failed to update MCPOIDCConfig ReferencingWorkloads")
 		// Non-fatal: continue with reconciliation
 	}
 
@@ -2124,24 +2124,29 @@ func setOIDCConfigRefCondition(m *mcpv1alpha1.MCPServer, status metav1.Condition
 	})
 }
 
-// updateOIDCConfigReferencingServers ensures the MCPServer name is listed in
-// the MCPOIDCConfig's ReferencingServers status field.
-func (r *MCPServerReconciler) updateOIDCConfigReferencingServers(
+// updateOIDCConfigReferencingWorkloads ensures the MCPServer is listed in
+// the MCPOIDCConfig's ReferencingWorkloads status field.
+func (r *MCPServerReconciler) updateOIDCConfigReferencingWorkloads(
 	ctx context.Context,
 	oidcConfig *mcpv1alpha1.MCPOIDCConfig,
 	serverName string,
 ) error {
+	ref := mcpv1alpha1.WorkloadReference{
+		Kind: "MCPServer",
+		Name: serverName,
+	}
+
 	// Check if already listed
-	for _, name := range oidcConfig.Status.ReferencingServers {
-		if name == serverName {
+	for _, entry := range oidcConfig.Status.ReferencingWorkloads {
+		if entry.Kind == ref.Kind && entry.Name == ref.Name {
 			return nil
 		}
 	}
 
-	// Add the server name
-	oidcConfig.Status.ReferencingServers = append(oidcConfig.Status.ReferencingServers, serverName)
+	// Add the workload reference
+	oidcConfig.Status.ReferencingWorkloads = append(oidcConfig.Status.ReferencingWorkloads, ref)
 	if err := r.Status().Update(ctx, oidcConfig); err != nil {
-		return fmt.Errorf("failed to update MCPOIDCConfig ReferencingServers: %w", err)
+		return fmt.Errorf("failed to update MCPOIDCConfig ReferencingWorkloads: %w", err)
 	}
 
 	return nil

cmd/thv-operator/controllers/mcpserver_controller.go

@@ -203,49 +203,53 @@ func TestMCPServerReconciler_handleOIDCConfig(t *testing.T) {
 			if tt.expectReferencingServer && tt.oidcConfig != nil {
 				var updated mcpv1alpha1.MCPOIDCConfig
 				require.NoError(t, fakeClient.Get(ctx, client.ObjectKeyFromObject(tt.oidcConfig), &updated))
-				assert.Contains(t, updated.Status.ReferencingServers, tt.mcpServer.Name)
+				expectedRef := mcpv1alpha1.WorkloadReference{Kind: "MCPServer", Name: tt.mcpServer.Name}
+				assert.Contains(t, updated.Status.ReferencingWorkloads, expectedRef)
 			}
 		})
 	}
 }
 
-func TestMCPServerReconciler_updateOIDCConfigReferencingServers(t *testing.T) {
+func TestMCPServerReconciler_updateOIDCConfigReferencingWorkloads(t *testing.T) {
 	t.Parallel()
 
-	t.Run("adds new server name", func(t *testing.T) {
+	existingRef := mcpv1alpha1.WorkloadReference{Kind: "MCPServer", Name: "existing"}
+
+	t.Run("adds new server reference", func(t *testing.T) {
 		t.Parallel()
 		ctx := t.Context()
 		scheme := runtime.NewScheme()
 		require.NoError(t, mcpv1alpha1.AddToScheme(scheme))
 
 		cfg := &mcpv1alpha1.MCPOIDCConfig{
 			ObjectMeta: metav1.ObjectMeta{Name: "cfg", Namespace: "default"},
-			Status:     mcpv1alpha1.MCPOIDCConfigStatus{ReferencingServers: []string{"existing"}},
+			Status:     mcpv1alpha1.MCPOIDCConfigStatus{ReferencingWorkloads: []mcpv1alpha1.WorkloadReference{existingRef}},
 		}
 		fc := fake.NewClientBuilder().WithScheme(scheme).WithObjects(cfg).
 			WithStatusSubresource(&mcpv1alpha1.MCPOIDCConfig{}).Build()
 		r := newTestMCPServerReconciler(fc, scheme, kubernetes.PlatformKubernetes)
 
-		require.NoError(t, r.updateOIDCConfigReferencingServers(ctx, cfg, "new"))
-		assert.ElementsMatch(t, []string{"existing", "new"}, cfg.Status.ReferencingServers)
+		require.NoError(t, r.updateOIDCConfigReferencingWorkloads(ctx, cfg, "new"))
+		newRef := mcpv1alpha1.WorkloadReference{Kind: "MCPServer", Name: "new"}
+		assert.ElementsMatch(t, []mcpv1alpha1.WorkloadReference{existingRef, newRef}, cfg.Status.ReferencingWorkloads)
 	})
 
-	t.Run("does not duplicate existing name", func(t *testing.T) {
+	t.Run("does not duplicate existing reference", func(t *testing.T) {
 		t.Parallel()
 		ctx := t.Context()
 		scheme := runtime.NewScheme()
 		require.NoError(t, mcpv1alpha1.AddToScheme(scheme))
 
 		cfg := &mcpv1alpha1.MCPOIDCConfig{
 			ObjectMeta: metav1.ObjectMeta{Name: "cfg", Namespace: "default"},
-			Status:     mcpv1alpha1.MCPOIDCConfigStatus{ReferencingServers: []string{"existing"}},
+			Status:     mcpv1alpha1.MCPOIDCConfigStatus{ReferencingWorkloads: []mcpv1alpha1.WorkloadReference{existingRef}},
 		}
 		fc := fake.NewClientBuilder().WithScheme(scheme).WithObjects(cfg).
 			WithStatusSubresource(&mcpv1alpha1.MCPOIDCConfig{}).Build()
 		r := newTestMCPServerReconciler(fc, scheme, kubernetes.PlatformKubernetes)
 
-		require.NoError(t, r.updateOIDCConfigReferencingServers(ctx, cfg, "existing"))
-		assert.Len(t, cfg.Status.ReferencingServers, 1)
+		require.NoError(t, r.updateOIDCConfigReferencingWorkloads(ctx, cfg, "existing"))
+		assert.Len(t, cfg.Status.ReferencingWorkloads, 1)
 	})
 }
 

cmd/thv-operator/controllers/mcpserver_oidcconfig_test.go

@@ -17,6 +17,9 @@ import (
 const (
 	timeout  = time.Second * 30
 	interval = time.Millisecond * 250
+
+	// conditionTypeValid is the MCPOIDCConfig "Valid" condition type
+	conditionTypeValid = "Valid"
 )
 
 var _ = Describe("MCPOIDCConfig Controller", func() {
@@ -61,7 +64,7 @@ var _ = Describe("MCPOIDCConfig Controller", func() {
 				return false
 			}
 			for _, cond := range fetched.Status.Conditions {
-				if cond.Type == "Valid" && cond.Status == metav1.ConditionTrue {
+				if cond.Type == conditionTypeValid && cond.Status == metav1.ConditionTrue {
 					return true
 				}
 			}