GoogleCloudPlatform/kubectl-ai

# kubectl-ai [](https://goreportcard.com/report/github.com/GoogleCloudPlatform/kubectl-ai)  [](https://deepwiki.com/GoogleCloudPlatform/kubectl-ai) [](https://github.com/GoogleCloudPlatform/kubectl-ai/stargazers) `kubectl-ai` 作为一个智能接口，将用户意图转化为精确的 Kubernetes 操作，使 Kubernetes 管理更加便捷高效。  ## 目录 - [快速开始](#quick-start) - [安装](#installation) - [使用](#usage) - [配置](#configuration) - [工具](#tools) - [Docker 快速开始](#docker-quick-start) - [MCP 客户端模式](#mcp-client-mode) - [额外功能](#extras) - [MCP 服务端模式](#mcp-server-mode) - [开始贡献](#start-contributing) - [学习资源](#learning-resources) ## 快速开始 首先，请确保已安装并配置好 kubectl。 ### 安装 #### 快速安装 (仅限 Linux & MacOS) ``` curl -sSL https://raw.githubusercontent.com/GoogleCloudPlatform/kubectl-ai/main/install.sh | bash ```

其他安装方法

#### 手动安装 1. 从 [releases 页面](https://github.com/GoogleCloudPlatform/kubectl-ai/releases/latest) 为您的目标机器下载最新版本。 2. 解压发布的文件，使二进制文件可执行，并将其移动到 $PATH 中的目录（如下所示）。 ``` tar -zxvf kubectl-ai_Darwin_arm64.tar.gz chmod a+x kubectl-ai sudo mv kubectl-ai /usr/local/bin/ ``` #### 使用 Krew 安装 首先，您需要安装 krew，更多详情请参阅 [krew 文档](https://krew.sigs.k8s.io/docs/user-guide/setup/install/) 然后您可以使用 krew 进行安装 ``` kubectl krew install ai ``` 现在您可以像这样作为 kubectl 插件调用 `kubectl-ai`：`kubectl ai`。 #### 在 NixOS 上安装 在 NixOS 上安装 `kubectl-ai` 有多种方式。若要永久安装，请将以下内容添加到您的 NixOS-Configuration 中： ``` 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](https://aistudio.google.com) 获取一个。 ``` export GEMINI_API_KEY=your_api_key_here kubectl-ai # 使用不同的 gemini model kubectl-ai --model gemini-2.5-pro-exp-03-25 # 使用 2.5 flash (更快) model kubectl-ai --quiet --model gemini-2.5-flash-preview-04-17 "check logs for nginx app in hello namespace" ```

使用其他 AI 模型

#### 使用本地运行的 AI 模型 (ollama 或 llama.cpp) 您可以将 `kubectl-ai` 与本地运行的 AI 模型结合使用。`kubectl-ai` 支持 [ollama](https://ollama.com/) 和 [llama.cpp](https://github.com/ggml-org/llama.cpp) 来使用本地运行的 AI 模型。 此外，[`modelserving`](modelserving) 目录提供了在本地或 Kubernetes 集群上部署您自己的基于 `llama.cpp` 的 LLM 服务端点的工具和说明。这允许您直接在您的环境中托管像 Gemma 这样的模型。 一个使用 Google 的 `gemma3` 模型配合 `ollama` 的示例： ``` # 假设 ollama 已经在运行，并且您已经拉取了其中一个 gemma models # ollama pull gemma3:12b-it-qat # 如果您的 ollama server 位于远程，请使用 OLLAMA_HOST 变量指定主机 # export OLLAMA_HOST=http://192.168.1.3:11434/ # 启用 enable-tool-use-shim，因为 models 需要特殊提示才能启用 tool calling kubectl-ai --llm-provider ollama --model gemma3:12b-it-qat --enable-tool-use-shim # 您可以使用 `models` 命令发现本地可用的 models >> models ``` #### 使用 Grok 您可以通过设置 X.AI API 密钥来使用 X.AI 的 Grok 模型： ``` export GROK_API_KEY=your_xai_api_key_here kubectl-ai --llm-provider=grok --model=grok-3-beta ``` #### 使用 AWS Bedrock 您可以使用您的 AWS 凭证来使用 AWS Bedrock Claude 模型： ``` # 使用 AWS SSO 配置 AWS credentials aws sso login --profile your-profile-name # 或者使用其他 AWS credential 方法（IAM roles、环境变量等） # 使用 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 # 通过环境变量覆盖 model export BEDROCK_MODEL=us.anthropic.claude-sonnet-4-20250514-v1:0 kubectl-ai --llm-provider=bedrock ``` AWS Bedrock 使用标准的 AWS SDK 凭证链，支持： - AWS SSO 配置文件 - IAM 角色 (用于 EC2/ECS/Lambda) - 环境变量 (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) - AWS CLI 配置文件 #### 使用 Azure OpenAI 您也可以通过设置您的 OpenAI API 密钥并指定提供商来使用 Azure OpenAI 部署： ``` 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 ``` #### 使用 OpenAI 您也可以通过设置您的 OpenAI API 密钥并指定提供商来使用 OpenAI 模型： ``` export OPENAI_API_KEY=your_openai_api_key_here kubectl-ai --llm-provider=openai --model=gpt-4.1 ``` #### 使用 OpenAI 兼容 API 例如，您可以按如下方式使用阿里云 qwen-xxx 模型。 ``` 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 "fetch logs for nginx app in hello namespace" ``` 与其他 unix 命令结合使用： ``` kubectl-ai < query.txt # 或 echo "list pods in the default namespace" | kubectl-ai ``` 您甚至可以将位置参数与 stdin 输入结合使用。位置参数将用作 stdin 内容的前缀： ``` cat error.log | kubectl-ai "explain the error" ``` 我们还通过选择性加入支持运行之间的持久化。这允许您将会话保存到本地文件系统，并恢复它以保持先前的上下文。它甚至可以在不同的接口之间工作！ ``` kubectl-ai --new-session # start a new session kubectl-ai --list-sessions # list all saved sessions kubectl-ai --resume-session 20250807-510872 # resume session 20250807-510872 kubectl-ai --delete-session 20250807-510872 # delete session 20250807-510872 ``` ## 配置 您还可以使用位于 `~/.config/kubectl-ai/config.yaml` 的 YAML 配置文件来配置 `kubectl-ai`： ``` mkdir -p ~/.config/kubectl-ai/ cat < ~/.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 provider 配置 llmProvider: "gemini" # Default LLM provider model: "gemini-2.5-pro-preview-06-05" # Default model skipVerifySSL: false # Skip SSL verification for LLM API calls # Tool 和权限设置 toolConfigPaths: ["~/.config/kubectl-ai/tools.yaml"] # Custom tools configuration paths skipPermissions: false # Skip confirmation for resource-modifying commands enableToolUseShim: false # Enable tool use shim for certain models # MCP 配置 mcpServer: false # Run in MCP server mode mcpClient: false # Enable MCP client mode externalTools: false # Discover external MCP tools (requires mcp-server) # Runtime 设置 maxIterations: 20 # Maximum iterations for the agent quiet: false # Run in non-interactive mode removeWorkdir: false # Remove temporary working directory after execution # Kubernetes 配置 kubeconfig: "~/.kube/config" # Path to kubeconfig file # UI 配置 uiType: "terminal" # UI mode: "terminal" or "web" uiListenAddress: "localhost:8888" # Address for HTML UI server # Prompt 配置 promptTemplateFilePath: "" # Custom prompt template file extraPromptPaths: [] # Additional prompt template paths # Debug 和 trace 设置 tracePath: "/tmp/kubectl-ai-trace.txt" # Path to trace file ```

所有这些设置都可以通过以下任一方式配置： 1. 命令行标志 (例如 `--model=gemini-2.5-pro`) 2. 配置文件 (`~/.config/kubectl-ai/config.yaml`) 3. 环境变量 (例如 `GEMINI_API_KEY`) 命令行标志优先于配置文件设置。 ## 工具 `kubectl-ai` 利用 LLM 使用一组强大的工具来建议和执行 Kubernetes 操作。它附带内置工具，如 `kubectl` 和 `bash`。 您还可以通过定义自己的自定义工具来扩展其功能。默认情况下，`kubectl-ai` 会在 `~/.config/kubectl-ai/tools.yaml` 中查找您的工具配置。 要指定工具配置文件或包含工具配置文件的目录，请使用： ``` ./kubectl-ai --custom-tools-config= "your prompt here" ``` 有关如何配置您自己的工具的更多详细信息，[请转至此处](docs/tools.md)。 ## Docker 快速开始 本项目提供一个 Docker 镜像，为您提供一个运行 kubectl-ai 的独立环境，包括针对 GKE 集群的运行。 ### 针对 GKE 运行容器 #### 步骤 1：构建镜像 克隆仓库并使用以下命令构建镜像 ``` git clone https://github.com/GoogleCloudPlatform/kubectl-ai.git cd kubectl-ai docker build -t kubectl-ai:latest -f images/kubectl-ai/Dockerfile . ``` #### 步骤 2：连接到您的 GKE 集群 设置应用默认凭证并连接到您的 GKE 集群。 ``` gcloud auth application-default login # If in a gcloud shell this is not necessary gcloud container clusters get-credentials --zone ``` #### 步骤 3：运行 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](CONTAINER.md) ## MCP 客户端模式 `kubectl-ai` 可以连接到外部 [MCP](https://modelcontextprotocol.io/examples) 服务器，以访问除内置工具之外的其他工具。 ### MCP 客户端快速开始 启用 MCP 客户端模式： ``` kubectl-ai --mcp-client ``` ### MCP 客户端配置 创建或编辑 `~/.config/kubectl-ai/mcp.yaml` 以自定义 MCP 服务器： ``` servers: # Local MCP server (stdio-based) # sequential-thinking: Advanced reasoning and step-by-step analysis - name: sequential-thinking command: npx args: - -y - "@modelcontextprotocol/server-sequential-thinking" # Remote MCP server (HTTP-based) - name: cloudflare-documentation url: https://docs.mcp.cloudflare.com/mcp # Optional: Remote MCP server with authentication - name: custom-api url: https://api.example.com/mcp auth: type: "bearer" token: "${MCP_TOKEN}" ``` 系统会自动： - 转换参数名称 (snake_case → camelCase) - 处理类型转换 (在适当时将字符串转换为数字/布尔值) - 为未知服务器提供回退行为 无需额外设置 —— 只需使用 `--mcp-client` 标志，AI 就能访问所有已配置的 MCP 工具。 📖 **有关 MCP 客户端模式的详细配置选项、故障排除和高级功能，请参阅 [MCP 客户端文档](docs/mcp-client.md)。** 📖 **有关多服务器编排和安全自动化示例，请参阅 [MCP 客户端集成指南](docs/mcp-client.md)。** ## 额外功能 您可以使用以下特殊关键字执行特定操作： - `model`：显示当前选择的模型。 - `models`：列出所有可用的模型。 - `tools`：列出所有可用的工具。 - `version`：显示 `kubectl-ai` 版本。 - `reset`：清除对话上下文。 - `clear`：清除终端屏幕。 - `exit` 或 `quit`：终止交互式 shell (Ctrl+C 也可行)。 ### 作为 kubectl 插件调用 您也可以运行 `kubectl ai`。`kubectl` 会将 `PATH` 中任何名称以 `kubectl-` 开头的可执行文件视为[插件](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/)。 ## MCP 服务端模式 `kubectl-ai` 可以充当 MCP 服务器，将 kubectl 工具暴露给其他 MCP 客户端（如 Claude、Cursor 或 VS Code）。该服务器可以在两种模式下运行： ### 基础 MCP 服务器 (仅限内置工具) 仅暴露 kubectl-ai 的原生 Kubernetes 工具： ``` kubectl-ai --mcp-server ``` ### 增强型 MCP 服务器 (具有外部工具发现) 额外发现并暴露来自其他 MCP 服务器的工具，作为统一接口： ``` kubectl-ai --mcp-server --external-tools ``` 这将创建一个强大的**工具聚合中心**，其中 kubectl-ai 同时充当： - **MCP Server**：向客户端暴露 kubectl 工具 - **MCP Client**：使用来自其他 MCP 服务器的工具 要通过使用可流式传输在 HTTP 上为客户端提供服务，请运行： ``` kubectl-ai --mcp-server --mcp-server-mode streamable-http --http-port 9080 ``` 这将在 `http://localhost:9080/mcp` 启动一个 MCP 端点。 增强模式通过单个 MCP 端点为 AI 客户端提供对 Kubernetes 操作和通用工具（文件系统、网页搜索、数据库等）的访问。 📖 **有关详细配置、示例和故障排除，请参阅 [MCP 服务端文档](docs/mcp-server.md)。** ## 开始贡献 我们欢迎社区对 `kubectl-ai` 的贡献。请查看我们的[贡献指南](contributing.md)以开始。 ## 学习资源 ### 演讲与演示 - [From Natural Language to K8s Operations: The MCP Architecture and Practice of kubectl-ai](https://blog.wu-boy.com/2025/10/from-natural-language-to-k8s-operations-the-mcp-architecture-and-practice-of-kubectl-ai-en) - 这是一个涵盖 kubectl-ai 与 MCP (Model Context Protocol) 的架构和实践应用的全面演示。 *注意：这不是 Google 官方支持的产品。本项目不符合 [Google 开源软件漏洞奖励计划](https://bughunters.google.com/open-source-security) 的资格。*

标签：AI, AIOps, AI风险缓解, DLL 劫持, DNS解析, EVTX分析, EVTX分析, Golang, GoogleCloudPlatform, K8s管理, kubectl, LLM, MCP, Shell, Unmanaged PE, 大语言模型, 子域名突变, 安全编程, 容器编排, 开源项目, 效率工具, 日志审计, 智能运维, 特权提升, 自动化代码审查, 自动化部署, 请求拦截