From b1bf8908f1b7091fabf88edc5cbdad7b5b8ee1d5 Mon Sep 17 00:00:00 2001 From: arkadeepsen Date: Fri, 8 May 2026 15:09:40 +0530 Subject: [PATCH] Add enhancement proposal to productize ovn-kubernetes MCP tools --- ...n-kubernetes-ocp-mcp-server-integration.md | 194 ++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 enhancements/network/ovn-kubernetes-ocp-mcp-server-integration.md diff --git a/enhancements/network/ovn-kubernetes-ocp-mcp-server-integration.md b/enhancements/network/ovn-kubernetes-ocp-mcp-server-integration.md new file mode 100644 index 0000000000..aff5f48e27 --- /dev/null +++ b/enhancements/network/ovn-kubernetes-ocp-mcp-server-integration.md @@ -0,0 +1,194 @@ +--- +title: ovn-kubernetes-ocp-mcp-server-integration +authors: + - "@arkadeepsen" +reviewers: + - "@tssurya, OVN-Kubernetes networking ownership and OVN/OVS troubleshooting tool semantics" + - "@Cali0707, integration implementation in kubernetes-mcp-server and downstream productization path" + - "@matzew, integration implementation in kubernetes-mcp-server and downstream productization path" +approvers: + - "@tssurya" +api-approvers: + - "None" +creation-date: 2026-05-08 +last-updated: 2026-05-08 +status: provisional +tracking-link: + - https://redhat.atlassian.net/browse/CORENET-7091 +see-also: + - https://github.com/ovn-kubernetes/ovn-kubernetes-mcp + - https://github.com/containers/kubernetes-mcp-server + - https://github.com/openshift/openshift-mcp-server +replaces: + - NA +superseded-by: + - NA +--- + +# OVN-Kubernetes MCP tools in OpenShift MCP server + +## Summary + +This enhancement proposes making the already-implemented OVN-Kubernetes MCP tools from [ovn-kubernetes-mcp](https://github.com/ovn-kubernetes/ovn-kubernetes-mcp) available via upstream [kubernetes-mcp-server](https://github.com/containers/kubernetes-mcp-server), so they can be **productized downstream** through the normal sync into [openshift-mcp-server](https://github.com/openshift/openshift-mcp-server). The intent is to reuse upstream OVN troubleshooting tools in OpenShift by integrating them into kubernetes-mcp-server, rather than re-implementing equivalent functionality downstream. + +## Motivation + +OVN-Kubernetes operators and support engineers often need Northbound and Southbound database views (`ovn-nbctl`, `ovn-sbctl`, traces, logical flows) while investigating connectivity and routing. These tools are already implemented in ovn-kubernetes-mcp, but OpenShift users benefit from consuming them via a **single MCP server** that shares authentication, tool governance, and documentation with the rest of the platform troubleshooting surface. + +The primary motivation for landing these tools in upstream kubernetes-mcp-server is **productization via downstream sync into openshift-mcp-server**. By first integrating the OVN toolset upstream, OpenShift can ship and support the same upstream code through the established downstream pipeline. + +### User Stories + +- As a cluster administrator or platform engineer, I want to run OVN logical database inspection tools through the same MCP server I already use for Kubernetes resources, so that I do not deploy or credential a separate MCP process for OVN-Kubernetes alone. +- As a support engineer, I want NB/SB “show” style output (and later `get`, `lflow-list`, `trace`) via MCP-aware clients, so that assisted troubleshooting matches how other cluster operations are automated. +- As an OpenShift contributor, I want OVN-specific MCP logic to live in the ovn-kubernetes-mcp repository as reusable packages, so that behavior stays aligned with the upstream OVN-Kubernetes community. + +### Goals + +- Add an `ovn-kubernetes` toolset to kubernetes-mcp-server that reuses the existing OVN MCP tool implementations from ovn-kubernetes-mcp, rather than re-implementing equivalent functionality. +- Enable kubernetes-mcp-server to execute OVN tool commands in-cluster using its existing pod-exec capabilities, with only minor upstream refactoring required in the imported OVN tools. +- Import the OVN and OVS layers from ovn-kubernetes-mcp incrementally (starting with core OVN/OVS troubleshooting tools), expanding coverage as dependencies and eval coverage mature. +- Make the toolset available to OpenShift users through openshift-mcp-server via downstream sync from kubernetes-mcp-server. + +### Non-Goals + +- Full parity in the first iteration with every tool category shipped by the standalone ovn-kubernetes-mcp binary (for example kernel diagnostics, optional images such as pwru/tcpdump, must-gather, sosreport) where those require separate dependencies, images, or workflows. +- New Kubernetes or OpenShift APIs, CRDs, operators, or cluster-side agents solely for this feature. +- Replacing existing CLI-based troubleshooting; MCP tools are an additional interface. +- Importing ovn-kubernetes-mcp tools under `kernel` and `network-tools` packages in the first iteration, since those tools depend on a node debugging capability (for example a node-debug tool) that is not currently available in kubernetes-mcp-server. + +## Proposal + +### Workflow Description + +1. An operator configures MCP clients (for example Cursor, other MCP hosts) to use openshift-mcp-server or kubernetes-mcp-server with a kubeconfig that can reach the target cluster and satisfies RBAC for pod read and pod exec where policies allow. +2. The user or automated agent invokes OVN/OVS troubleshooting tools with the Kubernetes namespace and name of a pod that runs OVN utilities (for example an `ovnkube-node` pod), and selects the desired database or command parameters (for example `nbdb` or `sbdb` where applicable). +3. The toolset handler invokes the imported OVN/OVS tool implementation and delegates in-cluster command execution to kubernetes-mcp-server’s existing pod-exec capability. +4. The server runs the appropriate `ovn-nbctl` / `ovn-sbctl` / `ovs-*` command inside the target pod; stdout/stderr are returned through the MCP tool response. +5. Results are returned to the MCP client as structured or textual output according to the tool schema. + +### API Extensions + +None. This work adds MCP tools only and does not extend the OpenShift or Kubernetes API surface. + +### Topology Considerations + +#### Hypershift / Hosted Control Planes + +The MCP server uses whatever cluster the kubeconfig targets. For HyperShift, that is typically the **hosted cluster** API when troubleshooting workload networking; there is no change to management-plane APIs. Operators must select the correct context (management versus guest) the same way they would for `kubectl exec`. + +#### Standalone Clusters + +Fully relevant: tools execute against pods on the same cluster the API client reaches. + +#### Single-node Deployments or MicroShift + +Relevant wherever OVN-Kubernetes runs and the user can identify a suitable pod; resource footprint is limited to occasional exec sessions initiated by MCP clients. MicroShift applicability follows whether openshift-mcp-server or kubernetes-mcp-server is supported for that distribution (product-specific packaging is outside this design). + +#### OpenShift Kubernetes Engine + +No dependency on OCP-only APIs for the initial import. Tool availability still depends on shipping openshift-mcp-server builds that include the synced toolset and on RBAC policy configured by the operator. + +### Implementation Details/Notes/Constraints + +**Importing upstream tools into kubernetes-mcp-server.** The OVN troubleshooting MCP tools already exist in ovn-kubernetes-mcp. The integration approach for kubernetes-mcp-server is to add an `ovn-kubernetes` toolset that reuses those implementations as imported packages and exposes them through kubernetes-mcp-server’s tool registration. + +**Command execution strategy.** Since the OVN tools need to run commands inside OVN-Kubernetes pods, the imported OVN tool implementation should be able to delegate “run this command in this pod” to the host server. This is expected to require only minor refactoring in ovn-kubernetes-mcp so command execution uses kubernetes-mcp-server’s pod-exec path rather than opening independent Kubernetes exec connections from the imported library. + +```mermaid +flowchart LR + subgraph upstreamLib [ovn-kubernetes-mcp] + OVNLogic[imported_OVN_OVS_tool_logic] + ExecDelegation[delegated_in_cluster_execution] + OVNLogic --> ExecDelegation + end + subgraph kms [kubernetes-mcp-server] + ToolHandler[ovn_kubernetes_tool_handlers] + HostPodExec[host_pod_exec] + ToolHandler --> HostPodExec + HostPodExec -.->|supplies| ExecDelegation + end + subgraph downstream [openshift-mcp-server] + Sync[Downstream_sync] + end + kms --> Sync +``` + +**Downstream.** openshift-mcp-server consumes kubernetes-mcp-server changes through its normal fork sync or vendor workflow (exact mechanics follow that repository’s documented process). + +### Risks and Mitigations + +- **RBAC and privilege:** Pod exec is sensitive. Mitigation: reuse kubernetes-mcp-server permission models for `pods/exec` and document required roles; keep tools read-only where possible. +- **Data sensitivity:** OVN database dumps can expose topology and workloads. Mitigation: treat tool output like other diagnostic data; warn in tool descriptions; rely on cluster RBAC and MCP deployment guidance. +- **Wrong pod or namespace:** Users may target non-OVN pods. Mitigation: clear parameter descriptions; surface stderr from exec failures. + +### Drawbacks + +- Requires maintaining a dependency from kubernetes-mcp-server on ovn-kubernetes-mcp (version alignment and API stability). +- Downstream sync latency means OpenShift may trail upstream kubernetes-mcp-server slightly unless backports are requested. + +## Alternatives (Not Implemented) + +- **Fork OVN tool logic into openshift-mcp-server only:** Rejected because it duplicates effort and diverges from upstream ovn-kubernetes-mcp. +- **Keep only the standalone ovn-kubernetes-mcp binary for OpenShift:** Rejected because it splits credentials, RBAC documentation, and user experience from the unified MCP server. +- **Have ovn-kubernetes-mcp open its own REST/exec connections inside kubernetes-mcp-server:** Rejected because it duplicates kubernetes-mcp-server’s pod execution behavior and splits security review surfaces. + +## Open Questions + +- Which additional OVN/OVS tools to import next, and in what order, given RBAC and support expectations? +- Whether openshift-mcp-server needs product-specific enablement flags or documentation for clusters where pod exec is restricted. + +## Test Plan + +- **Unit tests:** Ensure OVN/OVS tool implementations can be exercised without requiring a live cluster (for example by substituting test doubles for in-cluster command execution and validating command construction and output handling). +- **Integration:** Validate the `ovn-kubernetes` toolset end to end in kubernetes-mcp-server using the same pod-exec pathways as other tools, and ensure tool output is returned correctly. +- **Manual:** Run MCP tool calls against a cluster with OVN-Kubernetes installed, verifying OVN/OVS command output for a known `ovnkube-node` pod. + +### Tool acceptance mechanism (mcpchecker evals) + +kubernetes-mcp-server uses the [mcpchecker](https://github.com/mcpchecker/mcpchecker) framework to evaluate toolset behavior via scenario tasks stored under `evals/tasks/**` (for example, `evals/tasks/tekton/**`). Task selection is suite-based using labels (for example `metadata.labels.suite: tekton`), and the CI workflow runs mcpchecker with a `label-selector` per suite. The current CI gate in kubernetes-mcp-server is configured to require **at least 80% task pass rate and 80% assertion pass rate** (see `.github/workflows/mcpchecker.yaml` thresholds). + +For OVN-Kubernetes tool acceptance, we will add a dedicated suite (for example `suite: ovn-kubernetes`) with tasks that exercise imported OVN/OVS tools against a cluster where OVN-Kubernetes is present. + +## Graduation Criteria + +Not tied to a specific OpenShift release in this draft. When promoted toward a release, expectations should include end-to-end verification on representative topologies, documented RBAC for administrators, and agreement on the supported tool list. + +### Dev Preview -> Tech Preview + +- Imported OVN/OVS tools usable end to end against OVN-Kubernetes clusters. +- Clear documentation for namespace/pod selection and permissions. +- mcpchecker evaluation pass rate meets **≥ 80%** for task pass rate (and assertions), aligning with the current kubernetes-mcp-server CI gate. + +### Tech Preview -> GA + +- Broader tool coverage agreed with networking and support stakeholders. +- Sufficient soak time and feedback; openshift-docs updates if the feature is user-facing in product documentation. +- mcpchecker evaluation pass rate meets **≥ 95%** for task pass rate (and assertions) for the `ovn-kubernetes` suite. +- The OVN-Kubernetes eval suite is stable across representative topologies and does not regress existing suites (diff vs baseline tracked in `evals/results/*-latest.json` in kubernetes-mcp-server). + +### Removing a deprecated feature + +- Announce deprecation of overlapping standalone-only workflows if any are superseded; maintain compatibility until a documented removal release. + +## Upgrade / Downgrade Strategy + +No cluster upgrade steps are required: changes are confined to MCP server binaries and their dependencies. Upgrading or downgrading the MCP server image or package restores previous tool availability if the toolset is absent in an older build. + +## Version Skew Strategy + +The MCP server and Kubernetes API must remain compatible for pod get/exec Subresources as today. No coordinated kubelet or CNI version skew beyond ordinary Kubernetes expectations. + +## Operational Aspects of API Extensions + +Not applicable. There are no CRDs, admission webhooks, aggregated API servers, or finalizers introduced by this enhancement. + +## Support Procedures + +- **Symptoms:** Tool errors such as `Forbidden` or `cannot exec into a container` indicate RBAC or pod state issues; verify RoleBindings for `pods/exec` and that the target pod is running. +- **Logs:** API server audit logs may record exec attempts according to cluster policy; MCP server logs may surface handler errors. +- **Disable:** Disable or unregister the `ovn-kubernetes` toolset in MCP deployment configuration (exact mechanism depends on openshift-mcp-server packaging); no cluster-side toggle is defined here. + +## Infrastructure Needed [optional] + +Coordination across [ovn-kubernetes-mcp](https://github.com/ovn-kubernetes/ovn-kubernetes-mcp), [kubernetes-mcp-server](https://github.com/containers/kubernetes-mcp-server), and [openshift/openshift-mcp-server](https://github.com/openshift/openshift-mcp-server) for reviews and downstream sync timing.