MCP Kubernetes Ro

🚀 Kubernetes只读MCP服务器

mcp-kubernetes-ro 是一个 模型上下文协议（MCP） 服务器，它为AI助手提供对Kubernetes集群的只读访问权限。借助该服务器，AI模型能够列出资源、获取资源详情、检索Pod日志、发现API资源，并执行Base64编码/解码操作，同时通过只读访问来保障安全性。

服务器利用你本地的 kubectl 配置（即便未安装 kubectl 也能使用），为你的Kubernetes集群提供一个安全的只读接口，在允许对集群进行全面检查和故障排除的同时，防止任何破坏性操作。

✨ 主要特性

• 无需安装 kubectl：MCP服务器使用你本地的 kubectl 配置来连接Kubernetes集群，但不依赖 kubectl 二进制文件，因此即使你的机器上未安装 kubectl，它也能正常工作。
• 资源列表：可按类型列出任何Kubernetes资源，并可选择通过标签、字段和命名空间进行过滤。
• 资源详情：获取特定Kubernetes资源的完整详细信息。
• Pod日志：通过高级过滤选项（包括grep模式、时间过滤和上一次日志）检索Pod日志。
• 容器发现：列出Pod内的容器，以便有针对性地访问日志。
• API发现：发现可用的Kubernetes API资源及其功能。
• Base64实用工具：对Kubernetes机密和配置进行Base64数据的编码和解码。
• 多种传输模式：支持标准输入输出（stdio）和服务器发送事件（SSE）两种通信方式。
• 只读安全：在保持全面检查能力的同时，完全防止破坏性操作。
• 命名空间支持：可处理特定命名空间或集群范围的资源。
• 高级过滤：支持标签选择器、字段选择器和分页。
• 单命令上下文：为单个命令指定不同的Kubernetes上下文。
• 环境变量支持：自动检测 KUBECONFIG 环境变量。
• 启动连接检查：在启动时自动验证集群连接性和基本权限。

📦 安装指南

你可以从 发布页面 下载预构建的二进制文件。

或者，你也可以在macOS或Linux系统上使用Homebrew进行安装：

brew install patrickdappollonio/tap/mcp-kubernetes-ro

你还能将其作为NPM包使用，只需确保将配置提供给你的AI代理：

npx -y @patrickdappollonio/mcp-kubernetes-ro

最后，Docker用户可以从GitHub容器注册表中拉取预构建的镜像：

docker pull ghcr.io/patrickdappollonio/mcp-kubernetes-ro:latest

编辑器配置

将以下配置添加到你的编辑器设置中，以使用 mcp-kubernetes-ro：

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "mcp-kubernetes-ro",
      "args": [
        // 按需取消注释并修改：
        // "--kubeconfig=/path/to/kubeconfig",
        // "--namespace=default",
        // "--transport=stdio",
        // "--port=8080",
        // "--disabled-tools=get_logs,decode_base64"
      ],
      "env": {
        // 按需设置KUBECONFIG环境变量：
        // "KUBECONFIG": "/path/to/kubeconfig",
        // 按需设置MCP_KUBERNETES_RO_DISABLED_TOOLS环境变量：
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // 或者使用通用的DISABLED_TOOLS环境变量：
        // "DISABLED_TOOLS": "get_logs,decode_base64"
      }
    }
  }
}

你可以像上面那样直接从 $PATH 中使用 mcp-kubernetes-ro，也可以提供二进制文件的完整路径（例如 /path/to/mcp-kubernetes-ro）。

你还可以通过将其作为 npx 包来简化安装过程：

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "npx",
      "args": [
        "-y",
        "@patrickdappollonio/mcp-kubernetes-ro"
        // 按需取消注释并修改：
        // "--kubeconfig=/path/to/kubeconfig",
        // "--namespace=default",
        // "--transport=stdio",
        // "--port=8080",
        // "--disabled-tools=get_logs,decode_base64"
      ],
      "env": {
        // 按需设置KUBECONFIG环境变量：
        // "KUBECONFIG": "/path/to/kubeconfig",
        // 按需设置MCP_KUBERNETES_RO_DISABLED_TOOLS环境变量：
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // 或者使用通用的DISABLED_TOOLS环境变量：
        // "DISABLED_TOOLS": "get_logs,decode_base64"
      }
    }
  }
}

以下是如何使用Docker镜像的示例：

{
  "mcpServers": {
    "kubernetes-ro": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "KUBECONFIG=/root/.kube/config",
        "-v", "/path/to/kubeconfig:/root/.kube/config",
        "ghcr.io/patrickdappollonio/mcp-kubernetes-ro"
        // 在此处添加其他标志，例如 --disabled-tools=get_logs,decode_base64
      ],
      "env": {
        // 按需设置KUBECONFIG环境变量：
        // "KUBECONFIG": "/path/to/kubeconfig",
        // 按需设置MCP_KUBERNETES_RO_DISABLED_TOOLS环境变量：
        // "MCP_KUBERNETES_RO_DISABLED_TOOLS": "get_logs,decode_base64",
        // 或者使用通用的DISABLED_TOOLS环境变量：
        // "DISABLED_TOOLS": "get_logs,decode_base64"
      }
    },
  }
}

请注意，你需要将你的kubeconfig文件挂载到容器中，并将 KUBECONFIG 环境变量设置为挂载文件的路径，或者使用 --kubeconfig 标志进行设置。

前提条件

• 有效的Kubernetes配置文件（通常为 ~/.kube/config）。
• 有效的凭证和集群访问权限（无需安装kubectl二进制文件）。
• 进行读操作所需的适当RBAC权限。
• 指标服务器（指标工具必需）：要使用指标功能（get_node_metrics、get_pod_metrics），必须在你的集群中安装指标服务器。如果未安装，这些工具将返回错误消息。

💻 使用示例

可用的MCP工具

共有 10个工具 可供使用：

• list_resources：按类型列出任何Kubernetes资源，并可选择进行过滤，结果按最新排序。
• get_resource：获取特定资源的详细信息。
• get_logs：通过高级过滤选项（包括grep模式、时间过滤和上一次日志）获取Pod日志。
• get_pod_containers：列出Pod内的容器，以便访问日志。
• list_api_resources：列出可用的Kubernetes API资源及其详细信息（类似于kubectl api-resources）。
• list_contexts：从kubeconfig文件中列出可用的Kubernetes上下文。
• get_node_metrics：获取节点指标（CPU和内存使用情况）。
• get_pod_metrics：获取Pod指标（CPU和内存使用情况）。
• encode_base64：将文本数据编码为Base64格式。
• decode_base64：将Base64数据解码为文本格式。

工具管理

禁用工具

你可以使用 --disabled-tools 命令行标志或环境变量来禁用特定工具，工具名称以逗号分隔。支持两个环境变量以适应不同的使用场景：

• MCP_KUBERNETES_RO_DISABLED_TOOLS：特定于应用的变量，不会与其他工具冲突。
• DISABLED_TOOLS：通用变量，可在环境中的多个工具间共享。

优先级顺序：

1. 命令行标志：--disabled-tools=NAMES（优先级最高）。
2. 特定于应用的环境变量：MCP_KUBERNETES_RO_DISABLED_TOOLS。
3. 通用环境变量：DISABLED_TOOLS。

这在以下场景中非常有用：

• 安全：禁用可能暴露敏感信息的工具（例如 get_logs、decode_base64）。
• 性能：在不需要时禁用资源密集型工具（例如 get_node_metrics、get_pod_metrics）。
• 特定环境：禁用集群中不可用的工具（例如，未安装指标服务器时禁用指标工具）。
• 合规性：限制功能以满足组织策略。

可禁用的工具名称：

• list_resources
• get_resource
• get_logs
• get_pod_containers
• list_api_resources
• list_contexts
• get_node_metrics
• get_pod_metrics
• encode_base64
• decode_base64

当一个工具被禁用时，它将不会在MCP服务器中注册，也不会出现在可用工具列表中。同时，会在标准错误输出中记录一条消息，指示哪些工具已被跳过。

示例：

# 使用命令行标志（优先级最高）
mcp-kubernetes-ro --disabled-tools=encode_base64,decode_base64,get_logs

# 使用特定于应用的环境变量
export MCP_KUBERNETES_RO_DISABLED_TOOLS=encode_base64,decode_base64,get_logs
mcp-kubernetes-ro

# 使用通用环境变量
export DISABLED_TOOLS=encode_base64,decode_base64,get_logs
mcp-kubernetes-ro

# 优先级演示：命令行标志优先于环境变量
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs
export DISABLED_TOOLS=get_pod_metrics
mcp-kubernetes-ro --disabled-tools=encode_base64,decode_base64

# 优先级演示：特定于应用的环境变量优先于通用环境变量
export MCP_KUBERNETES_RO_DISABLED_TOOLS=encode_base64,decode_base64
export DISABLED_TOOLS=get_logs,get_pod_metrics
mcp-kubernetes-ro

# 输出：Skipping disabled tool: "encode_base64"
# 输出：Skipping disabled tool: "decode_base64"

运行模式

标准（stdio）模式

默认情况下，mcp-kubernetes-ro 以stdio模式运行，适用于与通过标准输入/输出进行通信的编辑器和其他工具集成。

mcp-kubernetes-ro

服务器发送事件（SSE）模式

你也可以将 mcp-kubernetes-ro 作为支持SSE的HTTP服务器运行，以实现基于Web的集成：

mcp-kubernetes-ro --transport=sse --port=8080

在SSE模式下，服务器将监听指定端口（默认：8080），并通过HTTP使用服务器发送事件提供相同的MCP工具。这对于Web应用程序或不适合使用stdio通信的环境非常有用。

配置选项

以下命令行标志可用于配置MCP服务器：

Kubernetes配置

• --kubeconfig=PATH：kubeconfig文件的路径（默认为 KUBECONFIG 环境变量，然后是 ~/.kube/config）。
• --namespace=NAME：操作的默认命名空间（默认为当前命名空间）。

传输选项

• --transport=TYPE：传输类型：stdio 或 sse（默认：stdio）。
• --port=PORT：SSE服务器的端口（默认：8080，仅在使用 --transport=sse 时使用）。

工具管理

• --disabled-tools=NAMES：以逗号分隔的要禁用的工具名称列表（可选）。
• MCP_KUBERNETES_RO_DISABLED_TOOLS：特定于应用的环境变量，用于禁用工具（命令行标志优先级更高）。
• DISABLED_TOOLS：通用环境变量，用于禁用工具（优先级低于 MCP_KUBERNETES_RO_DISABLED_TOOLS）。

上下文配置

服务器支持单命令上下文，这在处理同一 $KUBECONFIG 文件中的多个Kubernetes集群或上下文时提供了更大的灵活性。

配置优先级：

1. 命令级上下文：在单个工具调用中使用 context 参数。
2. Kubeconfig默认值：使用kubeconfig文件中指定的当前上下文。

Kubeconfig解析优先级：

1. 命令行标志：--kubeconfig 参数。
2. 环境变量：KUBECONFIG 环境变量。
3. 默认路径：~/.kube/config。
4. 集群内配置：在Kubernetes Pod内运行时自动检测。

示例：

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production-cluster"
}

这种方法允许你：

• 在同一会话中为不同操作使用不同的上下文。
• 无需重启服务器即可按命令切换上下文。
• 与现有的kubeconfig设置保持兼容。

工具使用文档

列出资源

按类型列出任何Kubernetes资源，并可选择进行过滤，结果按最新排序。

参数：

• resource_type（必需）：要列出的资源类型 - 使用复数形式（例如 'pods'、'deployments'、'services'）。
• api_version（可选）：资源的API版本（例如 'v1'、'apps/v1'）。
• namespace（可选）：目标命名空间（为空则表示集群范围的资源）。
• context（可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）。
• label_selector（可选）：用于过滤资源的标签选择器（例如 'app=nginx,version=1.0'）。
• field_selector（可选）：用于过滤资源的字段选择器（例如 'status.phase=Running'）。
• limit（可选）：要返回的最大资源数量（默认为所有）。
• continue（可选）：分页的继续令牌（来自上一次响应）。

示例：

{
  "resource_type": "pods",
  "namespace": "default",
  "context": "production",
  "label_selector": "app=nginx"
}

获取资源

获取特定资源的详细配置信息。

参数：

• resource_type（必需）：要获取的资源类型。
• name（必需）：资源名称。
• api_version（可选）：资源的API版本（例如 'v1'、'apps/v1'）。
• namespace（可选）：目标命名空间（对于命名空间资源是必需的）。
• context（可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）。

示例：

{
  "resource_type": "deployment",
  "name": "nginx-deployment",
  "namespace": "default",
  "context": "production"
}

获取日志

通过高级过滤选项（包括grep模式、时间过滤和上一次日志）获取Pod日志。

参数：

• namespace（必需）：Pod所在的命名空间。
• name（必需）：Pod名称。
• container（可选）：容器名称（对于多容器Pod是必需的）。
• context（可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）。
• max_lines（可选）：要检索的最大行数。
• grep_include（可选）：仅包含匹配这些模式的行（以逗号分隔）。类似于grep - 包含包含任何这些模式的行。
• grep_exclude（可选）：排除匹配这些模式的行（以逗号分隔）。类似于grep -v - 排除包含任何这些模式的行。
• use_regex（可选）：是否将grep模式视为正则表达式而不是字面字符串。
• since（可选）：返回比此时间更新的日志。支持持续时间（如 "5m"、"1h"、"2h30m"、"1d"）或绝对时间（如 "2023-01-01T10:00:00Z"）。
• previous（可选）：返回上一次终止的容器实例的日志（类似于kubectl logs --previous）。

示例：

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "container": "nginx",
  "context": "production",
  "max_lines": "100",
  "grep_include": "error,warning",
  "since": "5m"
}

获取Pod容器

列出Pod内的容器，以便访问日志。

参数：

• namespace（必需）：Pod所在的命名空间。
• name（必需）：Pod名称。
• context（可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）。

示例：

{
  "namespace": "default",
  "name": "nginx-pod-12345",
  "context": "production"
}

列出API资源

列出可用的Kubernetes API资源及其详细信息（类似于kubectl api-resources）。

参数： 无

示例：

{}

列出上下文

从kubeconfig文件中列出可用的Kubernetes上下文。这对于发现可用于其他工具中 context 参数的上下文非常有用。

参数： 无

示例：

{}

示例响应：

{
  "contexts": [
    {
      "name": "production",
      "cluster": "prod-cluster",
      "user": "prod-user",
      "namespace": "default",
      "current": true
    },
    {
      "name": "staging",
      "cluster": "staging-cluster",
      "user": "staging-user",
      "namespace": "staging",
      "current": false
    }
  ],
  "count": 2
}

获取节点指标

从指标服务器获取节点指标（CPU和内存使用情况）。由于内置的指标服务器端点不支持基于指针的分页，结果按时间戳（最新优先）排序，以实现一致的排序和分页。

参数：

• node_name（可选）：要获取指标的特定节点名称。如果未提供，则返回所有节点的指标。
• context（可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）。
• limit（可选）：要返回的最大节点指标数量。如果未提供，则返回所有可用指标。
• continue（可选）：分页的继续令牌（来自上一次响应）。

错误处理：

• 如果指标服务器不可用，返回错误消息。
• 检测常见的指标服务器错误并提供具体指导。

示例：

{
  "node_name": "worker-node-1",
  "context": "production",
  "limit": 5
}

示例响应（单个节点）：

{
  "kind": "NodeMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "worker-node-1",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "10.062s",
  "usage": {
    "cpu": "137m",
    "memory": "1368128Ki"
  }
}

示例响应（带分页的列表）：

{
  "kind": "NodeMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "count": 5,
  "items": [
    {
      "kind": "NodeMetrics",
      "metadata": { "name": "node-1" },
      "timestamp": "2023-01-01T12:00:00Z",
      "usage": { "cpu": "137m", "memory": "1368128Ki" }
    }
  ],
  "continue": "eyJvZmZzZXQiOjUsInR5cGUiOiJub2RlIiwibmFtZXNwYWNlIjoiIn0="
}

获取Pod指标

从指标服务器获取Pod指标（CPU和内存使用情况）。由于内置的指标服务器端点不支持基于指针的分页，结果按时间戳（最新优先）排序，以实现一致的排序和分页。

参数：

• namespace（可选）：要获取Pod指标的命名空间。如果未提供，则返回所有命名空间中所有Pod的指标。
• pod_name（可选）：要获取指标的特定Pod名称。如果指定，则需要 namespace。
• context（可选）：要使用的Kubernetes上下文（默认为kubeconfig中的当前上下文）。
• limit（可选）：要返回的最大Pod指标数量。如果未提供，则返回所有可用指标。
• continue（可选）：分页的继续令牌（来自上一次响应）。

错误处理：

• 如果指标服务器不可用，返回错误消息。
• 检测常见的指标服务器错误并提供具体指导。
• 验证在指定 pod_name 时是否提供了 namespace。

分页说明：

• 继续令牌具有上下文感知能力，如果命名空间上下文发生变化则会重置。
• 实现了客户端分页，以实现一致的排序和过滤。

示例（特定Pod）：

{
  "namespace": "kube-system",
  "pod_name": "metrics-server-557ff575fb-9dcl4",
  "context": "production"
}

示例（带分页）：

{
  "namespace": "kube-system",
  "context": "production",
  "limit": 10,
  "continue": "eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

示例响应（单个Pod）：

{
  "kind": "PodMetrics",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "metadata": {
    "name": "metrics-server-557ff575fb-9dcl4",
    "namespace": "kube-system",
    "creationTimestamp": "2023-01-01T12:00:00Z"
  },
  "timestamp": "2023-01-01T12:00:00Z",
  "window": "18.888s",
  "containers": [
    {
      "name": "metrics-server",
      "usage": {
        "cpu": "8020419n",
        "memory": "48164Ki"
      }
    }
  ]
}

示例响应（带分页的列表）：

{
  "kind": "PodMetricsList",
  "apiVersion": "metrics.k8s.io/v1beta1",
  "namespace": "kube-system",
  "count": 10,
  "items": [
    {
      "kind": "PodMetrics",
      "metadata": { "name": "pod-1", "namespace": "kube-system" },
      "timestamp": "2023-01-01T12:00:00Z",
      "containers": [
        {
          "name": "container-1",
          "usage": { "cpu": "8020419n", "memory": "48164Ki" }
        }
      ]
    }
  ],
  "continue": "eyJvZmZzZXQiOjIwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ=="
}

编码Base64

将文本数据编码为Base64格式。

参数：

• data（必需）：要编码的文本数据。

示例：

{
  "data": "username:password"
}

解码Base64

将Base64数据解码为文本格式。

参数：

• data（必需）：要解码的Base64数据。

示例：

{
  "data": "dXNlcm5hbWU6cGFzc3dvcmQ="
}

示例

基本使用示例

# 使用默认的kubeconfig和上下文启动
mcp-kubernetes-ro

# 使用特定的kubeconfig启动
mcp-kubernetes-ro --kubeconfig ~/.kube/config

# 使用KUBECONFIG环境变量启动
export KUBECONFIG=~/.kube/config
mcp-kubernetes-ro

# 使用特定的命名空间启动
mcp-kubernetes-ro --namespace kube-system

# 以SSE模式启动
mcp-kubernetes-ro --transport=sse --port=3000

高级配置示例

# 使用特定的kubeconfig启动生产集群
mcp-kubernetes-ro \
  --kubeconfig ~/.kube/prod-config \
  --namespace monitoring

# 使用环境变量以SSE模式启动开发环境
export KUBECONFIG=~/.kube/dev-config
mcp-kubernetes-ro \
  --transport=sse \
  --port=8080

# 使用单命令上下文（在工具调用中指定上下文）
# 现在上下文在工具级别指定，而不是全局指定

# 出于安全或性能原因禁用特定工具
mcp-kubernetes-ro --disabled-tools=get_logs,decode_base64

# 当指标服务器不可用时禁用指标工具
mcp-kubernetes-ro --disabled-tools=get_node_metrics,get_pod_metrics

# 在生产环境中禁用多个工具
mcp-kubernetes-ro \
  --kubeconfig ~/.kube/prod-config \
  --disabled-tools=encode_base64,decode_base64,get_logs

# 使用特定于应用的环境变量禁用工具
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs,decode_base64
mcp-kubernetes-ro

# 使用通用环境变量禁用工具
export DISABLED_TOOLS=get_logs,decode_base64
mcp-kubernetes-ro

# 命令行标志优先于两个环境变量
export MCP_KUBERNETES_RO_DISABLED_TOOLS=get_logs,decode_base64
export DISABLED_TOOLS=get_pod_metrics
mcp-kubernetes-ro --disabled-tools=get_node_metrics,get_pod_metrics

📚 详细文档

使用场景

集群故障排除

• 跨命名空间列出失败的Pod。
• 获取详细的资源配置信息。
• 检索Pod日志以进行调试。
• 发现可用的API资源。

资源发现

• 按类型探索集群资源。
• 查找具有特定标签的资源。
• 了解资源之间的关系。
• 识别资源配置。

安全与合规

• 只读访问可防止意外更改。
• 在无修改风险的情况下检查配置。
• 审计资源状态和设置。
• 安全地探索生产集群。

AI辅助操作

• 让AI助手帮助诊断集群问题。
• 获取针对资源问题的智能建议。
• 自动进行日志分析和模式识别。
• 通过自然语言查询Kubernetes资源。

AI助手注意事项

虽然此MCP服务器为Kubernetes集群检查提供了全面的工具，但一些AI助手可能存在限制或策略，即使技术上可用，也会阻止它们使用某些工具组合：

潜在限制

• 机密访问：由于安全策略对凭据处理的限制，一些AI助手可能拒绝检索、解码或显示Kubernetes机密（即使使用提供的 get_resource 和 decode_base64 工具）。
• 敏感数据：无论用户权限或工具可用性如何，AI模型可能内置了限制，禁止在聊天界面中暴露敏感信息。
• 安全模式：某些AI助手优先考虑安全最佳实践而非技术能力，可能拒绝执行可能暴露敏感数据的操作。

解决方法

如果你的AI助手因安全原因拒绝使用可用工具，可以采取以下措施：

1. 直接使用CLI访问：直接使用 kubectl 进行敏感操作，并让AI提供要运行的命令，例如：

   kubectl get secret <secret-name> -n <namespace> -o yaml
   echo "<base64-data>" | base64 -d
   

2. 手动使用工具：如果以编程方式使用MCP服务器，可以直接调用工具，而不是通过AI助手。
3. 考虑安全影响：AI的拒绝可能实际上是在保护你避免意外暴露凭据。

设计理念

这种行为反映了不同的安全方法：

• 基于工具：如果你拥有工具和权限，就应该能够使用它们。
• AI安全：优先防止意外暴露，而非技术能力。 在设计涉及敏感数据检索的工作流程时，应考虑到这一限制。

启动连接检查

MCP服务器在启动时会自动进行连接检查，以验证是否能够成功连接到你的Kubernetes集群。此检查包括：

1. API服务器可达性：验证Kubernetes API服务器是否可访问并响应。
2. 身份验证：确认你的凭据是否有效并被集群接受。
3. API发现：测试服务器是否能够发现可用的API资源。
4. 基本权限：验证你至少具有对命名空间的读访问权限（基本RBAC检查）。

你将看到的内容

启动成功后，你将看到如下输出：

Testing connectivity to Kubernetes cluster...
✓ Successfully connected to Kubernetes cluster (version: v1.28.0, 4 namespaces accessible)

故障排除连接问题

如果连接检查失败，你将看到详细的错误消息。常见问题包括：

• 无效的kubeconfig：检查你的kubeconfig文件是否存在且格式正确。
• 集群不可达：验证集群端点是否可从你的网络访问。
• 身份验证失败：确保你的凭据未过期且有效。
• 权限不足：验证你至少具有对基本集群资源的读访问权限。 连接检查有30秒的超时时间，以防止在无响应的集群上挂起。

安全注意事项

• 只读访问：服务器仅支持读操作（get、list、watch）。
• 本地身份验证：使用你现有的kubectl配置和凭据。
• 无破坏性操作：无法创建、更新或删除资源。
• 命名空间隔离：遵守kubeconfig中的RBAC权限。
• 安全通信：支持标准输入输出和基于HTTPS的SSE通信。

指标实现细节

错误检测与处理

指标工具（get_node_metrics 和 get_pod_metrics）包含复杂的错误检测机制，用于检测指标服务器的可用性：

• 自动检测：检测指标服务器是否未安装或无响应。
• 有用的错误消息：在指标服务器缺失时提供特定的安装命令。
• 常见错误模式：识别各种指标服务器错误场景：
  • metrics-server 服务未找到。
  • metrics.k8s.io API组不可用。
  • “服务器无法找到请求的资源” 错误。
  • “无可用指标” 情况。

分页实现

两个指标工具都实现了客户端分页，以确保结果的一致性，因为内置的指标服务器端点不支持基于指针的分页，同时也为AI工具提供了一种安全的方式来请求所需的数据，尤其适用于小上下文窗口。

• 排序：所有结果在分页前按时间戳（最新优先）排序。
• 继续令牌：Base64编码的JSON令牌包含：
  • offset：结果集中的当前位置。
  • type：资源类型（“node” 或 “pod”）。
  • namespace：上下文命名空间（对于Pod指标）。
• 上下文感知：当命名空间上下文发生变化时，分页状态重置。
• 令牌格式：eyJvZmZzZXQiOjEwLCJ0eXBlIjoicG9kIiwibmFtZXNwYWNlIjoia3ViZS1zeXN0ZW0ifQ==

资源检索策略

• 先获取再过滤：始终从服务器检索所有可用指标，然后应用客户端过滤和分页。
• 一致排序：确保跨分页请求的结果可预测。
• 命名空间范围：在提供时自动将Pod指标范围限定到特定命名空间。

错误处理

服务器为常见问题提供详细的错误消息：

• 无效的资源类型或API版本。
• 缺少必需的参数。
• RBAC权限错误。
• 网络连接问题。
• 格式错误的kubeconfig文件。
• 指标服务器不可用（提供安装指导）。

局限性

• 需要本地kubectl配置。
• 仅支持只读访问（无写操作）。
• 仅限于你的kubeconfig凭据可访问的资源。
• 不支持日志的实时流式传输（仅静态检索）。
• 除API资源外，不支持自定义资源定义的发现。