kubectl-ai

kubectl-ai 作为一个智能接口，能够将用户的意图转化为精确的 Kubernetes 操作，从而让 Kubernetes 的管理更加便捷高效。

目录

• 快速入门
  • 安装
  • 使用
• 配置
• 工具
• Docker 快速入门
• MCP 客户端模式
• 其他
• MCP 服务器模式
• 开始贡献
• 学习资源

快速入门

首先，请确保已安装并正确配置了 kubectl。

安装

快速安装（仅限 Linux 和 macOS）

curl -sSL https://raw.githubusercontent.com/GoogleCloudPlatform/kubectl-ai/main/install.sh | bash

tar -zxvf kubectl-ai_Darwin_arm64.tar.gz
chmod a+x kubectl-ai
sudo mv kubectl-ai /usr/local/bin/

kubectl krew install ai

  environment.systemPackages = with pkgs; [
    kubectl-ai
  ];

nix-shell -p kubectl-ai

使用

kubectl-ai 支持来自 gemini、vertexai、azopenai、openai、grok、bedrock 的 AI 模型，以及本地 LLM 提供商如 ollama 和 llama.cpp。

使用 Gemini（默认）

将您的 Gemini API 密钥设置为环境变量。如果您还没有密钥，请从 Google AI Studio 获取。

export GEMINI_API_KEY=your_api_key_here
kubectl-ai

# 使用不同的 Gemini 模型
kubectl-ai --model gemini-2.5-pro-exp-03-25

# 使用 2.5 flash（更快）模型
kubectl-ai --quiet --model gemini-2.5-flash-preview-04-17 "查看 hello 命名空间中 nginx 应用的日志"

# 假设 ollama 已经运行，并且您已经拉取了其中一个 gemma 模型
# ollama pull gemma3:12b-it-qat

# 如果您的 ollama 服务器位于远程主机上，请使用 OLLAMA_HOST 变量指定主机地址
# export OLLAMA_HOST=http://192.168.1.3:11434/

# 启用 tool-use-shim，因为这些模型需要特殊的提示才能启用工具调用
kubectl-ai --llm-provider ollama --model gemma3:12b-it-qat --enable-tool-use-shim

# 您可以使用 `models` 命令来发现本地可用的模型
>> models

export GROK_API_KEY=your_xai_api_key_here
kubectl-ai --llm-provider=grok --model=grok-3-beta

# 使用 AWS SSO 配置 AWS 凭证
aws sso login --profile your-profile-name
# 或者使用其他 AWS 凭证方法（IAM 角色、环境变量等）

# 使用 Claude 4 Sonnet（默认）
kubectl-ai --llm-provider=bedrock --model=us.anthropic.claude-sonnet-4-20250514-v1:0

# 使用 Claude 3.7 Sonnet
kubectl-ai --llm-provider=bedrock --model=us.anthropic.claude-3-7-sonnet-20250219-v1:0

# 通过环境变量覆盖模型
export BEDROCK_MODEL=us.anthropic.claude-sonnet-4-20250514-v1:0
kubectl-ai --llm-provider=bedrock

export AZURE_OPENAI_API_KEY=your_azure_openai_api_key_here
export AZURE_OPENAI_ENDPOINT=https://your_azure_openai_endpoint_here
kubectl-ai --llm-provider=azopenai --model=your_azure_openai_deployment_name_here
# 或
az login
kubectl-ai --llm-provider=openai://your_azure_openai_endpoint_here --model=your_azure_openai_deployment_name_here

export OPENAI_API_KEY=your_openai_api_key_here
kubectl-ai --llm-provider=openai --model=gpt-4.1

export OPENAI_API_KEY=your_openai_api_key_here
export OPENAI_ENDPOINT=https://dashscope.aliyuncs.com/compatible-mode/v1
kubectl-ai --llm-provider=openai --model=qwen-plus

以交互模式运行：

kubectl-ai

交互模式允许您与 kubectl-ai 进行对话，依次提出多个问题，同时保持上下文连贯。只需输入您的问题并按 Enter 键即可获得回复。要退出交互式 Shell，输入 exit 或按 Ctrl+C。

或者，直接输入任务来运行：

kubectl-ai --quiet "获取 hello 命名空间中 nginx 应用的日志"

还可以与其他 Unix 命令结合使用：

kubectl-ai < query.txt

# 或者
echo "列出默认命名空间中的 Pod" | kubectl-ai

你甚至可以将位置参数与标准输入结合使用。位置参数会作为标准输入内容的前缀：

cat error.log | kubectl-ai "解释这个错误"

我们还支持通过选择加入的方式实现跨运行的持久化。这允许你将会话保存到本地文件系统，并在之后恢复以保持之前的上下文。它甚至可以在不同的界面之间正常工作！

kubectl-ai --new-session # 开始一个新的会话
kubectl-ai --list-sessions # 列出所有已保存的会话
kubectl-ai --resume-session 20250807-510872 # 恢复会话 20250807-510872
kubectl-ai --delete-session 20250807-510872 # 删除会话 20250807-510872

配置

你还可以使用位于 ~/.config/kubectl-ai/config.yaml 的 YAML 配置文件来配置 kubectl-ai：

mkdir -p ~/.config/kubectl-ai/
cat <<EOF > ~/.config/kubectl-ai/config.yaml
model: gemini-2.5-flash-preview-04-17
llmProvider: gemini
toolConfigPaths: ~/.config/kubectl-ai/tools.yaml
EOF

验证你的配置：

kubectl-ai --quiet model

# LLM 提供商配置
llmProvider: "gemini"               # 默认 LLM 提供商
model: "gemini-2.5-pro-preview-06-05" # 默认模型
skipVerifySSL: false              # 跳过 LLM API 调用的 SSL 验证

# 工具和权限设置
toolConfigPaths: ["~/.config/kubectl-ai/tools.yaml"]  # 自定义工具配置路径
skipPermissions: false             # 跳过对修改资源命令的确认
enableToolUseShim: false        # 为某些模型启用工具使用适配层

# MCP 配置
mcpServer: false                  # 以 MCP 服务器模式运行
mcpClient: false                  # 启用 MCP 客户端模式
externalTools: false             # 发现外部 MCP 工具（需要 mcp-server）

# 运行时设置
maxIterations: 20                 # 代理的最大迭代次数
quiet: false                       # 以非交互模式运行
removeWorkdir: false             # 执行后删除临时工作目录

# Kubernetes 配置
kubeconfig: "~/.kube/config"      # kubeconfig 文件路径

# UI 配置
uiType: "terminal"                # UI 模式："terminal" 或 "web"
uiListenAddress: "localhost:8888" # HTML UI 服务器地址

# 提示词配置
promptTemplateFilePath: ""      # 自定义提示词模板文件
extraPromptPaths: []            # 其他提示词模板路径

# 调试和追踪设置
tracePath: "/tmp/kubectl-ai-trace.txt" # 追踪文件路径

所有这些设置都可以通过以下方式配置：

1. 命令行标志（例如 --model=gemini-2.5-pro）
2. 配置文件（~/.config/kubectl-ai/config.yaml）
3. 环境变量（例如 GEMINI_API_KEY）

命令行标志的优先级高于配置文件设置。

工具

kubectl-ai 利用大语言模型，借助一组强大的工具来建议并执行 Kubernetes 操作。它自带 kubectl 和 bash 等内置工具。

你也可以通过定义自己的自定义工具来扩展其功能。默认情况下，kubectl-ai 会在 ~/.config/kubectl-ai/tools.yaml 中查找你的工具配置。

要指定工具配置文件或包含工具配置文件的目录，请使用：

./kubectl-ai --custom-tools-config=<工具目录路径> "你的提示语在这里"

有关如何配置自定义工具的更多信息，请参阅 tools.md。

Docker 快速入门

该项目提供了一个 Docker 镜像，为你提供一个独立的环境来运行 kubectl-ai，包括针对 GKE 集群的使用。

在 GKE 上运行容器

第一步：构建镜像

克隆仓库并使用以下命令构建镜像：

git clone https://github.com/GoogleCloudPlatform/kubectl-ai.git
cd kubectl-ai
docker build -t kubectl-ai:latest -f images/kubectl-ai/Dockerfile .

第二步：连接到你的 GKE 集群

设置应用默认凭据并连接到你的 GKE 集群。

gcloud auth application-default login # 如果在 gcloud shell 中，则无需此步骤
gcloud container clusters get-credentials <集群名称> --zone <区域>

第三步：运行 kubectl-ai 容器

以下是一个可用于启动带有本地托管 Web UI 的容器的示例命令。请务必将占位符值替换为你具体的 Google Cloud 项目 ID 和位置。请注意，如果你使用的是 cloudshell 机器，则无需挂载 gcloud 配置目录。

docker run --rm -it -p 8080:8080 -v ~/.kube:/root/.kube -v ~/.config/gcloud:/root/.config/gcloud -e GOOGLE_CLOUD_LOCATION=us-central1 -e GOOGLE_CLOUD_PROJECT=my-gcp-project kubectl-ai:latest --llm-provider vertexai --ui-listen-address 0.0.0.0:8080 --ui-type web

有关从容器镜像运行的更多信息，请参阅 CONTAINER.md。

MCP 客户端模式

注意： MCP 客户端模式在 kubectl-ai 版本 v0.0.12 及以上版本中可用。

kubectl-ai 可以连接到外部 MCP 服务器，以访问除内置工具之外的其他工具。

使用 MCP 客户端的快速入门

启用 MCP 客户端模式：

kubectl-ai --mcp-client

MCP 客户端配置

创建或编辑 ~/.config/kubectl-ai/mcp.yaml 来自定义 MCP 服务器：

servers:
  # 本地 MCP 服务器（基于标准输入输出）
  # sequential-thinking：高级推理和逐步分析
  - name: sequential-thinking
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-sequential-thinking"
  
  # 远程 MCP 服务器（基于 HTTP）
  - name: cloudflare-documentation
    url: https://docs.mcp.cloudflare.com/mcp
    
  # 可选：带身份验证的远程 MCP 服务器
  - name: custom-api
    url: https://api.example.com/mcp
    auth:
      type: "bearer"
      token: "${MCP_TOKEN}"

系统会自动：

• 将参数名称转换为驼峰命名法（snake_case → camelCase）
• 处理类型转换（在适当的情况下将字符串转换为数字或布尔值）
• 对未知服务器提供回退行为

无需额外设置——只需使用 --mcp-client 标志，AI 就可以访问所有已配置的 MCP 工具。

📖 有关 MCP 客户端模式的详细配置选项、故障排除及高级功能，请参阅 MCP 客户端文档。

📖 有关多服务器编排和安全自动化示例，请参阅 MCP 客户端集成指南。

附加功能

您可以使用以下特殊关键字来执行特定操作：

• model：显示当前选定的模型。
• models：列出所有可用模型。
• tools：列出所有可用工具。
• version：显示 kubectl-ai 的版本。
• reset：清除对话上下文。
• clear：清空终端屏幕。
• exit 或 quit：退出交互式 Shell（也可使用 Ctrl+C）。

作为 kubectl 插件调用

您也可以直接运行 kubectl ai。kubectl 会将 PATH 环境变量中以 kubectl- 开头的任何可执行文件识别为插件，具体请参阅 kubectl 插件文档。

MCP 服务器模式

kubectl-ai 可以作为 MCP 服务器，向其他 MCP 客户端（如 Claude、Cursor 或 VS Code）暴露 kubectl 工具。该服务器支持两种运行模式：

基础 MCP 服务器（仅内置工具）

仅暴露 kubectl-ai 自带的 Kubernetes 工具：

kubectl-ai --mcp-server

增强型 MCP 服务器（包含外部工具发现）

除了内置工具外，还会发现并暴露来自其他 MCP 服务器的工具，形成统一的接口：

kubectl-ai --mcp-server --external-tools

这种方式构建了一个强大的 工具聚合中心，其中 kubectl-ai 同时扮演以下角色：

• MCP 服务器：向客户端暴露 kubectl 工具
• MCP 客户端：从其他 MCP 服务器获取工具

若需通过 HTTP 流式传输方式为客户端提供服务，可以运行以下命令：

kubectl-ai --mcp-server --mcp-server-mode streamable-http --http-port 9080

这将在 http://localhost:9080/mcp 启动一个 MCP 端点。

增强模式使 AI 客户端能够通过单一 MCP 端点访问 Kubernetes 操作以及通用工具（文件系统、网络搜索、数据库等）。

📖 有关详细配置、示例和故障排除，请参阅 MCP 服务器文档。

开始贡献

我们欢迎社区对 kubectl-ai 的贡献。请查看我们的 贡献指南，开始参与吧。

学习资源

技术演讲与演示

• 从自然语言到 K8s 操作：kubectl-ai 的 MCP 架构与实践 - 一场全面的演示，深入探讨了 kubectl-ai 结合 MCP（Model Context Protocol）的架构设计与实际应用。

注：本项目并非 Google 官方支持的产品。该项目不符合 Google 开源软件漏洞奖励计划 的资格。

kubectl-ai 快速上手指南

kubectl-ai 是一个智能 Kubernetes 管理工具，能将自然语言指令转化为精确的 kubectl 操作，支持 Gemini、OpenAI、Ollama 等多种大模型。

环境准备

• 操作系统：Linux, macOS, Windows
• 前置依赖：
  • 已安装并配置好 kubectl (确保能正常访问集群)。
  • (可选) 拥有一个大模型 API Key (如 Google Gemini, OpenAI, Azure OpenAI 等) 或本地运行的大模型服务 (如 Ollama)。

安装步骤

方法一：一键安装脚本 (推荐 Linux & macOS)

curl -sSL https://raw.githubusercontent.com/GoogleCloudPlatform/kubectl-ai/main/install.sh | bash

方法二：通过 Krew 安装 (跨平台)

如果你已安装 krew，可执行：

kubectl krew install ai

安装后通过 kubectl ai 命令调用。

方法三：手动安装

1. 从 Releases 页面 下载对应系统的压缩包。
2. 解压并赋予执行权限，移动到 $PATH 目录：

tar -zxvf kubectl-ai_<OS>_<ARCH>.tar.gz
chmod a+x kubectl-ai
sudo mv kubectl-ai /usr/local/bin/

基本使用

1. 配置 API Key

以默认的 Google Gemini 模型为例，设置环境变量：

export GEMINI_API_KEY=your_api_key_here

提示：若无 Key，可前往 Google AI Studio 获取。若使用其他模型（如 OpenAI、Ollama），请参考下方“切换模型”部分设置对应变量。

2. 交互式使用

直接运行命令进入交互模式，可连续提问并保持上下文：

kubectl-ai

示例对话：

>> list pods in the default namespace
>> show me the logs for the nginx pod
>> exit

3. 单次任务执行

使用 --quiet 标志直接执行单个任务并输出结果：

kubectl-ai --quiet "fetch logs for nginx app in hello namespace"

结合管道使用：

echo "list pods in the default namespace" | kubectl-ai
# 或
cat error.log | kubectl-ai "explain the error"

4. 切换 AI 模型

kubectl-ai 支持多种模型提供商，通过 --llm-provider 和 --model 参数切换：

• 使用本地 Ollama 模型 (需先启动 ollama 并 pull 模型):

  kubectl-ai --llm-provider ollama --model gemma3:12b-it-qat --enable-tool-use-shim
  

• 使用 OpenAI:

  export OPENAI_API_KEY=your_openai_api_key_here
  kubectl-ai --llm-provider=openai --model=gpt-4.1
  

• 使用 AWS Bedrock:

  # 确保 AWS 凭证已配置 (aws sso login 或环境变量)
  kubectl-ai --llm-provider=bedrock --model=us.anthropic.claude-sonnet-4-20250514-v1:0
  

• 使用 Azure OpenAI:

  export AZURE_OPENAI_API_KEY=your_key
  export AZURE_OPENAI_ENDPOINT=https://your-endpoint
  kubectl-ai --llm-provider=azopenai --model=your-deployment-name
  

5. 会话管理 (持久化上下文)

支持保存和恢复会话上下文，便于后续继续讨论：

kubectl-ai --new-session             # 开始新会话
kubectl-ai --list-sessions           # 列出已保存的会话
kubectl-ai --resume-session <ID>     # 恢复指定会话