[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-9913":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":16,"starSnapshotCount":16,"syncStatus":33,"lastSyncTime":34,"discoverSource":35},9913,"kubectl-ai","GoogleCloudPlatform\u002Fkubectl-ai","GoogleCloudPlatform","AI powered Kubernetes Assistant","",null,"Go",7493,703,47,98,0,1,8,39,6,39.54,"Apache License 2.0",false,"main",[26,27,28,29],"ai","assistant","cli","kubernetes","2026-06-12 02:02:14","# kubectl-ai\n\n[![Go Report Card](https:\u002F\u002Fgoreportcard.com\u002Fbadge\u002Fgithub.com\u002FGoogleCloudPlatform\u002Fkubectl-ai)](https:\u002F\u002Fgoreportcard.com\u002Freport\u002Fgithub.com\u002FGoogleCloudPlatform\u002Fkubectl-ai)\n![GitHub License](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Flicense\u002FGoogleCloudPlatform\u002Fkubectl-ai)\n[![Ask DeepWiki](https:\u002F\u002Fdeepwiki.com\u002Fbadge.svg)](https:\u002F\u002Fdeepwiki.com\u002FGoogleCloudPlatform\u002Fkubectl-ai)\n[![GitHub stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002FGoogleCloudPlatform\u002Fkubectl-ai.svg)](https:\u002F\u002Fgithub.com\u002FGoogleCloudPlatform\u002Fkubectl-ai\u002Fstargazers)\n\n`kubectl-ai` acts as an intelligent interface, translating user intent into\nprecise Kubernetes operations, making Kubernetes management more accessible and\nefficient.\n\n![kubectl-ai demo GIF using: kubectl-ai \"how's nginx app doing in my cluster\"](.\u002F.github\u002Fkubectl-ai.gif)\n\n## Table of Contents\n\n- [Quick Start](#quick-start)\n  - [Installation](#installation)\n  - [Usage](#usage)\n- [Configuration](#configuration)\n- [Tools](#tools)\n- [Docker Quick Start](#docker-quick-start)\n- [MCP Client Mode](#mcp-client-mode)\n- [Extras](#extras)\n- [MCP Server Mode](#mcp-server-mode)\n- [Start Contributing](#start-contributing)\n- [Learning Resources](#learning-resources)\n\n## Quick Start\n\nFirst, ensure that kubectl is installed and configured.\n\n### Installation\n\n#### Quick Install (Linux & MacOS only)\n\n```shell\ncurl -sSL https:\u002F\u002Fraw.githubusercontent.com\u002FGoogleCloudPlatform\u002Fkubectl-ai\u002Fmain\u002Finstall.sh | bash\n```\n\n\u003Cdetails>\n\u003Csummary>Other Installation Methods\u003C\u002Fsummary>\n\n#### Manual Installation (Linux, MacOS and Windows)\n\n1. Download the latest release from the [releases page](https:\u002F\u002Fgithub.com\u002FGoogleCloudPlatform\u002Fkubectl-ai\u002Freleases\u002Flatest) for your target machine.\n\n2. Untar the release, make the binary executable and move it to a directory in your $PATH (as shown below).\n\n```shell\ntar -zxvf kubectl-ai_Darwin_arm64.tar.gz\nchmod a+x kubectl-ai\nsudo mv kubectl-ai \u002Fusr\u002Flocal\u002Fbin\u002F\n```\n\n#### Install with Krew (Linux\u002FmacOS\u002FWindows)\n\nFirst of all, you need to have krew installed, refer to [krew document](https:\u002F\u002Fkrew.sigs.k8s.io\u002Fdocs\u002Fuser-guide\u002Fsetup\u002Finstall\u002F) for more details\nThen you can install with krew\n\n```shell\nkubectl krew install ai\n```\n\nNow you can invoke `kubectl-ai` as a kubectl plugin like this: `kubectl ai`.\n\n#### Install on NixOS\n\nThere are multiple ways to install `kubectl-ai` on NixOS. For a permanent installation add the following to your NixOS-Configuration:\n\n```nix\n  environment.systemPackages = with pkgs; [\n    kubectl-ai\n  ];\n```\n\nFor a temporary installation, you can use the following command:\n\n```shell\nnix-shell -p kubectl-ai\n```\n\n\u003C\u002Fdetails>\n\n### Usage\n\n`kubectl-ai` supports AI models from `gemini`, `vertexai`, `azopenai`, `openai`, `grok`, `bedrock` and local LLM providers such as `ollama` and `llama.cpp`.\n\n#### Using Gemini (Default)\n\nSet your Gemini API key as an environment variable. If you don't have a key, get one from [Google AI Studio](https:\u002F\u002Faistudio.google.com).\n\n```bash\nexport GEMINI_API_KEY=your_api_key_here\nkubectl-ai\n\n# Use different gemini model\nkubectl-ai --model gemini-2.5-pro-exp-03-25\n\n# Use 2.5 flash (faster) model\nkubectl-ai --quiet --model gemini-2.5-flash-preview-04-17 \"check logs for nginx app in hello namespace\"\n```\n\n\u003Cdetails>\n\u003Csummary>Use other AI models\u003C\u002Fsummary>\n\n#### Using AI models running locally (ollama or llama.cpp)\n\nYou can use `kubectl-ai` with AI models running locally. `kubectl-ai` supports [ollama](https:\u002F\u002Follama.com\u002F) and [llama.cpp](https:\u002F\u002Fgithub.com\u002Fggml-org\u002Fllama.cpp) to use the AI models running locally.\n\nAdditionally, the [`modelserving`](modelserving) directory provides tools and instructions for deploying your own `llama.cpp`-based LLM serving endpoints locally or on a Kubernetes cluster. This allows you to host models like Gemma directly in your environment.\n\nAn example of using Google's `gemma3` model with `ollama`:\n\n```shell\n# assuming ollama is already running and you have pulled one of the gemma models\n# ollama pull gemma3:12b-it-qat\n\n# if your ollama server is at remote, use OLLAMA_HOST variable to specify the host\n# export OLLAMA_HOST=http:\u002F\u002F192.168.1.3:11434\u002F\n\n# enable-tool-use-shim because models require special prompting to enable tool calling\nkubectl-ai --llm-provider ollama --model gemma3:12b-it-qat --enable-tool-use-shim\n\n# you can use `models` command to discover the locally available models\n>> models\n```\n\n#### Using Grok\n\nYou can use X.AI's Grok model by setting your X.AI API key:\n\n```bash\nexport GROK_API_KEY=your_xai_api_key_here\nkubectl-ai --llm-provider=grok --model=grok-3-beta\n```\n\n#### Using AWS Bedrock\n\nYou can use AWS Bedrock Claude models with your AWS credentials:\n\n```bash\n# Configure AWS credentials using AWS SSO\naws sso login --profile your-profile-name\n# Or use other AWS credential methods (IAM roles, environment variables, etc.)\n\n# Use Claude 4 Sonnet (default)\nkubectl-ai --llm-provider=bedrock --model=us.anthropic.claude-sonnet-4-20250514-v1:0\n\n# Use Claude 3.7 Sonnet\nkubectl-ai --llm-provider=bedrock --model=us.anthropic.claude-3-7-sonnet-20250219-v1:0\n\n# Override model via environment variable\nexport BEDROCK_MODEL=us.anthropic.claude-sonnet-4-20250514-v1:0\nkubectl-ai --llm-provider=bedrock\n```\n\nAWS Bedrock uses the standard AWS SDK credential chain, supporting:\n\n- AWS SSO profiles\n- IAM roles (for EC2\u002FECS\u002FLambda)\n- Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)\n- AWS CLI configuration files\n\n#### Using Azure OpenAI\n\nYou can also use Azure OpenAI deployment by setting your OpenAI API key and specifying the provider:\n\n```bash\nexport AZURE_OPENAI_API_KEY=your_azure_openai_api_key_here\nexport AZURE_OPENAI_ENDPOINT=https:\u002F\u002Fyour_azure_openai_endpoint_here\nkubectl-ai --llm-provider=azopenai --model=your_azure_openai_deployment_name_here\n# or\naz login\nkubectl-ai --llm-provider=openai:\u002F\u002Fyour_azure_openai_endpoint_here --model=your_azure_openai_deployment_name_here\n```\n\n#### Using OpenAI\n\nYou can also use OpenAI models by setting your OpenAI API key and specifying the provider:\n\n```bash\nexport OPENAI_API_KEY=your_openai_api_key_here\nkubectl-ai --llm-provider=openai --model=gpt-4.1\n```\n\n#### Using OpenAI Compatible API\n\nFor example, you can use aliyun qwen-xxx models as follows.\n\n```bash\nexport OPENAI_API_KEY=your_openai_api_key_here\nexport OPENAI_ENDPOINT=https:\u002F\u002Fdashscope.aliyuncs.com\u002Fcompatible-mode\u002Fv1\nkubectl-ai --llm-provider=openai --model=qwen-plus\n```\n\n\u003C\u002Fdetails>\n\nRun interactively:\n\n```shell\nkubectl-ai\n```\n\nThe interactive mode allows you to have a chat with `kubectl-ai`, asking multiple questions in sequence while maintaining context from previous interactions. Simply type your queries and press Enter to receive responses. To exit the interactive shell, type `exit` or press Ctrl+C.\n\nOr, run with a task as input:\n\n```shell\nkubectl-ai --quiet \"fetch logs for nginx app in hello namespace\"\n```\n\nCombine it with other unix commands:\n\n```shell\nkubectl-ai \u003C query.txt\n# OR\necho \"list pods in the default namespace\" | kubectl-ai\n```\n\nYou can even combine a positional argument with stdin input. The positional argument will be used as a prefix to the stdin content:\n\n```shell\ncat error.log | kubectl-ai \"explain the error\"\n```\n\nWe also support persistence between runs with an opt-in. This lets you save a session to the local filesystem, and resume it to maintain previous context. It even works between different interfaces!\n\n```shell\nkubectl-ai --new-session # start a new session\nkubectl-ai --list-sessions # list all saved sessions\nkubectl-ai --resume-session 20250807-510872 # resume session 20250807-510872\nkubectl-ai --delete-session 20250807-510872 # delete session 20250807-510872\n```\n\n## Configuration\n\nYou can also configure `kubectl-ai` using a YAML configuration file at `~\u002F.config\u002Fkubectl-ai\u002Fconfig.yaml`:\n\n```shell\nmkdir -p ~\u002F.config\u002Fkubectl-ai\u002F\ncat \u003C\u003CEOF > ~\u002F.config\u002Fkubectl-ai\u002Fconfig.yaml\nmodel: gemini-2.5-flash-preview-04-17\nllmProvider: gemini\ntoolConfigPaths: ~\u002F.config\u002Fkubectl-ai\u002Ftools.yaml\nEOF\n```\n\nVerify your configuration:\n\n```shell\nkubectl-ai --quiet model\n```\n\n\u003Cdetails>\n\u003Csummary>More configuration Options\u003C\u002Fsummary>\n\nHere's a complete configuration file with all available options and their default values:\n\n```yaml\n# LLM provider configuration\nllmProvider: \"gemini\"               # Default LLM provider\nmodel: \"gemini-2.5-pro-preview-06-05\" # Default model\nskipVerifySSL: false              # Skip SSL verification for LLM API calls\n\n# Tool and permission settings\ntoolConfigPaths: [\"~\u002F.config\u002Fkubectl-ai\u002Ftools.yaml\"]  # Custom tools configuration paths\nskipPermissions: false             # Skip confirmation for resource-modifying commands\nenableToolUseShim: false        # Enable tool use shim for certain models\n\n# MCP configuration\nmcpServer: false                  # Run in MCP server mode\nmcpClient: false                  # Enable MCP client mode\nexternalTools: false             # Discover external MCP tools (requires mcp-server)\n\n# Runtime settings\nmaxIterations: 20                 # Maximum iterations for the agent\nquiet: false                       # Run in non-interactive mode\nremoveWorkdir: false             # Remove temporary working directory after execution\n\n# Kubernetes configuration\nkubeconfig: \"~\u002F.kube\u002Fconfig\"      # Path to kubeconfig file\n\n# UI configuration\nuiType: \"terminal\"                # UI mode: \"terminal\" or \"web\"\nuiListenAddress: \"localhost:8888\" # Address for HTML UI server\n\n# Prompt configuration\npromptTemplateFilePath: \"\"      # Custom prompt template file\nextraPromptPaths: []            # Additional prompt template paths\n\n# Debug and trace settings\ntracePath: \"\u002Ftmp\u002Fkubectl-ai-trace.txt\" # Path to trace file\n```\n\n\u003C\u002Fdetails>\n\nAll these settings can be configured through either:\n\n1. Command line flags (e.g., `--model=gemini-2.5-pro`)\n2. Configuration file (`~\u002F.config\u002Fkubectl-ai\u002Fconfig.yaml`)\n3. Environment variables (e.g., `GEMINI_API_KEY`)\n\nCommand line flags take precedence over configuration file settings.\n\n## Tools\n\n`kubectl-ai` leverages LLMs to suggest and execute Kubernetes operations using a set of powerful tools. It comes with built-in tools like `kubectl` and `bash`.\n\nYou can also extend its capabilities by defining your own custom tools. By default, `kubectl-ai` looks for your tool configurations in `~\u002F.config\u002Fkubectl-ai\u002Ftools.yaml`.\n\nTo specify tools configuration files or directories containing tools configuration files, use:\n\n```sh\n.\u002Fkubectl-ai --custom-tools-config=\u003Cpath-to-tools-directory> \"your prompt here\"\n```\n\nFor further details on how to configure your own tools, [go here](docs\u002Ftools.md).\n\n## Docker Quick Start\n\nThis project provides a Docker image that gives you a standalone environment for running kubectl-ai, including against a GKE cluster.\n\n### Running the container against GKE\n\n#### Step 1: Build the Image\n\nClone the repository and build the image with the following command\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FGoogleCloudPlatform\u002Fkubectl-ai.git\ncd kubectl-ai\ndocker build -t kubectl-ai:latest -f images\u002Fkubectl-ai\u002FDockerfile .\n```\n\n#### Step 2: Connect to Your GKE Cluster\n\nSet up application default credentials and connect to your GKE cluster.\n\n```bash\ngcloud auth application-default login # If in a gcloud shell this is not necessary\ngcloud container clusters get-credentials \u003Ccluster-name> --zone \u003Czone>\n```\n\n#### Step 3: Run the kubectl-ai container\n\nBelow is a sample command that can be used to launch the container with a locally hosted web-ui. Be sure to replace the placeholder values with your specific Google Cloud project ID and location. Note you do not need to mount the gcloud config directory if you're on a cloudshell machine.\n\n```bash\ndocker run --rm -it -p 8080:8080 -v ~\u002F.kube:\u002Froot\u002F.kube -v ~\u002F.config\u002Fgcloud:\u002Froot\u002F.config\u002Fgcloud -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\n```\n\nFor more info about running from the container image see [CONTAINER.md](CONTAINER.md)\n\n## MCP Client Mode\n\n> **Note:** MCP Client Mode is available in `kubectl-ai` version v0.0.12 and onwards.\n\n`kubectl-ai` can connect to external [MCP](https:\u002F\u002Fmodelcontextprotocol.io\u002Fexamples) Servers to access additional tools in addition to built-in tools.\n\n### Quick Start with MCP Client\n\nEnable MCP client mode:\n\n```bash\nkubectl-ai --mcp-client\n```\n\n### MCP Client Configuration\n\nCreate or edit `~\u002F.config\u002Fkubectl-ai\u002Fmcp.yaml` to customize MCP servers:\n\n```yaml\nservers:\n  # Local MCP server (stdio-based)\n  # sequential-thinking: Advanced reasoning and step-by-step analysis\n  - name: sequential-thinking\n    command: npx\n    args:\n      - -y\n      - \"@modelcontextprotocol\u002Fserver-sequential-thinking\"\n  \n  # Remote MCP server (HTTP-based)\n  - name: cloudflare-documentation\n    url: https:\u002F\u002Fdocs.mcp.cloudflare.com\u002Fmcp\n    \n  # Optional: Remote MCP server with authentication\n  - name: custom-api\n    url: https:\u002F\u002Fapi.example.com\u002Fmcp\n    auth:\n      type: \"bearer\"\n      token: \"${MCP_TOKEN}\"\n```\n\nThe system automatically:\n\n- Converts parameter names (snake_case → camelCase)\n- Handles type conversion (strings → numbers\u002Fbooleans when appropriate)\n- Provides fallback behavior for unknown servers\n\nNo additional setup required - just use the `--mcp-client` flag and the AI will have access to all configured MCP tools.\n\n📖 **For detailed configuration options, troubleshooting, and advanced features for MCP Client mode, see the [MCP Client Documentation](docs\u002Fmcp-client.md).**\n\n📖 **For multi-server orchestration and security automation examples, see the [MCP Client Integration Guide](docs\u002Fmcp-client.md).**\n\n## Extras\n\nYou can use the following special keywords for specific actions:\n\n- `model`: Display the currently selected model.\n- `models`: List all available models.\n- `tools`: List all available tools.\n- `version`: Display the `kubectl-ai` version.\n- `reset`: Clear the conversational context.\n- `clear`: Clear the terminal screen.\n- `exit` or `quit`: Terminate the interactive shell (Ctrl+C also works).\n\n### Invoking as kubectl plugin\n\nYou can also run `kubectl ai`. `kubectl` finds any executable file in your `PATH` whose name begins with `kubectl-` as a [plugin](https:\u002F\u002Fkubernetes.io\u002Fdocs\u002Ftasks\u002Fextend-kubectl\u002Fkubectl-plugins\u002F).\n\n## MCP Server Mode\n\n`kubectl-ai` can act as an MCP server that exposes kubectl tools to other MCP clients (like Claude, Cursor, or VS Code). The server can run in two modes:\n\n### Basic MCP Server (Built-in tools only)\n\nExpose only kubectl-ai's native Kubernetes tools:\n\n```bash\nkubectl-ai --mcp-server\n```\n\n### Enhanced MCP Server (With external tool discovery)\n\nAdditionally discover and expose tools from other MCP servers as a unified interface:\n\n```bash\nkubectl-ai --mcp-server --external-tools\n```\n\nThis creates a powerful **tool aggregation hub** where kubectl-ai acts as both:\n\n- **MCP Server**: Exposing kubectl tools to clients\n- **MCP Client**: Consuming tools from other MCP servers\n\nTo serve clients over HTTP using the streamable transport, run:\n\n```bash\nkubectl-ai --mcp-server --mcp-server-mode streamable-http --http-port 9080\n```\n\nThis starts an MCP endpoint at `http:\u002F\u002Flocalhost:9080\u002Fmcp`.\n\nThe enhanced mode provides AI clients with access to both Kubernetes operations and general-purpose tools (filesystem, web search, databases, etc.) through a single MCP endpoint.\n\n📖 **For detailed configuration, examples, and troubleshooting, see the [MCP Server Documentation](docs\u002Fmcp-server.md).**\n\n## Start Contributing\n\nWe welcome contributions to `kubectl-ai` from the community. Take a look at our\n[contribution guide](contributing.md) to get started.\n\n## Learning Resources\n\n### Talks and Presentations\n\n- [From Natural Language to K8s Operations: The MCP Architecture and Practice of kubectl-ai](https:\u002F\u002Fblog.wu-boy.com\u002F2025\u002F10\u002Ffrom-natural-language-to-k8s-operations-the-mcp-architecture-and-practice-of-kubectl-ai-en) - A comprehensive presentation covering the architecture and practical usage of kubectl-ai with MCP (Model Context Protocol).\n\n---\n\n*Note: This is not an officially supported Google product. This project is not\neligible for the [Google Open Source Software Vulnerability Rewards\nProgram](https:\u002F\u002Fbughunters.google.com\u002Fopen-source-security).*\n","`kubectl-ai` 是一个基于人工智能的 Kubernetes 辅助工具，旨在通过自然语言处理用户意图并转化为精确的 Kubernetes 操作，从而简化集群管理。该项目采用 Go 语言开发，利用了多种 AI 模型（如 Gemini、VertexAI 和 OpenAI 等）来增强其智能解析能力，支持从简单的状态查询到复杂的配置调整等多种应用场景。适合那些希望提高工作效率、减少学习曲线或需要更直观方式与 Kubernetes 交互的开发者和运维人员使用。此外，它还提供了灵活的安装选项，包括直接下载、Krew 插件安装以及 NixOS 包管理器集成等，方便不同环境下的快速部署。",2,"2026-06-11 03:25:22","top_topic"]