k8sgpt 是一款用于扫描 Kubernetes 集群、诊断问题并以简洁英文分类问题的工具。

其分析器中整合了 SRE 经验，有助于提取最相关的信息并通过 AI 进行丰富。

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

姊妹项目： 查看 https://github.com/AlexsJones/sympozium/ 以管理 Kubernetes 中的代理。

目录

• 概述
• 安装
• 快速开始
• 分析器
• 示例
• LLM AI 后端
• 主要功能
• 模型上下文协议 (MCP)
• 文档
• 贡献
• 社区

CLI 安装

Linux/Mac 通过 brew

brew install k8sgpt

或

brew tap k8sgpt-ai/k8sgpt
brew install k8sgpt

基于 RPM 的安装（RedHat/CentOS/Fedora）

32 位：

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

64 位：

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

基于 DEB 的安装（Ubuntu/Debian）

32 位：

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

64 位：

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

基于 APK 的安装（Alpine）

32 位：

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

64 位：

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

在 WSL 或 Linux 上安装失败（缺少 gcc） 在 WSL 或 Linux 上安装 Homebrew 时，可能会遇到以下错误：

==> 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.

如果按提示安装 gcc，问题仍会存在。因此，需要安装 build-essential 包。

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

Windows

• 从 https://github.com/k8sgpt-ai/k8sgpt/releases 标签页下载最新的 k8sgpt Windows 二进制文件（根据系统架构选择）。
• 将下载的包解压到所需位置。将二进制文件位置配置到系统 PATH 环境变量中

Operator 安装

如需在 Kubernetes 集群内安装，请使用我们的 k8sgpt-operator，安装说明可在 https://github.com/k8sgpt-ai/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 官方文档。

示例：

• 简单过滤器：k8sgpt filters remove Service
• 多个过滤器：k8sgpt filters remove Ingress,Pod

其他命令

列出已配置的后端

k8sgpt auth list

更新已配置的后端

k8sgpt auth update $MY_BACKEND1,$MY_BACKEND2..

移除已配置的后端

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

列出集成

k8sgpt integrations list

激活集成

k8sgpt integrations activate [integration(s)]

使用集成

k8sgpt analyze --filter=[integration(s)]

停用集成

k8sgpt integrations deactivate [integration(s)]

服务模式

k8sgpt serve

带MCP（模型上下文协议）的服务模式

# 在默认端口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

MCP服务器支持与Claude Desktop等MCP兼容客户端集成。它默认运行在8089端口，提供：

• 通过MCP协议进行Kubernetes集群分析
• 资源信息和健康状态
• AI驱动的问题解释和建议

如需部署支持MCP的Helm chart，请参见charts/k8sgpt/values-mcp-example.yaml文件。

服务模式下的分析

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
The stats mode allows for debugging and understanding the time taken by an analysis by displaying the statistics of each analyzer.
- Analyzer Ingress took 47.125583ms
- Analyzer PersistentVolumeClaim took 53.009167ms
- Analyzer CronJob took 57.517792ms
- Analyzer Deployment took 156.6205ms
- Analyzer Node took 160.109833ms
- Analyzer ReplicaSet took 245.938333ms
- Analyzer StatefulSet took 448.0455ms
- Analyzer Pod took 5.662594708s
- Analyzer Service took 38.583359166s

诊断信息

要收集诊断信息，请使用以下命令在本地目录中创建dump_<timestamp>.json文件：

k8sgpt dump

LLM AI后端

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

可使用k8sgpt auth list列出可用提供商：

Default:
> openai
Active:
Unused:
> openai
> localai
> ollama
> azureopenai
> cohere
> amazonbedrock
> amazonsagemaker
> google
> huggingface
> noopai
> googlevertexai
> watsonxai
> customrest
> ibmwatsonxai

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

设置新的默认提供商

k8sgpt auth default -p azureopenai
Default provider set to 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

关键特性

通过此选项，数据在发送到AI后端前会进行脱敏处理。在分析执行期间，k8sgpt会检索敏感数据（Kubernetes对象名称、标签等）。这些数据在发送到AI后端时会被 masking（替换为密钥），并在解决方案返回给用户时使用该密钥进行去脱敏。

脱敏流程

1. 分析期间报告的错误：

Error: HorizontalPodAutoscaler uses StatefulSet/fake-deployment as ScaleTargetRef which does not exist.

2. 发送到AI后端的 payload：

Error: HorizontalPodAutoscaler uses StatefulSet/tGLcCRcHa1Ce5Rs as ScaleTargetRef which does not exist.

3. AI返回的 payload：

The Kubernetes system is trying to scale a StatefulSet named tGLcCRcHa1Ce5Rs using the HorizontalPodAutoscaler, but it cannot find the StatefulSet. The solution is to verify that the StatefulSet name is spelled correctly and exists in the same namespace as the HorizontalPodAutoscaler.

4. 返回给用户的 payload：

The Kubernetes system is trying to scale a StatefulSet named fake-deployment using the HorizontalPodAutoscaler, but it cannot find the StatefulSet. The solution is to verify that the StatefulSet name is spelled correctly and exists in the same namespace as the HorizontalPodAutoscaler.

更多详情

[!NOTE] 注意：脱敏目前不适用于事件。

在部分分析器（如Pod）中，我们会将事件消息提供给AI后端，由于这些消息无法提前预知，因此目前暂不进行 masking。

• 以下是正在被脱敏的分析器列表：

• Statefulset

• Service

• PodDisruptionBudget

• Node

• NetworkPolicy

• Ingress

• HPA

• Deployment

• Cronjob

• 以下是未被脱敏的分析器列表：

• ReplicaSet

• PersistentVolumeClaim

• Pod

• Log

• *Events

*注意：

• k8sgpt 不会对上述分析器进行 masking，因为除Events分析器外，它们不发送任何标识信息。

• Events分析器的 masking 计划在近期实施，详见此https://github.com/k8sgpt-ai/k8sgpt/issues/560%E3%80%82_%E9%9C%80%E8%A6%81%E8%BF%9B%E4%B8%80%E6%AD%A5%E7%A0%94%E7%A9%B6%E4%BB%A5%E7%90%86%E8%A7%A3%E4%BA%8B%E4%BB%B6%E6%A8%A1%E5%BC%8F%EF%BC%8C%E5%B9%B6%E8%83%BD%E5%A4%9F%E5%AF%B9%E4%BA%8B%E4%BB%B6%E4%B8%AD%E7%9A%84%E6%95%8F%E6%84%9F%E9%83%A8%E5%88%86%EF%BC%88%E5%A6%82Pod%E5%90%8D%E7%A7%B0%E3%80%81%E5%91%BD%E5%90%8D%E7%A9%BA%E9%97%B4%E7%AD%89%EF%BC%89%E8%BF%9B%E8%A1%8C masking。_

• 以下是未被脱敏的字段列表：

• Describe

• ObjectStatus

• Replicas

• ContainerStatus

• *Event Message

• ReplicaStatus

• Count (Pod)

*注意：

• 事件消息的 payload 中可能包含类似“super-secret-project-pod-X crashed”的内容，我们目前暂不进行 redact（计划在近期实施，详见此https://github.com/k8sgpt-ai/k8sgpt/issues/560%EF%BC%89%E3%80%82

谨慎操作

• K8gpt团队建议在关键生产环境中使用完全不同的后端**（本地模型）**。通过使用本地模型，您可以确保所有内容都保留在DMZ内，不会发生任何数据泄露。
• 如果对于向公共LLM（如OpenAI、Azure AI）发送数据的可能性存在任何不确定性，且这对业务关键操作构成风险，那么在这种情况下，应根据个人评估和相关风险的管辖范围避免使用公共LLM。

配置管理

k8sgpt 将配置数据存储在 $XDG_CONFIG_HOME/k8sgpt/k8sgpt.yaml 文件中。数据以明文形式存储，包括您的OpenAI密钥。

配置文件位置：

在某些场景下，可能更倾向于远程缓存。在这些场景中，K8sGPT支持AWS S3或Azure Blob存储集成。

远程缓存

[!NOTE] 一次只能配置和使用一个远程缓存

添加远程缓存

• AWS S3

  • 前提条件：需要将 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 作为环境变量。
  • 配置命令：k8sgpt cache add s3 --region <区域> --bucket <桶名称>
  • 使用HTTP端点的Minio配置：k8sgpt cache add s3 --bucket <桶名称> --endpoint <http://minio-endpoint>
  • 使用HTTPS端点的Minio配置（跳过TLS验证）：k8sgpt cache add s3 --bucket <桶名称> --endpoint <https://minio-endpoint> --insecure
  • 如果桶不存在，K8sGPT将创建该桶

• Azure存储

  • 我们支持多种身份验证方法来向Azure进行身份验证
  • 配置命令：k8sgpt cache add azure --storageacc <存储账户名称> --container <容器名称>
  • K8sGPT假设存储账户已存在，如果容器不存在，它将创建该容器
  • 用户有责任为其身份授予特定权限，以便能够上传Blob文件和创建存储账户容器（例如，Storage Blob Data Contributor角色）

• Google Cloud Storage

  • 前提条件：需要将 GOOGLE_APPLICATION_CREDENTIALS 作为环境变量。
  • 配置命令：k8sgpt cache add gcs --region <区域> --bucket <桶名称> --projectid <项目ID>
  • 如果桶不存在，K8sGPT将创建该桶

列出缓存项

k8sgpt cache list

从缓存中清除对象

[!NOTE] 使用此命令清除对象将删除上游文件，因此需要适当的权限。

k8sgpt cache purge $OBJECT_NAME

移除远程缓存

[!NOTE] 这不会删除上游S3桶或Azure存储容器

k8sgpt cache remove

自定义分析器

在某些场景下，您可能希望用自己选择的语言编写自定义分析器。K8sGPT现在支持通过遵循https://github.com/k8sgpt-ai/schemas/blob/main/protobuf/schema/v1/custom_analyzer.proto%E5%B9%B6%E6%8F%90%E4%BE%9B%E5%88%86%E6%9E%90%E5%99%A8%E6%9C%8D%E5%8A%A1%E6%9D%A5%E5%AE%9E%E7%8E%B0%E8%BF%99%E4%B8%80%E7%82%B9%E3%80%82

为此，在K8sGPT配置中定义分析器，它将被添加到扫描流程中。此外，您需要在分析时启用以下标志：

k8sgpt analyze --custom-analysis

以下是一个用https://github.com/k8sgpt-ai/host-analyzer%E7%BC%96%E5%86%99%E7%9A%84%E6%9C%AC%E5%9C%B0%E4%B8%BB%E6%9C%BA%E5%88%86%E6%9E%90%E5%99%A8%E7%A4%BA%E4%BE%8B%E3%80%82%E5%BD%93%E5%AE%83%E5%9C%A8 localhost:8080 上运行时，K8sGPT配置可以通过添加以下内容来获取它：

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

这使得能够将主机操作系统信息（来自此分析器示例）传递给K8sGPT，作为常规分析的上下文。

有关如何编写自定义分析器的文档，请参见

列出已配置的自定义分析器

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"

模型上下文协议（MCP）

K8sGPT提供模型上下文协议（MCP）服务器，将Kubernetes操作作为标准化工具公开，供Claude、***和其他MCP兼容客户端等AI助手使用。

启动MCP服务器：

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

k8sgpt serve --mcp

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

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

功能：

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

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

文档

官方文档可在 此处 获取。

贡献

请阅读我们的贡献指南。

社区

在 Slack 上加入我们。