KnoAI 技术站

主题

Rancher 常用命令速查（kubectl Shell 版） ​

  • 整理日期：2026-08-13
  • 环境：Rancher v2.14.3（sza 管理集群，域名 ai-ear.cn）
  • 入口：Rancher UI 右上角 Kubectl Shell 图标（默认操作 local 管理集群）；操作下游集群需先下载对应集群的 kubeconfig

一、集群相关 ​

bash
# 所有 v2 供给集群（RKE2/K3s 自定义/节点驱动集群），-A 看全部 fleet 命名空间
kubectl get clusters.provisioning.cattle.io -A

# 所有集群（含导入集群、托管集群）
kubectl get clusters.management.cattle.io

# Fleet 视角的集群
kubectl get clusters.fleet.cattle.io -A

# 查看某集群详情（K8s 版本、registry 配置等）
kubectl get clusters.provisioning.cattle.io <cluster> -n fleet-default -o yaml

# 仅看集群 K8s 版本
kubectl get clusters.provisioning.cattle.io -A \
  -o custom-columns='NAME:.metadata.name,NS:.metadata.namespace,VER:.spec.kubernetesVersion,READY:.status.ready'

# 删除集群（谨慎，节点需另行清理 /var/lib/rancher、/etc/rancher）
kubectl delete clusters.provisioning.cattle.io <cluster> -n fleet-default

二、节点 / 机器相关 ​

bash
# 所有 machine（CAPI 视角的节点，含状态、所在集群）
kubectl get machines.cluster.x-k8s.io -A

# 管理集群（local）的 K8s 节点
kubectl get nodes -o wide

# 查看某 machine 的 plan 是否下发（DATA=0 说明 planner 未生成 plan）
kubectl get secret <machine>-machine-plan -n fleet-default

# 查看 machine 详情与状态条件
kubectl describe machine <machine> -n fleet-default

# RKE2 控制平面状态（含具体等待原因）
kubectl get rkecontrolplane -A
kubectl get rkecontrolplane <cluster> -n fleet-default -o jsonpath='{.status.conditions}'

下游集群节点需在 UI 切换集群后用 Kubectl Shell，或：

bash
# 使用下游集群 kubeconfig
kubectl --kubeconfig=<cluster>.yaml get nodes -o wide

三、下游集群 workload / agent ​

bash
# 下游集群中的 cluster-agent（Rancher 与下游通信组件）
kubectl --kubeconfig=<cluster>.yaml -n cattle-system get pods
kubectl --kubeconfig=<cluster>.yaml -n cattle-system logs deploy/cattle-cluster-agent --tail=100

# 下游集群 system-agent 相关命名空间
kubectl --kubeconfig=<cluster>.yaml get ns | grep cattle

四、Rancher 服务端 / Fleet 日志 ​

bash
# Rancher 主日志（planner 报错、版本元数据刷新都在这里）
kubectl -n cattle-system logs deploy/rancher --tail=400 | grep -iE 'error|planner'

# Fleet controller / agent
kubectl -n cattle-fleet-system get pods
kubectl -n cattle-fleet-system logs deploy/fleet-controller --tail=100
kubectl -n cattle-fleet-local-system logs -l app=fleet-agent --tail=100

# 重启 rancher（如改了设置想立即生效）
kubectl rollout restart deploy/rancher -n cattle-system

五、节点侧排查命令（SSH 到下游节点） ​

bash
# system-agent 日志（plan 下发与执行情况）
sudo journalctl -u rancher-system-agent --no-pager -n 50

# rke2-server / rke2-agent 日志
sudo journalctl -u rke2-server --no-pager -n 50
sudo journalctl -u rke2-agent  --no-pager -n 50

# agent 连接信息（连的哪个 Rancher、watch 哪个 secret）
sudo cat /var/lib/rancher/agent/rancher2_connection_info.json

# 节点上已拉取的 RKE2 镜像
sudo /var/lib/rancher/rke2/bin/crictl --runtime-endpoint unix:///run/k3s/containerd/containerd.sock images

六、全局设置与版本管理 ​

bash
# 列出所有全局设置
kubectl get settings.management.cattle.io

# 查看/修改某项设置（如固定 RKE2 版本）
kubectl get settings.management.cattle.io rke2-default-version -o yaml
kubectl patch settings.management.cattle.io rke2-default-version --type merge \
  -p '{"value":"v1.35.6+rke2r1"}'

# 版本元数据刷新配置（refresh-interval-minutes=0 表示禁用自动刷新）
kubectl get settings.management.cattle.io rke-metadata-config -o jsonpath='{.value}'

# 私有镜像仓库
kubectl get settings.management.cattle.io system-default-registry -o jsonpath='{.value}'

七、私有仓库 / 镜像验证 ​

bash
# 验证 Harbor 中某镜像的 tag 列表
curl -s http://<registry>/v2/<repo>/tags/list -u 'user:xxx'

# 例：查看 system-agent-installer-rke2 有哪些版本
curl -s http://192.168.122.156:30000/v2/rancher/system-agent-installer-rke2/tags/list -u 'user:xxx'

注意：RKE2 版本号 v1.35.6+rke2r1 对应镜像 tag 为 v1.35.6-rke2r1（+ 变 -）。