AI导哈

Kubernetes MCP操作符

一个用于在Kubernetes集群中部署、观察和保护MCP（模型上下文协议）组件的操作符，支持自定义资源定义和控制器逻辑。

  • by repolhomp3
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 repolhomp3/k8s-mcp-operator

使用说明

MCP操作员项目指南

欢迎！本仓库将引导您构建一个Kubernetes Operator，该Operator将Model Context Protocol（MCP）组件视为一等工作负载。其目标是让部署、监控和保护集群中的MCP服务器、工具和代理变得简单易行，即使您对Kubernetes Operator是新手也没关系。

目录

  1. 为什么要在 Kubernetes 上使用 MCP？
  2. 项目概述
  3. 在这个仓库中你能获得什么
  4. 关键概念解析
  5. 先决条件
  6. 快速入门：运行MVP Operator
  7. 探索自定义资源
  8. 控制器的工作原理
  9. 自定义您的部署
  10. 测试与故障排除
  11. 路线图及后续步骤
  12. 有用资源与术语表

为什么要在 Kubernetes 上使用 MCP？

模型上下文协议（MCP） 这是一个新兴的标准，它允许大型语言模型（LLM）代理以结构化的方式与外部工具、数据存储和服务进行交互。目前，团队会临时部署MCP服务器，这导致：

  • 手工编写的YAML部署，模式不一致。
  • 脆弱的秘密处理与身份管理。
  • 稀疏可观测性和状态报告。

A. Kubernetes Operator（中文可译为“Kubernetes 操作器”或根据具体语境简化为“K8s 操作器”） 将所有这些逻辑编码化。操作员监控自定义资源，并持续地将其协调为实际的集群对象（如Deployment、Service、ConfigMap、Secret等）。这使得平台、安全和应用团队能够以声明式的方式管理MCP基础设施，就像我们管理原生Kubernetes工作负载一样。

项目概述

这个项目提供：

  • 自定义资源定义（CRDs） 对于三个MCP构建模块：服务器、工具和代理。
  • 一个最小化的Python/Kopf控制器 使（两者）和解/调和 MCPServer 将资源部署到服务中，然后报告状态。
  • 示例清单和脚本 这样你就可以立即进行实验并理解操作流程。
  • 一份详细的蓝图 捕获安全态势、生产路线图以及迁移到Go/Kubebuilder实现的路径。

当前的MVP（最有价值球员）专注于 MCPServer 和解。用于……的工具 MCPTool 和 MCPAgent 进行了描述并为未来的迭代提供了框架支持。

在这个仓库中你将获得什么

  • docs – 设计蓝图，阐述目标、架构、自定义资源定义（CRDs）、安全态势及路线图。
  • controller/ – Python 控制器代码（controller/mcp_operator.py:1) 使用Kopf和Kubernetes Python客户端。
  • config/crds/ – MCP资源的CRD YAML文件，外加一个 kustomization.yaml 如果你更喜欢 kubectl apply -k。
  • config/rbac/ – 运行集群内的操作符（operator）所需的命名空间（Namespace）、服务账户（ServiceAccount）、集群角色（ClusterRole）和集群角色绑定（ClusterRoleBinding）。
  • config/samples/ – 在安装自定义资源定义（CRDs）后，尝试使用最少的MCPServer、MCPTool和MCPAgent自定义资源。
  • examples/dev-stack.yaml – 一个单一清单文件，用于设置密钥、配置映射以及示例MCP资源，以构建一个开箱即用的演示环境。
  • requirements.txt / Makefile – 依赖项锁定以及用于安装、运行和检查控制器的辅助目标。

关键概念解析

概念 在此处的含义 哪里可以看到
MCP 服务器 向代理暴露 MCP 功能的后端进程。与 Deployment + Service 进行协调。 config/crds/mcpservers.yaml:1， config/samples/mcpserver.yaml:1
MCP工具：描述MCP服务器可以连接的外部工具（HTTP API、数据库等） config/crds/mcptools.yaml:1， config/samples/mcptool.yaml:1
MCP Agent 将服务器和工具绑定成可运行的代理Pod，以协调交互。（计划中的协调器。） config/crds/mcpagents.yaml:1， config/samples/mcpagent.yaml:1
操作符 一个监控自定义资源并应用更改以达到期望状态的控制器。 controller/mcp_operator.py:1
Kopf 用于快速编写Kubernetes操作符的Python框架。 kopf.readthedocs.io（可译为：“Kopf项目的官方文档网站”，其中“Kopf”可能是一个特定项目或库的名称，而“.readthedocs.io”是用于托管项目文档的常见域名后缀，类似于“readthedocs.org”）

先决条件

在开始之前：

  • 一个Kubernetes集群（使用kind、minikube、k3d或托管集群均可）。
  • kubectl 配置为指向该集群。
  • Python 3.9+（用于控制器）。建议使用虚拟环境。
  • （可选） kustomize 如果你使用独立版 kubectl apply -k。

如果你是Kubernetes的新手，先快速浏览一下 概念概述 了解部署（Deployments）、服务（Services）、Pod以及基于角色的访问控制（RBAC）。

快速入门：运行MVP操作符

  1. 克隆仓库 并进入该目录。

    git clone https://github.com/your-org/mcp-operator.git
cd mcp-operator

  2. 创建一个独立的Python环境 并安装依赖项。

    python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

  3. 安装CRDs（自定义资源定义） 这样，Kubernetes 就能理解新的资源类型。

    kubectl apply -k config/crds

    确认他们已注册：

    kubectl get crd | grep mcp.operator

  4. 安装RBAC资产 (命名空间，服务账户，集群角色，绑定)。

    kubectl apply -k config/rbac

  5. 在本地运行操作符 （这会使用您的 kubeconfig 文件与集群进行通信）。

    make run

    你应该看到Kopf的日志输出，表明操作员正在监控 MCPServer 资源。

  6. 应用样本资源 在另一个终端中。

    kubectl apply -k config/samples
# or use the richer example:
kubectl apply -f examples/dev-stack.yaml

  7. 检查状态。

    kubectl get mcpservers -n mcp-system
kubectl describe mcpserver demo-server -n mcp-system
kubectl get pods -n mcp-system

就是这样——你正在运行MVP操作符！示例MCPServer现在会持续地在内部被调整为Deployment和Service mcp-system 命名空间。

探索自定义资源

MCPServer（config/crds/mcpservers.yaml:1）

您可以设置的关键字段：

  • spec.imageMCP服务器的容器镜像（必需）。
  • spec.replicas期望的副本数量（默认为1）。
  • spec.portMCP服务器暴露的容器端口。
  • spec.env环境变量，包括可选的 valueFrom 秘密参考。
  • spec.config要么是内联JSON（会为您转换为ConfigMap），要么是现有ConfigMap的引用。
  • spec.secretRefs要挂载的密钥名称；控制器将每个密钥映射到一个卷。
  • spec.podSecurity像这样的属性 serviceAccountName， runAsNonRoot，以及 seccompProfile。
  • spec.resources标准的 Kubernetes 请求/限制字典。

状态字段（status.phase， status.conditions， status.endpoint) 由控制器进行更新，以便您能够与GitOps或仪表板集成。

MCPTool（config/crds/mcptools.yaml:1）

尽管控制器目前还不能对工具进行操作，但CRD允许团队注册元数据：

  • spec.type工具类别（http， postgres等）。
  • spec.endpoint工具所在的位置。
  • spec.auth.secretRef包含凭据的秘密。
  • spec.schema内联规范或参考说明，描述预期的输入/输出。

MCPAgent（config/crds/mcpagents.yaml:1）

设计用于在代理自动化实现后进行未来的对账：

  • spec.serverRef指示代理应使用的MCPServer。
  • spec.tools工具引用的数组（默认情况下处于同一命名空间）。
  • spec.scaling基本的自动扩展提示（最小/最大副本数，CPU目标）。
  • spec.rollout策略旋钮映射部署策略。
  • spec.runtime额外的环境变量和资源预算。

即使在合并工具存在之前，这些定义也为平台团队提供了一种一致的方式来在Git中捕捉意图。

控制器的工作原理

核心逻辑存在于 controller/mcp_operator.py:1以下是高级流程概述：

  1. 配置加载 – 控制器尝试加载集群内的配置，若从笔记本电脑运行则回退到本地kubeconfig文件。
  2. “Kopf handlers”可以翻译为“头部操作员”或“头部处理人员”，具体取决于上下文和行业术语的习惯用法。在某些领域，如机械维修、制造业或特定的工业流程中，这个术语可能指的是负责处理或操作头部部件的工作人员。 – 装饰器（@kopf.on.create， @kopf.on.update， @kopf.timer为MCPServer事件和定期状态检查注册回调函数。
  3. 期望状态合成 – 当一个新的MCPServer出现时，控制器会构建：
    • 一个用于MCP服务器容器的部署（包含环境变量、密钥、配置卷、安全上下文）。
    • 一个在请求的端口上暴露部署的服务。
    • 如果你提供，就是一个内联的ConfigMap spec.config.inline。
  4. 申请或更新 – 控制器创建资源，如果资源已存在，则对其进行修补。
  5. 状态报告 – 每30秒，它会检查部署的就绪状态，并更新MCPServer的状态，包括阶段、条件以及一个内部终端URL。

因为控制器总是会调整以符合期望的规格，所以您可以放心地修改MCPServer的YAML文件，操作符将会滚动更新Deployment以使其匹配。

自定义您的部署

一旦快速入门成功运行，请根据您的需求调整YAML文件：

  • 交换 spec.image 用于您自己的MCP服务器构建。
  • 添加在（此处）引用的机密信息 spec.secretRefs 注入API密钥或TLS证书。
  • 使用 spec.config.configMapRef 链接到外部管理的配置。
  • 调整 spec.podSecurity.serviceAccountName 用于IAM角色（在EKS上的IRSA，GKE上的Workload Identity等）。
  • 修改示例 config/samples/mcptool.yaml:1 并且 config/samples/mcpagent.yaml:1 以反映真实的工具/代理。即使没有协调器，这些自定义资源（CRs）也可以记录依赖关系。
  • 将这些资源整合到Git仓库中，以便GitOps工具（如ArgoCD、Flux）能够自动应用它们。

测试与故障排除

  • 运行控制器并启用详细日志：
    KOPF_LOGLEVEL=DEBUG make run
  • 检查事件 由操作员发出：
    kubectl get events --sort-by=.metadata.creationTimestamp -n mcp-system
  • 检查生成的Deployment/Service 验证标签和数量：
    kubectl get deploy demo-server -n mcp-system -o yaml
kubectl get svc demo-server-svc -n mcp-system -o yaml
  • 常见问题：
    • 镜像拉取错误确保镜像可访问，并在需要时配置镜像拉取密钥（imagePullSecrets）。
    • 秘密未找到在应用MCPServer之前，请先创建引用的密钥。
    • *状态卡在“待处理”*跑 kubectl describe deployment 查看为何Pod未就绪（探测失败、配置缺失等）。
    • 权限被拒绝确保你已经申请了 config/rbac/operator-rbac.yaml:1 并且操作员进程正在使用 mcp-operator 服务账户。

在受限环境中进行Python字节码编译时，请使用：

PYTHONPYCACHEPREFIX=.pycache python3 -m py_compile controller/mcp_operator.py

路线图及后续步骤

长期愿景（概述于 docs:1）包括：

  1. 全面重写为Go/Kubebuilder – 获取准入webhooks、类型化客户端、领导者选举以及更强大的测试功能。
  2. MCPTool 和 MCPAgent 一致性检查器 – 自动连接工具和代理，应用网络策略，并传播凭据。
  3. 操作强化 – 水平Pod自动扩缩器、Pod干扰预算、Prometheus指标、结构化日志。
  4. 渐进式交付 – 金丝雀发布和蓝绿部署策略，Argo Rollouts集成，以及使用Gatekeeper/Kyverno进行策略强制执行。
  5. 多租户（架构） – 工作区隔离、团队级基于角色的访问控制（RBAC）框架、资源配额。
  6. 联合会 – 使用GitOps覆盖层或Cluster API管理跨集群的MCP部署。

欢迎社区贡献——请查看问题列表或提出与蓝图相符的增强建议。

有用资源及术语表

  • Kubernetes Operator 基础知识 – 操作符模式介绍.
  • Kopf 文档 – 框架使用指南.
  • 模型上下文协议 – OpenAI的公告和MCP（模型上下文协议）规范（搜索“Model Context Protocol OpenAI”以获取最新参考）。
  • 术语表：
    • CRD（Customer Relationship Development，客户关系发展） – CustomResourceDefinition，一种模式扩展，使Kubernetes能够接受自定义对象。
    • “Reconciler”可以翻译为“协调者”或“和解者”，具体取决于上下文和语境。在金融或会计领域，它可能指的是负责核对账目、确保账目一致的人或系统；在更广泛的语境中，它可以指任何负责协调、调解或解决冲突的人 – 运算符内部的循环，用于将实际状态驱动至期望状态。
    • 服务账户 – Pods用于与Kubernetes API或云提供商通信的身份。
    • 内联配置 – 配置直接嵌入到MCPServer规范中，由控制器转换为ConfigMap。

按照本README文件的指导，您应该能够：

  1. 了解MCP操作员的职责。
  2. 安装并观察MVP控制器。
  3. 尝试MCPServer的规范，并为未来版本中更丰富的工具做好准备。

祝建设顺利，欢迎根据所收录的设计指南对操作符进行迭代改进 docs。

相关 MCP