BYO resources and reference them

[aliok]

Problem

The current MCPServer CRD is growing with each new feature request. For example:

• ConfigMap mounting requires 3 new fields (configMapRef, configMapMountPath, configMapVolumeName)
• RBAC support added serviceAccountName
• Future user requests will include: rollout policies, pod affinity, resource limits, topology spread constraints, etc.

This leads to two issues:

1. CRD bloat - The API becomes unwieldy with 20+ fields covering every Kubernetes deployment feature
2. Maintenance burden - Every new K8s feature requires CRD updates, testing, and documentation

We need a way to keep the simple use case simple while supporting advanced configurations.

[aliok]

NOTE: I gave up on this idea!

I wanted to discuss a two-CRD Architecture

Introduce two CRDs that serve different user personas:

1. MCPServer (Simple, Beginner-Friendly)

• Minimal fields: image, port, args, serviceAccountName, etc.
• Locked API - won't grow over time
• Managed by operator - creates an MCPServerConfig resource

2. MCPServerConfig (Advanced, Full Control)

• Includes podTemplate (full PodSpec passthrough)
• Includes more detailed service related fields
• Includes more detailed networking/auth/etc. related fields
• Can be created directly by advanced users OR generated by operator from MCPServer

NOTE: MCPServerConfig name is provisional. Welcome to bikeshedding.

User Workflows

Beginner Path

apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
  name: my-mcp-server
spec:
  image: foo.bar:latest
  port: 8080
  serviceAccountName: mcp-viewer

Operator creates a MCPServerConfig out of it.

Advanced Path

apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServerConfig
metadata:
  name: my-advanced-mcp-server
spec:
  image: ghcr.io/modelcontextprotocol/servers/filesystem:latest
  port: 8080

  podTemplate:
    metadata:
      labels:
        version: canary
    spec:
      affinity:
        podAntiAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchLabels:
                  app: my-advanced-mcp-server
              topologyKey: kubernetes.io/hostname
      resources:
        limits:
          memory: 512Mi
        requests:
          memory: 256Mi

  serviceTemplate:
    metadata:
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-type: nlb

Benefits

1. Simple stays simple - MCPServer never grows beyond core fields
2. Future-proof - New K8s features automatically available e.g. via MCPServerConfig.podTemplate
3. Gradual complexity - Users can "graduate" from MCPServer to MCPServerConfig when needed
4. Less code - Don't need to add CRD fields for every deployment feature

Related Patterns

Not exactly the same, but similar:

• Service → Endpoints/EndpointSlice (Service is simple selectors, Endpoints are detailed IPs)

[aliok]

After offline discussions, the 2 CRD idea above is now obsolete.

Issues:

• The 2nd CRD won't solve the CRD bloat problem
• Bad UX
• People would still prefer the simpler CRD, but can ask config options added in it, instead of using the 2nd CRD.

Thanks @everettraven for the API review!

[aliok]

New proposal is this:

• We have 1 CRD only
• The CRD will be opinionated
  • We only add fields that can cover the %80 of the cases and reject the rest
  • If users really need the remaining %20, we advise them to go and create Deployments and other things manually
• We allow BYO Deployment, Service (and other resources if necessary) - detailed below

Bring your own resources approach:

• User creates e.g. Deployment manually. And sets a reference in the MCPServer resource. For example:

spec:
  deploymentRef:
    apiVersion: apps/v1
    kind: Deployment
    name: kubernetes-mcp-server-deployment
  ...

• Not possible to specify Deployment related config (image, etc) when a reference is used
• Controller doesn't reconcile the Deployment or setOwnerRef, but monitors status for setting MCPServer status
• deploymentRef can be even named like workloadRef to allow other PodSpecables, such as StatefulSet, DaemonSet.
• Similar story for Service

To clarify, BYO approach won't be the only option. We will still allow this:

spec:
  image: quay.io/containers/kubernetes_mcp_server:latest
  ...