AI导哈

OpenShift诊断服务

Must-Gather MCP服务器为AI助手提供全面的OpenShift must-gather数据访问，用于故障排除和诊断。

  • by Prashanth684
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 Prashanth684/must-gather-mcp-server

使用说明

必须收集MCP服务器

为AI助手提供对OpenShift全面访问的模型上下文协议（MCP）服务器必须收集数据以进行故障排除和诊断。

概述

必须收集的MCP服务器使AI助手能够通过必须收集的档案深入分析OpenShift集群，提供：

  • 完成集群配置和状态
  • 网络连接和性能数据
  • ETCD数据库运行状况和指标
  • 带有日志的Pod和节点诊断
  • 操作员状态和版本跟踪

特性

🚀 演出

  • 快速资源访问：对约11000个资源进行内存索引
  • 计划任务管理软件：加载和索引需要5-10秒
  • 快速查询：对于索引资源查找，<50ms
  • 按需日志：仅在请求时加载日志

🛠️ 工具类别（5个工具集中的62个工具）

组合工具集（28个工具）

版本和信息（6个工具）：

  • cluster_version_get -OpenShift版本、更新状态、功能
  • cluster_info_get -基础设施（平台、区域、拓扑、网络配置）
  • cluster_operators_list -所有处于可用/进展/降级状态的操作员
  • cluster_operator_get -详细的操作员条件、版本、相关对象
  • cluster_nodes_list -具有角色、状态、kubelet版本的节点
  • cluster_node_get -详细的节点信息（容量、条件、污染）

机器配置（4个工具）：

  • machineconfig_list -列出所有MachineConfig（操作系统和systemd配置）
  • machineconfig_get -获取详细的MachineConfig，包括点火配置
  • machineconfigpool_status -检查池降级并更新状态
  • machineconfignode_status -每个节点配置应用程序状态

存储（4个工具）：

  • storage_classes_list -列出带有配置项和默认值的StorageClass
  • csi_drivers_status -CSI驱动程序功能和状态
  • volume_attachments_list -查找卡住或失败的卷装载
  • persistent_volumes_status -PV状态（可用、绑定、失败）

安全和RBAC（2个工具）：

  • security_scc_list -SecurityContextConstraints与权限分析
  • rbac_clusterroles_list -具有危险权限检测的ClusterRoles

OLM/操作员（3个工具）：

  • olm_subscriptions_status -运营商订阅和升级状态
  • olm_catalogsources_status -目录源连接和运行状况
  • olm_installplans_status -等待操作员安装

准入控制（2个工具）：

  • admission_webhooks_list -验证和修改webhooks
  • admission_policies_list -基于CEL的录取政策

配置（2个工具）：

  • cluster_config_list -列出所有config.openshift.io资源
  • cluster_config_get -获取详细的集群配置

入口和路由（4个工具）：

  • routes_list -列出具有主机、服务、TLS配置和准入状态的OpenShift路由
  • route_get -获取详细的路由信息，包括后端权重和TLS终止
  • ingress_list -列出带有规则和后端的Kubernetes Ingress资源
  • ingresscontroller_status -获取IngressController（路由器）状态、副本和条件

核心工具集（6个工具）

资源（3个工具）：

  • resources_get -按种类/名称/命名空间获取任何Kubernetes资源
  • resources_list -使用标签/字段选择器列出资源
  • namespaces_list -列出所有命名空间

事件（3个工具）：

  • events_list -按类型/命名空间/原因筛选事件
  • events_timeline -事件分析的时序事件序列
  • events_by_resource -特定Pod/节点/部署的所有事件

诊断工具集（17个工具）

Pod日志（2个工具）：

  • pod_logs_get -带尾部支撑的集装箱日志（当前/以前）
  • pod_containers_list -发现带有日志的容器

节点诊断（4个工具）：

  • nodes_list -具有可用诊断数据的节点
  • node_diagnostics_get -全面的节点诊断（kubelet、sysinfo、CPU/IRQ、硬件）
  • node_kubelet_logs -Kubelet日志（从.gz自动解压缩）
  • node_kubelet_logs_grep -使用可选的不区分大小写的搜索按字符串过滤kubelet日志

扩展节点诊断（3个工具）：

  • node_hardware_info -CPU拓扑、PCI设备、网络接口
  • node_dmesg_errors -分析内核日志以查找错误、OOM终止、硬件问题
  • node_kernel_info -内核引导参数和配置

主机服务日志（3个工具）：

  • host_service_logs_list -列出systemd服务（kubelet、crio、NetworkManager等）
  • host_service_logs_get -通过尾部支持获取特定的服务日志
  • host_service_logs_grep -在所有主机服务日志中搜索

静态Pod（1个工具）：

  • static_pod_termination_logs -控制平面吊舱崩溃日志（kube-apiserver、etcd等）

ETCD（4个工具）：

  • etcd_health -群集运行状况、端点状态、警报
  • etcd_object_count -资源类型对象计数
  • etcd_members_list -成员ID、对等方/客户端URL
  • etcd_endpoint_status -数据库大小、配额使用情况、筏状态、领导者信息

网络工具集（3个工具）

  • network_scale_get -网络资源计数（服务、Pod、策略）
  • network_ovn_resources -OVN Kubernetes组件资源使用情况
  • network_connectivity_check -吊舱连接测试结果及故障分析

监控工具集（8个工具）

普罗米修斯核心健康：

  • monitoring_prometheus_status -带有TSDB统计信息和运行时信息的服务器状态
  • monitoring_prometheus_targets -使用健康过滤清除目标
  • monitoring_prometheus_tsdb -详细的TSDB统计数据，包括顶级指标和标签基数

警报和规则管理：

  • monitoring_alertmanager_status -AlertManager群集状态和版本信息
  • monitoring_prometheus_rules -记录和提醒健康状态规则
  • monitoring_prometheus_alerts -具有严重性过滤的活动警报

配置和发现：

  • monitoring_prometheus_config_summary -配置概述，包括抓取作业和全局设置
  • monitoring_servicemonitor_list -ServiceMonitor用于抓取目标发现的CRD列表

安装

来源

git clone <repository>
cd must-gather-mcp-server
make build

通过npm（发布时）

npx must-gather-mcp-server@latest --must-gather-path /path/to/must-gather

通过Python（发布时）

uvx must-gather-mcp-server --must-gather-path /path/to/must-gather

用法

STDIO模式（默认）

用于Claude Desktop、MCP Inspector和其他使用STDIO的MCP客户端：

./must-gather-mcp-server --must-gather-path /path/to/must-gather

使用克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）：

{
  "mcpServers": {
    "must-gather": {
      "command": "/path/to/must-gather-mcp-server",
      "args": ["--must-gather-path", "/path/to/your/must-gather"]
    }
  }
}

与MCP检查员一起

npx @modelcontextprotocol/inspector@latest ./must-gather-mcp-server \
  --must-gather-path /path/to/must-gather

HTTP/SSE模式

用于Goose或其他基于HTTP的MCP客户端等代理：

./must-gather-mcp-server \
  --must-gather-path /path/to/must-gather \
  --http \
  --http-addr localhost:8080

服务器将于启动 http://localhost:8080 SSE端点位于 http://localhost:8080/sse.

与鹅

配置Goose以连接到HTTP端点：

# goose config
mcp_servers:
  must-gather:
    url: http://localhost:8080/sse

然后启动Goose，它将连接到MCP服务器。

命令行选项

Flags:
  --must-gather-path string    Path to must-gather directory (required)
  --http                       Run in HTTP/SSE mode instead of STDIO
  --port string                HTTP server port (replaces deprecated --http-addr)
  --http-addr string           HTTP server address (deprecated, use --port)

  --config string              Path to configuration file
  --config-dir string          Path to drop-in configuration directory

  --log-level int              Log verbosity level (0-9)

  --require-oauth              Require OAuth authentication
  --oauth-audience string      OAuth audience for token validation
  --authorization-url string   OIDC authorization server URL

  --version                    Show version information
  -h, --help                   help for must-gather-mcp-server

有关完整的配置选项，请参阅 身份验证指南.

查询示例

聚类分析

  • “此集群运行的是哪个版本的OpenShift？”
  • “显示所有降级的群集运算符”
  • “列出所有主节点及其状态”
  • “这个集群在哪个平台上，在哪个地区？”

机器配置

  • “显示所有MachineConfigPools及其状态”
  • “是否有任何节点因计算机配置问题而降级？”
  • “哪些MachineConfig应用于工作节点？”

存储故障排除

  • “哪个是默认的StorageClass？”
  • “显示所有失败的卷附件”
  • “列出所有处于失败状态的持久卷”
  • “群集中有哪些CSI驱动程序可用？”

安全和RBAC

  • “哪些SecurityContextConstraints允许特权容器？”
  • “显示具有通配符权限的ClusterRoles”
  • “列出所有有权访问特权SCC的用户”

操作员生命周期（OLM）

  • “是否有任何运营商订阅处于UpgradeFailed状态？”
  • “显示需要批准的待定安装计划”
  • “认证运营商目录来源是否健康？”

事件和事件

  • “显示最近一小时的所有警告事件”
  • “X舱发生了什么事？”
  • “过去2小时命名空间Y的事件时间表”
  • 查找所有原因为“回退”或“失败”的事件

ETCD监控

  • “检查ETCD群集运行状况”
  • “ETCD数据库大小和配额使用情况如何？”
  • “ETCD集群中是否存在筏板滞后？”
  • “列出所有ETCD成员”

网络故障排除

  • “显示所有失败的网络连接检查”
  • “这个集群的网络规模是多少？”
  • “哪些OVN组件使用的资源最多？”

Pod和节点诊断

  • “获取命名空间Y中pod X的日志”
  • “显示节点Z的kubelet日志”
  • “按'error'字符串过滤节点Z的kubelet日志”
  • “在所有节点的kubelet日志中搜索'OOM'”
  • “列出所有具有诊断数据的节点”
  • “获取节点A的全面诊断”

扩展节点诊断

  • 显示节点X的硬件信息（CPU、PCI设备）
  • “在所有节点上分析dmesg的错误和OOM终止”
  • “节点Y的内核引导参数是什么？”

主机级调试

  • “列出所有主机系统服务日志”
  • “显示最后100行的crio服务日志”
  • “在所有主机服务日志中搜索'error'”

控制平面调试

  • “显示主-0的kube-apiserver终止日志”
  • “有任何控制飞机吊舱坠毁吗？”

准入控制

  • “列出所有验证和变异的Webhook”
  • “配置了哪些准入政策？”

配置

  • “列出所有群集配置资源”
  • “显示OAuth配置”
  • “启用了哪些功能门？”

入口和路线

  • “列出所有显示其入场状态的路线”
  • “显示命名空间Y中路由X的详细信息”
  • “默认IngressController的状态是什么？”
  • “列出所有具有TLS边缘终止的路由”
  • “是否有Kubernetes Ingress资源？”

监测和可观察性

  • “普罗米修斯服务器状态和TSDB统计数据是什么？”
  • “显示所有失败的普罗米修斯刮靶”
  • “列出当前正在触发的所有关键警报”
  • “按系列计数，最重要的指标是什么？”
  • “显示AlertManager群集状态”
  • “列出群集中的所有ServiceMonitors”
  • “配置了哪些警报规则？”

建筑

需求

  • 转到1.25或更高版本
  • 制造

构建命令

# Build for current platform
make build

# Build for all platforms
make build-all-platforms

# Run tests
make test

# Run linter
make lint

# Format code
make fmt

建筑

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                               │
│                  (Claude Desktop, Goose, etc.)                  │
└────────────────────────────┬────────────────────────────────────┘
                             │ MCP Protocol
                             │ (STDIO or HTTP/SSE)
┌────────────────────────────▼────────────────────────────────────┐
│                   Must-Gather MCP Server                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              62 MCP Tools (5 Toolsets)                   │   │
│  │  Cluster | Core | Diagnostics | Network | Monitoring    │   │
│  └─────────────────────┬────────────────────────────────────┘   │
│                        │                                         │
│  ┌─────────────────────▼──────────────┬──────────────────────┐  │
│  │    In-Memory Index                 │  On-Demand Files     │  │
│  │  • ~11k YAML resources             │  • Pod logs          │  │
│  │  • GVK, namespace, labels          │  • Node diagnostics  │  │
│  │  • <50ms lookups                   │  • ETCD metrics      │  │
│  └────────────────────────────────────┴──────────────────────┘  │
└────────────────────────────┬────────────────────────────────────┘
                             │
┌────────────────────────────▼────────────────────────────────────┐
│                   Must-Gather Archive                           │
│  cluster-scoped-resources/ | namespaces/ | nodes/ | etcd_info/  │
│  network_logs/ | pod_network_connectivity_check/ | monitoring/  │
└─────────────────────────────────────────────────────────────────┘

数据加载

  1. 初创公司：从集群范围的资源/和命名空间加载YAML资源/
  2. 索引：根据GVK、命名空间和标签构建内存索引（~5-10s）
  3. 查询：使用索引数据快速查找（<50ms）
  4. 日志：调用工具时按需加载（未编入索引）

目录结构

must-gather/
├── quay-io-okd-scos-content-sha256-.../ (container directory)
│   ├── cluster-scoped-resources/      # Cluster-wide resources
│   │   ├── config.openshift.io/       # Cluster config, operators, version
│   │   └── core/                      # Nodes, PVs
│   ├── namespaces/                    # Namespaced resources
│   │   └── {namespace}/
│   │       ├── core/                  # Pods, services, etc.
│   │       └── pods/                  # Pod logs
│   ├── nodes/                         # Node diagnostics
│   ├── etcd_info/                     # ETCD health and metrics
│   ├── network_logs/                  # Network scale and OVN metrics
│   ├── pod_network_connectivity_check/ # Connectivity test results
│   └── monitoring/                    # Prometheus and AlertManager data
│       ├── alertmanager/              # AlertManager status
│       ├── prometheus/                # Prometheus metrics and configuration
│       │   ├── prometheus-k8s-0/      # Replica 0 (targets, TSDB stats)
│       │   ├── prometheus-k8s-1/      # Replica 1 (targets, TSDB stats)
│       │   ├── rules.json             # Alerting and recording rules
│       │   └── status/                # Shared configuration and flags
│       └── servicemonitors/           # ServiceMonitor CRDs

工具类别

索引资源 （快速查询）：

  • 集群资源（运营商、版本、基础设施、节点）
  • 核心资源（Pod、服务、配置映射等）
  • 所有Kubernetes/OOpenShift API资源

按需数据 （从文件中读取）：

  • Pod容器日志
  • 节点诊断（kubelet日志、sysinfo、硬件信息）
  • ETCD详细状态
  • 网络连接检查

文档

演出

初创公司

  • 加载时间：11000个资源约5-10秒
  • 索引时间：~2-3秒
  • 内存使用量：~100-200MB（取决于集群大小）

查询性能

  • 索引查询：<50ms
  • 日志检索：<500ms（大多数情况下）
  • Kubelet日志解压：<1s（371K.gz文件）

故障排除

必须收集但未找到

Error: must-gather path does not exist: /path

解决方案：验证路径指向提取的必须收集的目录（而不是.tar文件）。

未找到容器目录

加载器自动检测容器目录（通常命名为 quay-io-okd-scos-content-sha256-...).如果失败，请检查必须收集的数据是否已正确提取。

缺少工具

Registered 0 toolsets

解决方案：确保工具集导入存在于 cmd/must-gather-mcp-server/cmd/root.go.

贡献

欢迎投稿！请确保：

  • 代码格式为 make fmt
  • 测试通过 make test
  • 林特尔与 make lint
  • 文档已针对新功能进行了更新

许可证

Apache许可证2.0

版本

跑 ./must-gather-mcp-server --version 查看版本信息。

相关 MCP