kubectl-ai 完全教程:Google 开源的 AI Kubernetes 运维助手

用熟 Kubernetes 的人都知道,日常运维的痛点往往不在"不懂原理",而在"命令拼凑太费劲":查一个应用为什么起不来,要在 get、describe、logs、events 之间来回跳;写一条带标签过滤的查询命令,得先回忆 jsonpath 语法;新人接手集群更是无从下手。有没有一种方式,直接说人话就能操作集群?

kubectl-ai 就是冲着这个问题来的。它是 GoogleCloudPlatform 在 GitHub 开源的 AI Kubernetes 助手(Go 编写,Apache-2.0 协议,约 7.6k Star),定位是一个"智能接口":把用户的自然语言意图翻译成精确的 Kubernetes 操作。它不是简单的命令生成器,而是一个带工具调用能力的 Agent——会自己调用 kubectl、bash 等工具查询集群状态,根据返回结果一步步推理,直到给出结论或完成操作。本文完整走一遍它的安装、配置与实战用法。

先说明一句:按仓库 README 的声明,该项目并非 Google 官方支持的产品(not an officially supported Google product),而是 GoogleCloudPlatform 组织下的开源项目,按社区开源工具看待即可。

一、功能总览

  • 自然语言操作集群:用自然语言描述意图(如"看看 nginx 应用在集群里运行得怎么样"),它自动生成并执行对应的 kubectl 命令并汇总回答
  • Agent 式多步排障:内置 kubectl 与 bash 工具,能连续多轮"查询—分析—再查询"(看 Pod 状态、describe、查日志……),默认最多迭代 20 轮(maxIterations 可调)
  • 多模型提供商:支持 Gemini(默认)、Vertex AI、OpenAI、Azure OpenAI、AWS Bedrock、Grok,以及本地运行的 Ollama、llama.cpp;任何 OpenAI 兼容接口也能接
  • 三种使用姿势:交互式对话(带上下文追问)、一次性非交互任务(--quiet,适合脚本)、标准输入管道(喂日志文件解读)
  • 会话持久化:会话可保存到本地,跨次运行恢复上下文
  • 可扩展工具:除内置工具外,可在 tools.yaml 里定义自定义工具;还支持 MCP 双向模式(客户端调用外部工具、服务端对外暴露 K8s 工具,见第四节进阶部分)
  • 多种运行形态:单二进制、kubectl 插件(kubectl ai)、Docker 容器,终端与 Web 两种 UI

二、安装

前提:本机已安装并配置好 kubectl(kubectl-ai 通过你的 kubeconfig 访问集群,能做什么取决于这份凭据的权限,安全一节会细说)。安装方式有四种,任选其一。

方式 1:一键脚本(Linux / macOS)

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

方式 2:手动安装(Linux / macOS / Windows)

从 GitHub Releases 页面下载对应平台的压缩包,解压后把二进制放进 PATH:

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

方式 3:Krew 插件方式

# 需要先装好 krew 插件管理器
kubectl krew install ai

# 之后可以两种写法等价使用
kubectl ai
kubectl-ai

原理是 kubectl 会把 PATH 里以 kubectl- 开头的可执行文件识别为插件,所以手动安装的二进制同样能用 kubectl ai 调用。

方式 4:NixOS 与 Docker

NixOS 用户可临时运行 nix-shell -p kubectl-ai,或加入系统配置(environment.systemPackages)永久安装。项目还提供 Dockerfile 可构建镜像运行(官方文档有对接 GKE 的完整示例)。

三、模型配置

kubectl-ai 的大脑外包给大模型,--llm-provider 选提供商、--model 选具体模型。默认提供商是 Gemini。

1. Gemini(默认)

# API Key 从 Google AI Studio 免费申请
export GEMINI_API_KEY=your_api_key

kubectl-ai

# 指定其他 Gemini 模型
kubectl-ai --model gemini-2.5-pro-exp-03-25

2. OpenAI 与 OpenAI 兼容接口

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

# 兼容接口示例:接阿里云百炼的通义千问
export OPENAI_API_KEY=your_api_key
export OPENAI_ENDPOINT=https://dashscope.aliyuncs.com/compatible-mode/v1
kubectl-ai --llm-provider=openai --model=qwen-plus

对国内用户很关键:任何 OpenAI 兼容端点(百炼、中转、自建网关)改 OPENAI_ENDPOINT 即可接入。

3. 云厂商托管模型

# AWS Bedrock(走标准 AWS 凭据链:SSO、IAM 角色、环境变量均可)
aws sso login --profile your-profile-name
kubectl-ai --llm-provider=bedrock --model=us.anthropic.claude-sonnet-4-20250514-v1:0

# Azure OpenAI
export AZURE_OPENAI_API_KEY=your_api_key
export AZURE_OPENAI_ENDPOINT=https://your_azure_openai_endpoint_here
kubectl-ai --llm-provider=azopenai --model=your_deployment_name

# Grok(xAI)
export GROK_API_KEY=your_api_key
kubectl-ai --llm-provider=grok --model=grok-3-beta

Vertex AI 同样受支持(--llm-provider vertexai),在 GCP 环境里配合应用默认凭据使用,官方 Docker 对接 GKE 示例用的就是它。

4. 本地模型(Ollama / llama.cpp)

数据不出内网的场景用本地模型:kubectl-ai 支持 Ollama 与 llama.cpp,仓库的 modelserving 目录还提供了部署 llama.cpp 模型服务的方法:

# 先确保 ollama 已运行并拉好模型,如 ollama pull gemma3:12b-it-qat
# 远程 ollama 服务用 OLLAMA_HOST 指定地址
# export OLLAMA_HOST=http://192.168.1.3:11434/

# --enable-tool-use-shim 是给需要特殊提示才能用工具调用的模型准备的垫片
kubectl-ai --llm-provider ollama --model gemma3:12b-it-qat --enable-tool-use-shim

5. 配置文件

不想每次敲参数,把默认配置写进 ~/.config/kubectl-ai/config.yaml:

llmProvider: gemini
model: gemini-2.5-flash-preview-04-17
toolConfigPaths: ~/.config/kubectl-ai/tools.yaml

其他配置项还有 maxIterations(默认 20)、kubeconfig 路径、uiType(terminal/web)、skipPermissions(默认 false)等;优先级为命令行参数高于配置文件,密钥通过环境变量传入。改完可用 kubectl-ai --quiet model 验证生效的模型。

四、使用教程

1. 交互模式:像聊天一样运维

不带参数直接运行进入交互式 shell,可带着上下文连续追问,输入 exit、quit 或 Ctrl+C 退出:

kubectl-ai

# 进入后直接提问,可连续追问
>> how's nginx app doing in my cluster
>> 它最近一小时有没有重启过?
>> 把它的副本数扩到 3 个

交互模式里有一组特殊关键字:model 查看当前模型、models 列出可用模型、tools 列出可用工具、version 看版本、reset 清空上下文、clear 清屏。

2. 非交互模式:一次性任务与脚本集成

# --quiet 非交互执行单个任务,输出结果后退出
kubectl-ai --quiet --model gemini-2.5-flash-preview-04-17 "check logs for nginx app in hello namespace"

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

# 管道组合:把文件或命令输出喂给它解读
kubectl-ai < query.txt
echo "list pods in the default namespace" | kubectl-ai
cat error.log | kubectl-ai "explain the error"

管道用法在排障时特别顺手:报错日志不用自己啃,先让它解释一遍;位置参数会作为前缀与标准输入内容组合成完整提问。

3. 典型排障示例

  • 应用健康巡检:kubectl-ai "how's nginx app doing in my cluster"——它会自行查询 Deployment、Pod、Service 状态并汇总结论
  • 查日志定位问题:指定命名空间与应用让它"check logs",它会翻对应 Pod 日志并提炼关键错误
  • Pod 起不来:在交互模式里问"为什么 xxx 命名空间里的 Pod 一直 Pending/CrashLoopBackOff",它会按 describe 看事件、再看日志的顺序逐项排查,比自己逐个敲命令快得多
  • 批量查询:"列出所有命名空间里重启次数超过 5 次的 Pod"这类要拼复杂命令的查询,自然语言描述即可

4. 会话管理

kubectl-ai --new-session              # 开一个新会话
kubectl-ai --list-sessions            # 列出已保存的会话
kubectl-ai --resume-session 20250807-510872   # 恢复指定会话,接着上次的上下文继续
kubectl-ai --delete-session 20250807-510872   # 删除会话

会话持久化为可选开启。长时间排障中途要关终端时,存下会话、回来 --resume-session 续上,不用重述背景。

5. 进阶:自定义工具与 MCP

只有 kubectl 和 bash 往往不够用:kubectl-ai 支持在 ~/.config/kubectl-ai/tools.yaml 里定义自己的工具,也可用 --custom-tools-config 指定其他工具配置目录。更进一步,它支持 MCP(Model Context Protocol)双向玩法:

# MCP 客户端模式:接入外部 MCP 服务的工具(v0.0.12 起)
kubectl-ai --mcp-client

# MCP 服务端模式:把 K8s 工具暴露给 Claude、Cursor、VS Code 等客户端
kubectl-ai --mcp-server

# 增强模式:同时聚合其他 MCP 服务的工具,统一对外
kubectl-ai --mcp-server --external-tools

# 以 HTTP 方式提供服务(端点为 http://localhost:9080/mcp)
kubectl-ai --mcp-server --mcp-server-mode streamable-http --http-port 9080

MCP 客户端的服务列表配置在 ~/.config/kubectl-ai/mcp.yaml,本地(stdio)与远程(HTTP)服务都可挂载。服务端模式下它相当于工具聚合网关:客户端连进来既能操作 Kubernetes,也能用它聚合的外部工具。

五、安全与权限注意事项

  • 权限上限就是你的 kubeconfig:kubectl-ai 以当前 kubeconfig 凭据的身份操作集群,RBAC 给多少权它最多就有多少权。建议日常用只读或受限的上下文,别拿集群管理员凭据图省事
  • 修改类操作默认要确认,别轻易关:配置项 skipPermissions 默认为 false,即涉及资源变更的命令会先征求确认;设为 true 等于让模型直接改集群,只应在隔离的测试环境考虑
  • 模型会犯错,执行前看一眼命令:LLM 生成的命令可能选错命名空间、写错标签选择器。确认环节展示的命令务必扫一眼再放行,尤其 delete、scale、apply 这类写操作
  • 数据会流向模型提供商:排障时它读取的 Pod 日志、资源定义会作为上下文发给所选的 LLM 服务。涉及敏感数据、合规要求高的环境,优先选本地 Ollama/llama.cpp 或企业托管通道(Bedrock、Vertex AI)
  • MCP 的 HTTP 端点默认无认证:官方文档明确提醒,streamable-http 端点默认不带认证,能连上端口的人就能执行 kubectl 和 bash。只在本机用就绑 localhost;要对外提供,必须加 --mcp-auth-issuer 等参数启用 OAuth 2.1 认证,或放在受控网络内
  • API Key 的保管:各提供商的 Key 都通过环境变量传入,别写进仓库或提交到 Git;Bedrock 走 AWS 标准凭据链(SSO/IAM 角色)更稳妥

六、适用人群与小结

kubectl-ai 适合三类人:一是K8s 新手与偶尔运维的开发,用自然语言跨过命令记忆门槛,顺便在它的执行过程中学到真实的 kubectl 用法;二是值班与排障场景的运维,巡检、查日志、初步定位这类高频动作交给它跑,自己专注判断;三是已在用其他 AI 客户端的团队,通过它的 MCP 服务端模式把集群操作能力统一供给 Claude、Cursor 等工具。

它的边界也要清楚:复杂变更(Helm 发布、生产变更操作)仍应走既有流程和审批,它更适合查询、巡检和初步排障;本地小模型的工具调用能力有限,认真排障建议用 Gemini、Claude、GPT 这一档的模型。在"AI 助手 + 真实工具执行"这条路线上,kubectl-ai 是目前 Kubernetes 方向最值得一试的开源实现之一——安装只要一条命令,拿一个真实排障问题试一次便知合不合手。

发表回复

后才能评论