From Natural Language to K8s Operations: The MCP Architecture and Practice of kubectl-ai

kubectl-ai is a revolutionary open-source project that seamlessly integrates large language models with Kubernetes operations, enabling users to interact intelligently with K8s clusters through natural language. This talk will delve into how this innovative technology addresses the complexity of traditional kubectl commands, significantly lowering the barrier to using Kubernetes.

We will provide a detailed introduction to the core architecture of kubectl-ai, including its Agent dialogue management system, extensible tools framework, and the inventive application of the MCP (Model Context Protocol). The tool supports multiple LLM providers, ranging from Google Gemini to locally deployed models, and features a dual MCP mode design.

Audience Takeaways:

* Deploying and configuring the kubectl-ai tool
* Performing daily Kubernetes operations using natural language
* Extending tool functionality to meet enterprise needs
* Understanding MCP protocol applications in AI tool integration

Event Link: https://k8s.ithome.com.tw/2025/session-page/4096

Transcript

1. kubectl-ai: Natural Language Operations for Kubernetes (AI Powered K8s Assistant) Bo-Yi Wu (GDE) https://blog.wu-boy.com/ 2025/10/23 16:00 - 16:40 KubeSummit 2025 kubectl-ai Repo
2. Outline • Why do we use the kuebectl-ai Assistant? • Demo of three core features • Technical Architecture
3. Who has ever spent over 30 minutes troubleshooting why a Pod failed to start? (kubectl cheat sheet?) IUUQTLVCFSOFUFTJPEPDTSFGFSFODFLVCFDUMRVJDLSFGFSFODF
4. .VMUJQMF
   UFBNT
   BSF
   TJNVMUBOFPVTMZ
   SFBDIJOH
   PVU
   UP
   *5
   FOHJOFFST
   GPS
   IFMQ
   SFTPMWJOH
   ,VCFSOFUFT
   JTTVFT Terminal 1: kubectl get pods -n prod Terminal 2: kubectl describe pod nginx-xxx Terminal 3: kubectl logs nginx-xxx --previous Terminal 4: kubectl get events -n prod Terminal 5: kubectl get service nginx Terminal 6: curl -v http://nginx-service
5. kubectl fl ow vs. kubectl-ai Traditional Method kubectl-ai 🔍 Need to remember 20+ kubectl commands 💬 Natural language conversation 🔄 Manually execute multiple related commands 🤖 AI automatic reasoning and decision- making 📝 Need to write complex YAML ✨ Just describe your needs ⏱ Takes 15–30 minutes to troubleshoot ⚡ Get answers in 2–5 minutes
6. What is kubectl-ai?
7. What is kubectl-ai? ✅ AI plugin for kubectl ✅ Supports 8+ mainstream LLMs (Gemini/GPT-4/Claude/Grok) ✅ Open source (Apache 2.0) - Google Cloud Platform ✅ Over 95% evaluation success rate ✅ MCP protocol for integration with third-party tools IUUQTHJUIVCDPN(PPHMF$MPVE1MBUGPSNLVCFDUMBJCMPCNBJOLTCFODINE
8. Demo of Three Core Features • Intelligent Troubleshooting • MCP Client Integration • MCP Server Capability
9. Demo 01 (Intelligent Troubleshooting)
10. apiVersion: apps/v1 kind: Deployment metadata: name: nginx spec: replicas: 3 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:wrong-tag # wrong tag resources: requests: memory: "10Gi" # wrong value --- apiVersion: v1 kind: Service metadata: name: nginx-svc spec: selector: app: nginx ports: - port: 80 Scenario: Newly deployed nginx service is not functioning properly Objective: Demonstrate how AI can quickly identify the issue and suggest solutions
11. kubectl-ai \ "What is wrong with the Nginx service? Why is it not accessible?"
13. 1SPCMFN
    *EFOUJ fi FE
14. 4PMVUJPOT
    GSPN
    LVCFDUMBJ
15. 1SPCMFN
    3FTPMWFE
    GSPN
    LVCFDUMBJ
16. Demo 02 (MCP Client Integration)
17. $SFBUFE
    CZ
    %BJMZ%PTFPG%4DPN 8IBU
    JT
    .$1
    $MJFOU
18. Challenge & Solution for Kubernetes Security Audits Challenge: • Manual execution of multiple security tools across systems • Time-consuming data collection and correlation by hand • Manual report creation and distribution • High risk of human error and resource consumption Solution: One-command orchestration across multiple MCP servers • Single command triggers automated security tools seamlessly • Automatic data aggregation and unified result reporting • Effortless report generation and distribution • Minimized manual intervention for higher efficiency and accuracy • Scalable to multi-server environments Benefits: • Greatly increased audit speed and reliability • Lower human error and operational costs • Enhanced automation and standardization of security monitoring
19.    
20. kubectl-ai —mcp-client \ "Scan the RBAC permissions in the srv-gitea namespace, identify overprivileged ServiceAccounts, and create a Jira issue in the GAIA project with a summary of the fi ndings included in the description."
21. 6TF
    .$1
    5PPM
    QFSNJ fl PX IUUQTHJUIVCDPNUVUSBOTFQFSNJ fl PX
22. 6TF
    .$1
    5PPM
    DSFBUF
    +JSB
    JTTVF
23. Advanced Work fl ows 4DBO
    3#"$ $SFBUF
    +JSB
    5JDLFU &NBJM
    4FDVSJUZ
    5FBN 1PTU
    UP
    5FBNT
24. Demo 03 (MCP Server Capability)
25. $SFBUFE
    CZ
    %BJMZ%PTFPG%4DPN 8IBU
    JT
    .$1
    4FSWFS
26. kubectl-ai —mcp-server \ —mcp-server-mode \ streamable-http \ —http-port 9080
27. Claude Code CLI integrate with 1. Permi fl ow MCP 2. kubectl-ai MCP
28. “Scan the RBAC permissions in the srv-gitea namespace, identify overprivileged ServiceAccounts” 1SPNQU
30. kubectl-ai —mcp-server \ —mcp-server-mode \ streamable-http \ —http-port 9080 \ —external-tools - All kubectl-ai built-in tools (kubectl, cluster analysis, etc.) - Tools from external MCP servers (filesystem, web search, etc.) - Unified interface for all tools through a single MCP endpoint
31. Demo (kubectl-ai MCP server Acts as a Tool Aggregator)
33.   
34. Technical Architecture
36. %FNP
     %FNP
     %FNP
    
37. MCP Manager HTTPClient and StdioClient
38. Three Authentication Mode • Bearer Token • Basic Auth • API Key (custom header)
39.  .$1
    4FSWFS .$1
    $MJFOU 0"VUI
    'MPX
40. *OJUJBM
    .$1
    .BOHFS
42. type Agent struct { // === Communication Channels === Input chan any // Receives UI input Output chan any // Sends messages to UI // === Execution Mode === RunOnce bool // Non-interactive mode flag InitialQuery string // Initial query // === Agentic Loop State === pendingFunctionCalls []ToolCallAnalysis // Pending tool executions currChatContent []any // Current chat contents currIteration int // Current iteration count // === LLM Integration === LLM gollm.Client // LLM client llmChat gollm.Chat // Chat session Model string // Model name Provider string // Provider (openai/gemini/bedrock) // === Tool System === Tools tools.Tools // Tool registry EnableToolUseShim bool // Tool use shim mode // === MCP Support === MCPClientEnabled bool // MCP client enabled mcpManager *mcp.Manager // MCP manager // === Session Management === session *api.Session // Current session ChatMessageStore api.ChatMessageStore // Message persistence sessionMu sync.Mutex // Session lock // === Permissions & Configurations === SkipPermissions bool // Skip permission checks MaxIterations int // Maximum iterations Kubeconfig string // Kubernetes config path workDir string // Working directory } "HFOU
    4USVDUVSF
    
47. type ToolCallAnalysis struct { FunctionCall gollm.FunctionCall // Original function call returned by LLM ParsedToolCall *tools.ToolCall // Parsed tool invocation IsInteractive bool // Whether interactive input is required IsInteractiveError error // Error during interactive check ModifiesResourceStr string // "yes"/"no"/"unknown" } func (c *Agent) analyzeToolCalls(ctx context.Context, toolCalls []gollm.FunctionCall) ([]ToolCallAnalysis, error) { toolCallAnalysis := make([]ToolCallAnalysis, len(toolCalls)) for i, call := range toolCalls { toolCallAnalysis[i].FunctionCall = call // Parse tool invocation toolCall, err := c.Tools.ParseToolInvocation(ctx, call.Name, call.Arguments) if err != nil { return nil, fmt.Errorf("parsing tool call: %w", err) } // Check whether interaction is needed (e.g., vim, nano, etc.) toolCallAnalysis[i].IsInteractive, err = toolCall.GetTool().IsInteractive(call.Arguments) if err != nil { toolCallAnalysis[i].IsInteractiveError = err } // Check whether resources are modified (requires permission confirmation) toolCallAnalysis[i].ModifiesResourceStr = toolCall.GetTool().CheckModifiesResource(call.Arguments) toolCallAnalysis[i].ParsedToolCall = toolCall } return toolCallAnalysis, nil } ✅
    4BGF
    UP
    FYFDVUF
    ⚠
    6TFS
    DPO fi SNBUJPO
    SFRVJSFE
    🚫
    4IPVME
    CF
    CMPDLFE
48. gollm.FunctionCall{ ID: "call_abc123", Name: "kubectl", Arguments: map[string]any{ "command": "delete pod nginx-abc -n production", }, } toolCall, err := c.Tools.ParseToolInvocation(ctx, call.Name, call.Arguments) if err != nil { return nil, fmt.Errorf("error parsing tool call: %w", err) }  
49. toolCallAnalysis[i].IsInteractive, err = toolCall.GetTool().IsInteractive(call.Arguments) if err != nil { toolCallAnalysis[i].IsInteractiveError = err }  8IZ
    OFFE
    UP
    DIFDL
    JOUFSBDUJWF
    DPNNBOE 🚫 Stuck: Agent keeps waiting for user input 🚫 Can’t get output: Terminal took over 🚫 Workflow broken: Agent loop got interrupted toolCallAnalysis[i].ModifiesResourceStr = toolCall.GetTool().CheckModifiesResource(call.Arguments)  writeOps = map[string]bool{ "create": true, "apply": true, "edit": true, "delete": true, "patch": true, "replace": true, "scale": true, "autoscale": true, "expose": true, "run": true, "exec": true, "set": true, "label": true, "annotate": true, "taint": true, "drain": true, "cordon": true, "uncordon": true, "debug": true, "attach": true, "cp": true, "reconcile": true, "approve": true, "deny": true, "certificate": true, } 8IZ
    OFFE
    UP
    DIFDL
    NPEJGZ
    SFTPVSDF
    DPNNBOE
50. $POWFSTBUJPO
    'MPX
51. Thanks