OCPMCP-200: feat: add kuadrant mcp gateway integration

[Cali0707]

This PR takes a first pass at adding a gateway integration to our downstream.

To avoid merge conflict issues as much as possible this is implemented in a separate controller (using status patches only to avoid conflicts), and it leverages annotations instead of spec changes.

To configure an MCP server to be registered with the gateway the user only needs to add a annotation:

# MCPServer resource with ServiceAccount for RBAC
apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
  name: kubernetes-mcp-server
  namespace: default
  annotations:
    mcp.x-k8s.io/gateway-ref: gateway-system/mcp-gateway
    mcp.x-k8s.io/gateway-tool-prefix: kube_
    # mcp.x-k8s.io/gateway-hostname: kube.mcp.local

The gateway-ref annotation is the only required one (without this we don't reconcile gateway resources). The other two allow some customization on how this is reconciled

[openshift-ci-robot]

@Cali0707: This pull request explicitly references no jira issue.

Details

In response to this:

This PR takes a first pass at adding a gateway integration to our downstream.

To avoid merge conflict issues as much as possible this is implemented in a separate controller (using status patches only to avoid conflicts), and it leverages annotations instead of spec changes.

To configure an MCP server to be registered with the gateway the user only needs to add a annotation:

# MCPServer resource with ServiceAccount for RBAC
apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
 name: kubernetes-mcp-server
 namespace: default
 annotations:
   mcp.x-k8s.io/gateway-ref: gateway-system/mcp-gateway
   mcp.x-k8s.io/gateway-tool-prefix: kube_
   # mcp.x-k8s.io/gateway-hostname: kube.mcp.local

The gateway-ref annotation is the only required one (without this we don't reconcile gateway resources). The other two allow some customization on how this is reconciled

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[Cali0707]

@matzew @aliok @jaideepr97 looks like we don't have any CI set up downstream yet...

[matzew]

/hold DO NOT MERGE

let's first get the upstream refactors in place

[matzew]

would it be better to move these to a dedicated package?
I like they are mostly new/standalone files.

But might be good - does not have to be now - just wondering

[grs]

I like this, nice work!

In thinking a little about it though, I wonder if we can do something in the CRD itself. E.g. in the post-refactored schema, could we have an 'extensions', 'integrations' or perhaps even 'gateways' field that could take a list of objects, perhaps just starting with a type and list of name value pairs in the first instance.

This isn't really much different to annotations, but I think it lays the path for more of these sorts of added value integrations. I would even think we could allow many of them (including one for the kuadrant mcp-gateway) in the upstream as it would be non-exclusionary.

Just a thought.

On a separate point entirely, would it also be worth having a flag that causes a network policy to be created that prevents access to the actual mcp server by anything except gateway pods? (Otherwise, if you have on cluster access, you can just bypass the gateway and any protections or policies it might be trying to enforce).

[matzew]

I would even think we could allow many of them (including one for the kuadrant mcp-gateway) in the upstream as it would be non-exclusionary.

I guess that is something we could do. I'd raise that upstream as something to discuss - with the argument that there are some abstract "mcp gateways", and potential integration might be handy

e.g. like the kubernetes ecosystem knows about "service mesh" integrations, like istio - and others.

[matzew]

On a separate point entirely, would it also be worth having a flag that causes a network policy to be created that prevents access to the actual mcp server by anything except gateway pods? (Otherwise, if you have on cluster access, you can just bypass the gateway and any protections or policies it might be trying to enforce).

That is a very good point!

[openshift-ci-robot]

@Cali0707: This pull request references OCPMCP-200 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "4.22.0" version, but no target version was set.

Details

In response to this:

This PR takes a first pass at adding a gateway integration to our downstream.

To avoid merge conflict issues as much as possible this is implemented in a separate controller (using status patches only to avoid conflicts), and it leverages annotations instead of spec changes.

To configure an MCP server to be registered with the gateway the user only needs to add a annotation:

# MCPServer resource with ServiceAccount for RBAC
apiVersion: mcp.x-k8s.io/v1alpha1
kind: MCPServer
metadata:
 name: kubernetes-mcp-server
 namespace: default
 annotations:
   mcp.x-k8s.io/gateway-ref: gateway-system/mcp-gateway
   mcp.x-k8s.io/gateway-tool-prefix: kube_
   # mcp.x-k8s.io/gateway-hostname: kube.mcp.local

The gateway-ref annotation is the only required one (without this we don't reconcile gateway resources). The other two allow some customization on how this is reconciled

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[Cali0707]

I would even think we could allow many of them (including one for the kuadrant mcp-gateway) in the upstream as it would be non-exclusionary.

I guess that is something we could do. I'd raise that upstream as something to discuss - with the argument that there are some abstract "mcp gateways", and potential integration might be handy

e.g. like the kubernetes ecosystem knows about "service mesh" integrations, like istio - and others.

+1 - let's try to upstream this idea

[jaideepr97]

On a separate point entirely, would it also be worth having a flag that causes a network policy to be created that prevents access to the actual mcp server by anything except gateway pods? (Otherwise, if you have on cluster access, you can just bypass the gateway and any protections or policies it might be trying to enforce).

Along similar lines, one of the questions I had shared on slack was whether we would want the gateway address to be in the status of the MCPServer in status.address.url instead of the service URL that is constructed by the upstream controller right now? Presumably we do not want to expose the service URL if we do not want users trying to connect to it directly

[aliok]

Feature-wise, this looks great. It is a wonderful integration.
+1 on Gordon's comment around separate field, if we can find a good way of doing that.
We might want to ask a review from the API review folks, when we want to proceed with that.

Implementation-wise, following is the idea, right?

• Upstream: we don't introduce this integration as Kuadrant gateway is not a standard
• Midstream/downstream: we maintain this additional controller in our fork

[matzew]

Upstream: we don't introduce this integration as Kuadrant gateway is not a standard

+1 on this specific implementation

Good point on the API reviewers, and perhaps we could think about some generic hook for "gateways" at large - e.g. like other projects had support for "service mesh", but not coming with a default integration of one particular.

Or maybe that is more for future - but IMO worth to consider

[jaideepr97]

@Cali0707 probably a good time to get back to this now that the upstream operator is in good shape!

[Cali0707]

@jaideepr97 I'm out at MCP Dev summit this week, will pick this back up next week 😄

[aliok]

FYI, started a thread around MCP Lifecycle operator AND MCP gateway(s) integration in upstream Kubernetes Slack: https://kubernetes.slack.com/archives/C09P6KS6EQZ/p1777284205197289

[aliok]

Folks,

I've started working on some designs for MCP gateway integrations. Created some Google docs, which I will share in the upstream issue: kubernetes-sigs#125

/hold

Please hold this as I have different ideas that could be more extensible.