Kubectl-AI提升集群应用部署、故障运维效率

面对日益复杂的云原生环境，传统的Kubernetes运维模式在部署效率、故障定位面临挑战。繁琐的Kubectl命令、YAML配置文件参数以及依赖经验的故障排查，已成为制约运维团队提效降本的主要瓶颈。通过kubectl-ai 智能运维工具，借助大语言模型能力将自然语言意图自动转换为可执行的kubectl命令，实现对KCE容器集群的智能管控。

kubectl-ai工具可实现：

• 降低操作门槛：支持使用自然语言描述运维需求（例如：“查看所有异常Pod”或“扩容Deployment A到5个副本”），使初级工程师也能安全、高效地完成复杂操作，显著减少人为失误。

• 加速故障定位：kubectl-ai工具通过分析事件、日志及资源状态，快速定位问题根因（例如：“Pod因探针超时而被重启，建议延长超时阈值”），并提供修复建议。

本文档旨介绍kubectl-ai在KCE容器集群中的安装与配置。通过该工具，您可以显著降低运维复杂度、加速问题定位，提升集群的运维效率与智能化水平。

部署前提

• 首次使用金山云容器服务2.0，需要为金山云账号赋予系统角色权限，才能正常创建集群，关于如何授权，请参考角色授权。

• 使用金山云容器服务2.0，创建一个正常运行的KCE2.0容器集群，关于如何创建集群，请参考创建集群。

• 在星流平台- 模型API服务获取API Key，关于如何使用模型API服务，请参考快速上手模型API服务。

部署说明

本文将使用大模型deepseek-v3-0324为例，您可按需、按费用选择其他大语言模型。

安装Kubectl-ai

在Linux和MacOS环境快速安装

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

在Linux、MacOS、Windows环境手动安装

• 从发布页面下载适用于目标机器的最新版本

• 解压发行版，使二进制文件可执行，并将其移动到 $PATH 中的目录

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

安装成功如下图显示

可执行以下命令，查看kubectl-ai相关指令

root@vm11-0-100-48:~# kubectl-ai --help
kubectl-ai is a command-line tool that allows you to interact with your Kubernetes cluster using natural language queries. It leverages large language models to understand your intent and translate it into kubectl

Usage:
  kubectl-ai [flags]
  kubectl-ai [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  version     Print the version number of kubectl-ai

Flags:
      --alsologtostderr                    log to standard error as well as files (no effect when -logtostderr=true)
      --custom-tools-config stringArray    path to custom tools config file or directory (default [{CONFIG}/kubectl-ai/tools.yaml,{HOME}/.config/kubectl-ai/tools.yaml])
      --delete-session string              delete a session by ID
      --enable-tool-use-shim               enable tool use shim
      --external-tools                     in MCP server mode, discover and expose external MCP tools
      --extra-prompt-paths stringArray     extra prompt template paths
  -h, --help                               help for kubectl-ai
      --http-port int                      port for the HTTP endpoint in MCP server mode (used with --mcp-server when --mcp-server-mode is streamable-http) (default 9080)
      --kubeconfig string                  path to kubeconfig file
      --list-sessions                      list all available sessions
      --llm-provider string                language model provider (default "gemini")
      --max-iterations int                 maximum number of iterations agent will try before giving up (default 20)
      --mcp-client                         enable MCP client mode to connect to external MCP servers
      --mcp-server                         run in MCP server mode
      --mcp-server-mode string             mode of the MCP server. Supported values: stdio, streamable-http (default "stdio")
      --model string                       language model e.g. gemini-2.0-flash-thinking-exp-01-21, gemini-2.0-flash (default "gemini-2.5-pro")
      --new-session                        create a new session
      --prompt-template-file-path string   path to custom prompt template file
      --quiet                              run in non-interactive mode, requires a query to be provided as a positional argument
      --remove-workdir                     remove the temporary working directory after execution
      --resume-session string              ID of session to resume (use 'latest' for the most recent session)
      --show-tool-output                   show tool output in the terminal UI
      --skip-permissions                   (dangerous) skip asking for confirmation before executing kubectl commands that modify resources
      --skip-verify-ssl                    skip verifying the SSL certificate of the LLM provider
      --trace-path string                  path to the trace file (default "/tmp/kubectl-ai-trace.txt")
      --ui-listen-address string           address to listen for the HTML UI. (default "localhost:8888")
      --ui-type UIType                     user interface type to use. Supported values: terminal, web, tui. (default terminal)
  -v, --v Level                            number for the log level verbosity

Use "kubectl-ai [command] --help" for more information about a command.

为当前登录环境配置Kubeconfig文件

可以在KCE2.0控制台获取Kubeconfig，保存至所在环境的$HOME/.kube/config文件中。该文件用于存储所要管理集群的访问凭证。kubectl会根据该文件连接至集群。

1. 登录金山云容器服务2.0，选择目标集群，进入集群详情

2. 进入集群信息页-APIServer访问，获取集群内网访问/外网访问的Kubeconfig文件

3. 将复制的集群凭证内容粘贴至$HOME/.kube/config文件中，保存并退出

如果$HOME/目录下没有.kube目录和config文件，请自行创建。

使用以下命令验证集群连通性，可查询出Node节点列表，代表可以连通集群

root@vm11-0-100-48:~# kubectl get no
NAME          STATUS   ROLES    AGE   VERSION
11.0.100.48   Ready    worker   33d   v1.32.6

为kubectl-ai配置API Key

登录星流平台-API服务-模型广场，选择所需模型的API Key及OPENAI_ENDPOINT

在环境中配置API key，执行以下命令

export OPENAI_API_KEY=<上一步获取的API Key>
export OPENAI_ENDPOINT=https://kspmas.ksyun.com/v1/chat/completions
kubectl-ai --llm-provider=openai --model=deepseek-v3-0324

预期输出如下：

root@vm11-0-100-48:~# kubectl-ai --llm-provider=openai --model=deepseek-v3-0324

  Hey there, what can I help you with today?

>>>

功能验证

1. 指定容器镜像快速创建Nginx服务，并对外暴露服务

1. 创建Ngxin Deployement，输入以下指令：

在Namespace Default下创建一个名字为Nginx1的Deployment，使用镜像hub.kce.ksyun.com/lzj_ns/nginx:latest，imagePullSecrets名为ksyunregistrykey

说明：由于需要通过kubectl命令创建资源，请根据实际输出的结果，在出现Do you want to proceed ?的提示询问是否执行kubectl命令后，按回车键回复1、2、3中的一个数字，分别代表执行、执行并不再提问、停止执行。后续步骤中均以回复数字1或Yes（即执行）作为示例。

预期输出：

2. 创建Loadbalance Service暴露Nginx服务，并通过浏览器浏览

为Namespace Default下的Deployment nginx1创建一个loadbalance类型的service

预期输出：

验证效果：

2. 对Deployment nginx1执行横向扩容，副本数为5

输入以下内容：

输出Namespace default下的deployement nginx1的副本数，并对其进行扩容，目标副本数为5

预期输出：

3. 故障模拟

本场景将模拟以下常见错误：

1. NodeSelector不匹配：将Deployement的Pod指定调度在包含标签env：test 的Node上，但集群内无任何Node包含此标签，因为Deployement Pod处于Pending状态

2. readinessProbe端口错误：readinessProbe检查8080端口，应用实际使用80，就绪探针会一直失败，Pod状态为NotReady。

使用以下两个Deployement模拟故障

# 模拟NodeSelector不匹配
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-err1
  namespace: default
  labels:
    app: nginx-err1
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-err1
  template:
    metadata:
      labels:
        app: nginx-err1
    spec:
      nodeSelector:
        env: test
      containers:
      - name: nginx
        image: hub.kce.ksyun.com/lzj_ns/nginx:latest
        ports:
        - containerPort: 80
      imagePullSecrets:
      - name: ksyunregistrykey
---
# readinessProbe端口错误
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-err2
  namespace: default
  labels:
    app: nginx-err2
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-err2
  template:
    metadata:
      labels:
        app: nginx-err2
    spec:
      containers:
      - name: nginx
        image: hub.kce.ksyun.com/lzj_ns/nginx:latest
        ports:
        - containerPort: 80
        readinessProbe:
          tcpSocket:
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 10
      imagePullSecrets:
      - name: ksyunregistrykey

1. 使用kubectl执行以下命令，创建示例资源模拟故障场景

kubectl apply -f error.yaml

2. 使用kubectl-ai输入以下指令，获取Deployement nginx-err1、nginx-err2的信息

输入以下内容：

获取Namespace default下deployment nginx-err1、nginx-err2的信息

预期输出：

3. 使用kubectl-ai修复问题

输入以下内容：

请帮助我修复Namespace default下deployment nginx-err1、nginx-err2的异常问题

预期输出：

查看效果：