[RFE] specify cluster details on request

[thoraxe]

Summary

Add support for dynamic Kubernetes cluster targeting through HTTP headers, allowing AI systems to specify cluster endpoints and TLS configuration per-request without requiring pre-configured kubeconfig contexts.

Problem Statement

Currently, the MCP server only supports targeting clusters that are pre-configured in a kubeconfig file via the context parameter. This requires:

1. Pre-configuration: All target clusters must be known and configured ahead of time
2. Static configuration: Cannot dynamically connect to new clusters
3. LLM parameter pollution: Adding dynamic cluster support via tool parameters would require LLMs to understand infrastructure details

For AI systems that need to interact with multiple Kubernetes clusters dynamically (e.g., multi-tenant scenarios, ephemeral clusters, or clusters discovered at runtime), the current approach is limiting.

Proposed Solution

Add support for specifying cluster connection details via HTTP headers while maintaining 100% backward compatibility with the existing context-based approach.

New HTTP Headers

  X-Kubernetes-Cluster-Server: https://cluster.example.com:6443
  X-Kubernetes-Cluster-CA-Data: LS0tLS1CRUdJTi...  # base64 encoded CA cert
  X-Kubernetes-Cluster-Insecure: false              # optional, default: false
  X-Kubernetes-Cluster-Server-Name: cluster.example.com  # optional, for SNI

Precedence Logic

1. If X-Kubernetes-Cluster-Server header is present: Use dynamic cluster from headers
2. Else if context parameter is present: Use kubeconfig context (existing behavior)
3. Else: Use default kubeconfig context (existing behavior)

Benefits

Clean Separation of Concerns

• LLM tool parameters: Remain focused on Kubernetes resources and operations

• Infrastructure configuration: Handled at the HTTP header level by the AI system

• No parameter pollution: Tool signatures stay clean and focused

  Backward Compatibility

  • ✅ All existing configurations work unchanged
  • ✅ All existing API calls work unchanged
  • ✅ Headers are completely optional
  • ✅ Zero migration required

  Flexibility

  • Switch clusters per request without changing tool parameters
  • Set headers once and reuse across multiple tool calls
  • Support for ephemeral or dynamically discovered clusters
  • Standard HTTP header patterns

Example Usage

Current Approach (Unchanged)

  POST /mcp/tools/call
  Authorization: Bearer token123
  Content-Type: application/json

  {
    "method": "tools/call",
    "params": {
      "name": "pods_list",
      "arguments": {
        "context": "prod-cluster",  // Uses kubeconfig context
        "namespace": "default"
      }
    }
  }

New Dynamic Approach

  POST /mcp/tools/call
  Authorization: Bearer token123
  X-Kubernetes-Cluster-Server: https://my-cluster.example.com:6443
  X-Kubernetes-Cluster-CA-Data: LS0tLS1CRUdJTi...
  Content-Type: application/json

  {
    "method": "tools/call",
    "params": {
      "name": "pods_list",
      "arguments": {
        "namespace": "default"  // Clean tool parameters - no cluster info
      }
    }
  }

Implementation Approach

Phase 1: Core Implementation

1. Header extraction: Enhance contextFunc() in pkg/mcp/mcp.go to extract cluster headers
2. Manager enhancement: Modify Manager.Derived() in pkg/kubernetes/manager.go to handle dynamic clusters
3. Configuration validation: Basic URL parsing and CA certificate validation

Phase 2: Production Features

1. Configuration options: Optional settings for enabling/disabling dynamic clusters
2. Audit logging: Track dynamic cluster usage for security/compliance
3. Rate limiting: Prevent resource exhaustion from dynamic requests
4. Error handling: Comprehensive validation and error messages

Configuration (Optional)

  # Optional: Enable dynamic cluster headers (default: true)
  enable_dynamic_cluster_headers = true

  # Optional: Operational controls
  [dynamic_clusters]
  audit_dynamic_requests = true
  max_dynamic_requests_per_minute = 100
  request_timeout = "30s"

Security Considerations

Why This Is Safe

• No additional attack surface: Users with valid bearer tokens can already access these clusters directly
• Standard patterns: Uses established HTTP header security practices
• Validation: URL parsing and certificate validation prevent malformed requests
• Audit trail: Optional logging for compliance requirements

Controls

• Rate limiting: Prevent server resource exhaustion
• Request validation: Ensure well-formed cluster specifications
• Audit logging: Track dynamic cluster access for compliance

Files to Modify

1. pkg/mcp/mcp.go: Enhance contextFunc() to extract cluster headers
2. pkg/kubernetes/manager.go: Modify Derived() method to handle dynamic clusters
3. pkg/config/config.go: Add optional configuration for dynamic cluster support
4. Tests and documentation

Alternatives Considered

1. Tool parameters: Rejected because it pollutes LLM-facing parameters with infrastructure details
2. Configuration endpoints: Rejected because it requires additional API complexity
3. Replace existing approach: Rejected to maintain backward compatibility

Open Questions

1. Should there be any allowlisting of cluster domains/IPs, or is token-based access control sufficient?
2. Should we add connection pooling for frequently accessed dynamic clusters?
3. Any specific naming preferences for the HTTP headers?