vMCP: Kubernetes - Controller Implementation

[yrobla]

Description

Implement the Kubernetes controller for VirtualMCPServer that reconciles resources, discovers backends, manages deployments, and reports status.

Scope:

• Implement VirtualMCPServer controller with reconciliation logic
• Backend discovery from MCPGroup
• Create and manage Deployment, Service, ConfigMap
• Status updates with conditions
• Health monitoring and backend tracking

Key Components:

1. Controller Reconciliation

   • Watch VirtualMCPServer resources
   • Watch referenced MCPGroup for membership changes
   • Watch referenced MCPExternalAuthConfig for auth changes
   • Watch referenced MCPToolConfig for tool filter changes
   • Watch referenced VirtualMCPCompositeToolDefinition for workflow changes

2. Backend Discovery

   • Query MCPGroup for workload list
   • Read each workload's MCPServer spec
   • Extract externalAuthConfigRef for discovered mode
   • Build backend configuration map
   • Update status with discovered backends

3. Resource Management

   • Deployment: Create vmcp container deployment
   • Service: Expose VirtualMCPServer (ClusterIP or LoadBalancer)
   • ConfigMap: Generate configuration from CRD spec
   • Set owner references for garbage collection
   • Update resources on spec changes

4. Configuration Generation

   • Convert VirtualMCPServer CRD spec to vmcp CLI config format
   • Merge discovered backend auth configurations
   • Apply conflict resolution settings
   • Include composite tool definitions
   • Store in ConfigMap for vmcp binary

5. Status Management

   • Use StatusCollector pattern (existing ToolHive pattern)
   • Update conditions: Ready, AuthConfigured, BackendsDiscovered
   • Track discovered backends with auth types
   • Report capability counts (from aggregation)
   • Phase: Pending, Ready, Degraded, Failed

6. Health Monitoring

   • Periodic backend health checks
   • Update backend status in VirtualMCPServer status
   • Trigger reconciliation on health changes
   • Circuit breaker integration

Related Proposal Sections:

• Discovery Mode Example (lines 643-698)
• Backend Discovery (proposal section on group-based management)

Dependencies:

• Issue Add provenance information to packaging #151 (Kubernetes - VirtualMCPServer CRD) - CRD definition
• Issue Version command in release binaries showing "dev" #153 (Binary Setup) - vmcp binary and container image
• Issue Update architecture diagram #146 (Configuration) - CLI config format
• Existing operator infrastructure and patterns

Implementation Notes:

• Follow MCPServer controller patterns
• Reuse StatusCollector from mcpregistrystatus package
• Use controller-runtime client for queries
• Handle partial backend availability gracefully
• Support rolling updates for config changes
• vmcp container runs as Deployment (not StatefulSet)

Additional Context

Reference: https://github.com/stacklok/toolhive/blob/main/docs/proposals/THV-2106-virtual-mcp-server.md

This is part 3 of 4 for Kubernetes support.

Acceptance Criteria

• VirtualMCPServer controller scaffolded
• Reconciliation logic for VirtualMCPServer resources
• Watch MCPGroup for backend membership changes
• Watch MCPExternalAuthConfig changes
• Watch MCPToolConfig changes
• Watch VirtualMCPCompositeToolDefinition changes
• Backend discovery from MCPGroup workloads
• Extract externalAuthConfigRef from backend MCPServers
• Deployment creation and updates
• Service creation (ClusterIP/LoadBalancer configurable)
• ConfigMap generation with vmcp configuration
• Owner reference management
• Status updates using StatusCollector
• Condition management (Ready, AuthConfigured, BackendsDiscovered)
• Discovered backends tracking in status
• Backend health monitoring
• Graceful handling of unavailable backends
• Unit tests for controller logic
• Integration tests with envtest
• Documentation: Controller architecture and reconciliation flow