k8sgpt 是一款用于扫描 Kubernetes 集群、诊断并以简单英语对问题进行分类处理的工具。

它将 SRE 经验编码到分析器中，并帮助提取最相关的信息，再结合 AI 技术进一步丰富这些信息。

开箱即用，支持与 OpenAI、Azure、Cohere、Amazon Bedrock、Google Gemini 以及本地模型集成。

姊妹项目： 如果您想在 Kubernetes 中管理代理，请查看 sympozium。

目录

• 概述
• 安装
• 快速入门
• 分析器
• 示例
• LLM AI 后端
• 关键特性
• 模型上下文协议 (MCP)
• 文档
• 贡献
• 社区
• 许可证

CLI 安装

Linux/Mac 通过 brew

brew install k8sgpt

或者

brew tap k8sgpt-ai/k8sgpt
brew install k8sgpt

sudo rpm -ivh https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.31/k8sgpt_386.rpm

sudo rpm -ivh https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.31/k8sgpt_amd64.rpm

curl -LO https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.31/k8sgpt_386.deb
sudo dpkg -i k8sgpt_386.deb

curl -LO https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.31/k8sgpt_amd64.deb
sudo dpkg -i k8sgpt_amd64.deb

wget https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.31/k8sgpt_386.apk
apk add --allow-untrusted k8sgpt_386.apk

wget https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.31/k8sgpt_amd64.apk
apk add --allow-untrusted k8sgpt_amd64.apk

==> Installing k8sgpt from k8sgpt-ai/k8sgpt Error: The following formula cannot be installed from a bottle and must be
built from the source. k8sgpt Install Clang or run brew install gcc.

   sudo apt-get update
   sudo apt-get install build-essential

Windows

• 请根据您的系统架构，从 Release 页面下载最新版本的 k8sgpt Windows 二进制文件。
• 将下载的压缩包解压到您希望存放的位置，并配置系统的 PATH 环境变量以指向该二进制文件所在目录。

Operator 安装

如需在 Kubernetes 集群内安装，请使用我们的 k8sgpt-operator，安装说明请参见 此处。

此运行模式非常适合对集群进行持续监控，并可与您现有的监控系统（如 Prometheus 和 Alertmanager）集成。

快速入门

• 当前默认的 AI 提供商是 OpenAI，您需要先从 OpenAI 生成一个 API 密钥。
  • 您可以通过运行 k8sgpt generate 打开浏览器链接来生成密钥。
• 运行 k8sgpt auth add 将其设置到 k8sgpt 中。
  • 您也可以直接使用 --password 标志提供密码。
• 运行 k8sgpt filters 来管理分析器使用的活动过滤器。默认情况下，所有过滤器都会在分析过程中执行。
• 运行 k8sgpt analyze 开始扫描。
• 使用 k8sgpt analyze --explain 可以获得更详细的故障说明。
• 您还可以运行 k8sgpt analyze --with-doc（无论是否使用 explain 标志），以获取来自 Kubernetes 的官方文档。

与 Claude Desktop 配合使用

K8sGPT 可以与 Claude Desktop 集成，从而提供基于 AI 的 Kubernetes 集群分析功能。此集成需要 K8sGPT v0.4.14 或更高版本。

前置条件

1. 安装 K8sGPT v0.4.14 或更高版本：

   brew install k8sgpt
   

2. 从官方网站安装 Claude Desktop

3. 使用您偏好的 AI 后端配置 K8sGPT：

   k8sgpt auth
   

设置

1. 启动 K8sGPT 的 MCP 服务器：

   k8sgpt serve --mcp
   

2. 在 Claude Desktop 中：

   • 打开设置
   • 导航到集成部分
   • 添加 K8sGPT 作为新的集成
   • MCP 服务器将自动被检测到

3. 使用以下 JSON 配置 Claude Desktop：

{
  "mcpServers": {
    "k8sgpt": {
      "command": "k8sgpt",
      "args": [
        "serve",
        "--mcp"
      ]
    }
  }
}

使用

连接成功后，您可以使用 Claude Desktop 来：

• 分析您的 Kubernetes 集群
• 获取关于集群健康状况的详细信息
• 获得修复问题的建议
• 查询集群信息

Claude Desktop 中的示例命令：

• “分析我的 Kubernetes 集群”
• “我的集群健康状况如何？”
• “显示 default 命名空间中的任何问题”

故障排除

如果遇到连接问题：

1. 确保 K8sGPT 已启用 MCP 服务器并正在运行
2. 验证您的 Kubernetes 集群是否可访问
3. 检查您的 AI 后端是否已正确配置
4. 重启 K8sGPT 和 Claude Desktop

如需更多信息，请访问我们的 文档。

分析器

K8sGPT 使用分析器来对集群中的问题进行分类和诊断。它内置了一组分析器，但您也可以编写自己的分析器。

内置分析器

默认启用

• podAnalyzer
• pvcAnalyzer
• rsAnalyzer
• serviceAnalyzer
• eventAnalyzer
• ingressAnalyzer
• statefulSetAnalyzer
• deploymentAnalyzer
• jobAnalyzer
• cronJobAnalyzer
• nodeAnalyzer
• mutatingWebhookAnalyzer
• validatingWebhookAnalyzer
• configMapAnalyzer

可选

• hpaAnalyzer
• pdbAnalyzer
• networkPolicyAnalyzer
• gatewayClass
• gateway
• httproute
• logAnalyzer
• storageAnalyzer
• securityAnalyzer
• CatalogSource
• ClusterCatalog
• ClusterExtension
• ClusterService
• ClusterServiceVersion
• OperatorGroup
• InstallPlan
• Subscription

示例

使用默认分析器进行扫描

k8sgpt generate
k8sgpt auth add
k8sgpt analyze --explain
k8sgpt analyze --explain --with-doc

按资源筛选

k8sgpt analyze --explain --filter=Service

按命名空间筛选

k8sgpt analyze --explain --filter=Pod --namespace=default

输出为 JSON

k8sgpt analyze --explain --filter=Service --output=json

解释时匿名化

k8sgpt analyze --explain --filter=Service --output=json --anonymize

k8sgpt filters list

k8sgpt filters add [筛选器]

k8sgpt filters remove [筛选器]

k8sgpt auth list

k8sgpt auth update $MY_BACKEND1,$MY_BACKEND2..

k8sgpt auth remove -b $MY_BACKEND1,$MY_BACKEND2..

k8sgpt integrations list

k8sgpt integrations activate [集成]

k8sgpt analyze --filter=[集成]

k8sgpt integrations deactivate [集成]

k8sgpt serve

# 在默认端口 8089 上启用 MCP 服务器
k8sgpt serve --mcp --mcp-http

# 在自定义端口上启用 MCP 服务器
k8sgpt serve --mcp --mcp-http --mcp-port 8089

# 完整的服务模式，包含 MCP
k8sgpt serve --mcp --mcp-http --port 8080 --metrics-port 8081 --mcp-port 8089

grpcurl -plaintext -d '{"namespace": "k8sgpt", "explain" : "true"}' localhost:8080 schema.v1.ServerAnalyzerService/Analyze
{
  "status": "OK"
}

k8sgpt analyze --explain --custom-headers CustomHeaderKey:CustomHeaderValue

k8sgpt analyze -s
统计模式允许通过显示每个分析器的统计数据来进行调试和了解分析所花费的时间。
- Ingress 分析器耗时 47.125583 毫秒
- PersistentVolumeClaim 分析器耗时 53.009167 毫秒
- CronJob 分析器耗时 57.517792 毫秒
- Deployment 分析器耗时 156.6205 毫秒
- Node 分析器耗时 160.109833 毫秒
- ReplicaSet 分析器耗时 245.938333 毫秒
- StatefulSet 分析器耗时 448.0455 毫秒
- Pod 分析器耗时 5.662594708 秒
- Service 分析器耗时 38.583359166 秒

k8sgpt dump

LLM AI 后端

K8sGPT 会在您使用 --explain 标志（例如 k8sgpt analyze --explain）解释分析结果时，使用您选择的 LLM 或生成式 AI 提供商。您可以使用 --backend 标志来指定已配置的提供商（默认为 openai）。

您可以通过 k8sgpt auth list 列出可用的提供商：

默认：
> openai
活跃：
未使用：
> openai
> localai
> ollama
> azureopenai
> cohere
> amazonbedrock
> amazonsagemaker
> google
> huggingface
> noopai
> googlevertexai
> watsonxai
> customrest
> ibmwatsonxai

有关如何配置和使用每个提供商的详细文档，请参阅此处。

设置新的默认提供商

k8sgpt auth default -p azureopenai
默认提供商已设置为 azureopenai

使用 Amazon Bedrock Converse 和推理配置文件

系统推理配置文件

k8sgpt auth add --backend amazonbedrockconverse --providerRegion us-east-1 --model arn:aws:bedrock:us-east-1:123456789012:inference-profile/my-inference-profile

应用推理配置文件

k8sgpt auth add --backend amazonbedrockconverse --providerRegion us-east-1 --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/2uzp4s0w39t6

使用 Amazon Bedrock 和推理配置文件

系统推理配置文件

k8sgpt auth add --backend amazonbedrock --providerRegion us-east-1 --model arn:aws:bedrock:us-east-1:123456789012:inference-profile/my-inference-profile

应用推理配置文件

k8sgpt auth add --backend amazonbedrock --providerRegion us-east-1 --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/2uzp4s0w39t6

主要特性

错误：HorizontalPodAutoscaler 使用名为 StatefulSet/fake-deployment 的 ScaleTargetRef，但该对象不存在。

错误：HorizontalPodAutoscaler 使用名为 StatefulSet/tGLcCRcHa1Ce5Rs 的 ScaleTargetRef，但该对象不存在。

Kubernetes 系统正尝试使用 HorizontalPodAutoscaler 扩缩名为 tGLcCRcHa1Ce5Rs 的 StatefulSet，但未能找到该 StatefulSet。解决方法是检查 StatefulSet 名称拼写是否正确，并确认其与 HorizontalPodAutoscaler 位于同一命名空间中。

Kubernetes 系统正尝试使用 HorizontalPodAutoscaler 扩缩名为 fake-deployment 的 StatefulSet，但未能找到该 StatefulSet。解决方法是检查 StatefulSet 名称拼写是否正确，并确认其与 HorizontalPodAutoscaler 位于同一命名空间中。

k8sgpt cache list

k8sgpt cache purge $OBJECT_NAME

k8sgpt cache remove

k8sgpt analyze --custom-analysis

custom_analyzers:
  - name: host-analyzer
    connection:
      url: localhost
      port: 8080

k8sgpt custom-analyzer list

k8sgpt custom-analyzer add --name my-custom-analyzer --port 8085

k8sgpt custom-analyzer remove --names "my-custom-analyzer,my-custom-analyzer-2"

K8sGPT 提供了一个模型上下文协议服务器，它将 Kubernetes 操作暴露为标准化工具，供像 Claude、ChatGPT 等 MCP 兼容客户端使用。

启动 MCP 服务器：

标准输入输出模式（适用于本地 AI 助手）：

k8sgpt serve --mcp

HTTP 模式（用于网络访问）：

k8sgpt serve --mcp --mcp-http --mcp-port 8089

功能：

• 12 种用于集群分析、资源管理和调试的工具
• 3 种用于访问集群信息的资源
• 3 个交互式故障排除提示
• 无状态 HTTP 模式，适用于一次性调用
• 与 Claude Desktop 及其他 MCP 客户端的全面集成

了解更多： 请参阅 MCP.md，获取完整的文档、使用示例和集成指南。

文档

我们的官方文档可在 这里 找到。

贡献

请阅读我们的 贡献指南。

社区

您可以在 Slack 上找到我们。

许可证

k8sgpt 快速上手指南

k8sgpt 是一款用于扫描 Kubernetes 集群、诊断问题并以自然语言提供修复建议的 AI 工具。它将 SRE 经验编码到分析器中，并结合 AI 能力帮助用户快速定位和解决集群问题。

环境准备

• 操作系统：Linux (Ubuntu/Debian, CentOS/RHEL, Alpine), macOS, Windows
• 前置依赖：
  • 已配置好 kubectl 并能正常访问 Kubernetes 集群
  • （可选）Homebrew（macOS/Linux 推荐安装方式）
  • AI 提供商 API Key（默认支持 OpenAI，也支持 Azure, Cohere, Amazon Bedrock, Google Gemini 及本地模型）

安装步骤

macOS / Linux (推荐)

使用 Homebrew 安装是最便捷的方式：

brew install k8sgpt

或者通过 Tap 安装：

brew tap k8sgpt-ai/k8sgpt
brew install k8sgpt

Linux (手动安装)

Ubuntu/Debian:

# 64位系统
curl -LO https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.31/k8sgpt_amd64.deb
sudo dpkg -i k8sgpt_amd64.deb

CentOS/RHEL/Fedora:

# 64位系统
sudo rpm -ivh https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.31/k8sgpt_amd64.rpm

Alpine:

# 64位系统
wget https://github.com/k8sgpt-ai/k8sgpt/releases/download/v0.4.31/k8sgpt_amd64.apk
apk add --allow-untrusted k8sgpt_amd64.apk

注意：如果在 WSL 或 Linux 上使用 Homebrew 安装失败并提示缺少 gcc，请运行 sudo apt-get install build-essential 安装构建依赖。

Windows

1. 从 Release 页面 下载对应架构的最新二进制文件。
2. 解压到指定目录。
3. 将该目录添加到系统的 PATH 环境变量中。

基本使用

1. 配置 AI 后端

k8sgpt 默认使用 OpenAI。你需要先获取 API Key 并进行配置。

生成/获取 API Key： 你可以运行以下命令打开浏览器链接生成 Key，或直接在 OpenAI 官网获取：

k8sgpt generate

添加认证信息：

k8sgpt auth add

• 按提示输入 API Key。
• 或者直接使用 flag 传递：k8sgpt auth add --password <YOUR_API_KEY>

如果使用其他 AI 提供商（如 Azure, Google Gemini 等），请参考官方文档配置对应的 backend。

2. 执行集群分析

基础扫描： 对集群进行快速健康检查：

k8sgpt analyze

获取详细解释： 使用 --explain 参数，AI 将对发现的问题提供自然语言的详细解释和修复建议：

k8sgpt analyze --explain

结合官方文档： 使用 --with-doc 参数，在解释的同时附带 Kubernetes 官方文档链接：

k8sgpt analyze --explain --with-doc

3. 高级用法示例

指定资源类型过滤： 只分析特定资源（如 Service 或 Pod）：

k8sgpt analyze --explain --filter=Service

指定命名空间： 只分析特定命名空间下的资源：

k8sgpt analyze --explain --filter=Pod --namespace=default

匿名化输出： 如果担心敏感信息泄露，可以使用 --anonymize 参数对数据进行脱敏处理：

k8sgpt analyze --explain --filter=Service --output=json --anonymize

管理过滤器： 查看、添加或移除默认启用的分析器：

# 列出所有可用过滤器
k8sgpt filters list

# 添加默认过滤器
k8sgpt filters add Service,Pod

# 移除默认过滤器
k8sgpt filters remove Service