RKE2 + Rancher 方式部署 K8s 集群

⚠️ 来源 install/kubernetes/rancher/rke2/rke2.md 第 1 行标注「本文是测试文档，暂时未测试」。本篇按原文整理，命令与版本请在自己的环境再验证一遍，不要直接照搬到生产。

本篇说明如何用 Rancher Server 纳管、用 RKE2 部署一套 Kubernetes 集群，作为 CubeStudio 的运行底座。RKE2 自带一套 containerd 实例（与主机系统自带的 containerd 相互独立），本篇重点说明它的路径、配置改法与常用排查命令。

RKE2 是 Rancher 的下一代 K8s 发行版，内置 containerd，由 rke2-server / rke2-agent 进程统一管理，主机本身不需要再单独安装 containerd。

一、部署 Rancher Server

用 nerdctl（或 docker）以容器方式启动 Rancher Server。下面命令把镜像默认仓库指向阿里云加速。

# 可选：预先把 k3s 内置镜像放到 rancher 数据目录（离线/加速用）
# mkdir -p /data/rancher/k3s/agent/images/
# wget https://cube-studio.oss-cn-hangzhou.aliyuncs.com/install/k3s-airgap-images.tar -O /data/rancher/k3s/agent/images/k3s-airgap-images.tar
# nerdctl network create cube-studio

export RANCHER_CONTAINER_TAG=v2.8.5
export PASSWORD=cube-studio

nerdctl run -d --privileged --restart=unless-stopped -p 443:443 \
  --name=myrancher \
  -e AUDIT_LEVEL=3 \
  -e CATTLE_SYSTEM_DEFAULT_REGISTRY=registry.cn-hangzhou.aliyuncs.com \
  -e CATTLE_BOOTSTRAP_PASSWORD=$PASSWORD \
  registry.cn-hangzhou.aliyuncs.com/rancher/rancher:$RANCHER_CONTAINER_TAG

启动后：

• 打开 https://<主机IP>:443/，等待 Web 界面就绪（预计 1~10 分钟）。
• 用 CATTLE_BOOTSTRAP_PASSWORD 设置的密码（这里是 cube-studio）登录。

环境变量含义：CATTLE_SYSTEM_DEFAULT_REGISTRY 让 Rancher 的系统组件走阿里云镜像源；AUDIT_LEVEL=3 开审计日志；CATTLE_BOOTSTRAP_PASSWORD 是首次登录的初始密码。Rancher 版本 v2.8.5 为示例值，可按需调整。

二、用 Rancher 创建 RKE2 集群

在 Rancher Web 界面新建一个 RKE2 集群，注意以下要点：

• K8s 版本：建议 1.25。

• 不要部署 nginx-ingress（CubeStudio 用 istio 做网关）。

• 镜像仓库：配置 registry.cn-hangzhou.aliyuncs.com，Rancher 的系统组件会走阿里云。

• 镜像加速 Mirror：让 K8s 拉镜像走加速器：

  镜像仓库主机名	mirror 地址
  *（所有）	docker.m.daocloud.io
  docker.io	docker.m.daocloud.io

• API server 参数（高级选项里加）：

  --service-node-port-range=1-65535
  

注意：原文「高级选项-补充的」一节给过一段「kubelet 参数：使用主机的 containerd」的配置（container-runtime=remote、containerd=/run/containerd/containerd.sock 等），并自带「配置这个会出错」的标注（见 install/kubernetes/rancher/rke2/containerd-rke2.md）。RKE2 默认使用自带的 containerd（socket 在 /run/k3s/containerd/containerd.sock，见 install/kubernetes/rancher/rke2/rke2.md:60），不要把它改成主机的 /run/containerd/containerd.sock，否则启动异常。请勿照抄那段 kubelet 参数。

部署完成后的清理

进入 Rancher Web 界面「全部命名空间 → Pod」页面，过滤 10.4 网段的所有 Pod 并全部删除。原因：这些不是 K8s 集群网关的 Pod，而是 nerdctl 网络残留。

三、（可选）主机系统基线设置

如果需要开启 IPVS 模式并配置内核网络转发参数，可在每台机器执行：

apt install ipset ipvsadm -y

# 加载 ip_vs 系列内核模块
sudo modprobe ip_vs
sudo modprobe ip_vs_rr
sudo modprobe ip_vs_wrr
sudo modprobe ip_vs_lc
sudo modprobe ip_vs_wlc
sudo modprobe ip_vs_lblc
sudo modprobe ip_vs_lblcr
sudo modprobe ip_vs_sh
sudo modprobe ip_vs_dh
sudo modprobe ip_vs_sed
sudo modprobe ip_vs_nq
lsmod | grep ip_vs

# 网络转发 sysctl
cat > /etc/sysctl.d/k8s.conf << EOF
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
vm.swappiness = 0
EOF

modprobe br_netfilter
lsmod | grep br_netfilter

四、Rancher Server 内自带的 k3s 镜像

Rancher Server 容器内自带一份 k3s air-gap 镜像包，可放到数据目录加速/离线安装：

mkdir -p /data/rancher/k3s/agent/images/
wget https://cube-studio.oss-cn-hangzhou.aliyuncs.com/install/k3s-airgap-images.tar \
  -O /data/rancher/k3s/agent/images/k3s-airgap-images.tar

# 也可从 rancher 镜像里直接 cp 出来：
# docker run --rm --entrypoint "" -v $(pwd):/output rancher/rancher:v2.8.5 \
#   cp /var/lib/rancher/k3s/agent/images/k3s-airgap-images.tar /output/k3s-airgap-images.tar
# cp k3s-airgap-images.tar /data/rancher/k3s/agent/images/

五、修改 RKE2 的 containerd 配置

RKE2 的 containerd 配置由 rke2-server 在启动时从模板 config.toml.tmpl 生成。要让它支持 certs.d 镜像 mirror，需要追加 config_path：

# 用现有 config.toml 作为模板起点
cp /var/lib/rancher/rke2/agent/etc/containerd/config.toml \
   /var/lib/rancher/rke2/agent/etc/containerd/config.toml.tmpl

# 追加 registry config_path
tee -a /var/lib/rancher/rke2/agent/etc/containerd/config.toml.tmpl << 'EOF'
[plugins."io.containerd.grpc.v1.cri".registry]
  config_path = "/etc/containerd/certs.d"
EOF

# 改完重启 rke2-server，containerd 会随之重生成配置并重启
systemctl restart rke2-server

六、RKE2 的目录与运行机制（重点）

RKE2 自带 containerd 实例，与主机系统的 containerd 完全独立，关键路径如下：

要点：

• RKE2 的 containerd 实例通过 rke2-server 管理，不要自己手动管它；改了配置就 systemctl restart rke2-server。
• RKE2 集群上启动的 Pod 使用 RKE2 自带的 containerd 实例，不用主机系统的，所以主机本身不需要安装 containerd。

七、kubeconfig 与 kubectl

RKE2 把 kubeconfig 写在 /etc/rancher/rke2/rke2.yaml，kubectl 在自带 bin 目录：

export KUBECONFIG=/etc/rancher/rke2/rke2.yaml
/var/lib/rancher/rke2/bin/kubectl get nodes

# 或直接指定 kubeconfig
/var/lib/rancher/rke2/bin/kubectl --kubeconfig /etc/rancher/rke2/rke2.yaml get nodes

八、查看与排查 RKE2 的 containerd

# 导出当前生效的 containerd 配置
/var/lib/rancher/rke2/bin/containerd config dump

# 用 ctr 直连 RKE2 的 containerd socket 看容器/镜像（注意 namespace=k8s.io）
/var/lib/rancher/rke2/bin/ctr --address /run/k3s/containerd/containerd.sock --namespace k8s.io container ls
/var/lib/rancher/rke2/bin/ctr --address /run/k3s/containerd/containerd.sock --namespace k8s.io images ls

# 让 crictl 默认走 RKE2 的配置
echo "export CRI_CONFIG_FILE=/var/lib/rancher/rke2/agent/etc/crictl.yaml" >> /etc/profile
source /etc/profile
cp /var/lib/rancher/rke2/bin/crictl /usr/local/bin/
crictl ps

# 或显式指定配置 / runtime endpoint
/var/lib/rancher/rke2/bin/crictl --config /var/lib/rancher/rke2/agent/etc/crictl.yaml ps
/var/lib/rancher/rke2/bin/crictl --runtime-endpoint unix:///run/k3s/containerd/containerd.sock ps -a

# 改完配置统一重启
systemctl restart rke2-server

九、组件、日志与卸载

组件与日志

# 控制平面节点：运行 rke2-server，含 API Server / Scheduler 等控制面组件
systemctl status rke2-server

# 节点纳管 agent：运行 rke2-agent，仅工作负载相关组件（kubelet、kube-proxy）
systemctl status rancher-system-agent

卸载

rancher-system-agent-uninstall.sh

部署完平台之后

RKE2 集群就绪后，把它作为 K8s 底座继续按标准流程部署 CubeStudio（执行 install/kubernetes 下的 start.sh 等）。容器 CLI 统一用 nerdctl 时，记得把 CubeStudio 配置 CONTAINER_CLI 改为 nerdctl（默认是 docker，见 myapp/config.py:1110）。其余部署细节参见「02-部署安装」段其它文档。