离线环境单Docker部署Rancher：如何为内置K3s传递私有仓库凭证？

问题背景 #

在离线（Air-Gapped）环境以单Docker容器启动Rancher时，内置的local集群拉取rancher/shell镜像失败，原因是私有镜像仓库需要认证，但未将凭证传递给Rancher内部运行的K3s集群。

解决方案 #

方法1：启动Rancher容器时挂载私有仓库认证文件 #

Rancher内置的K3s使用containerd作为容器运行时，containerd会读取特定路径下的认证配置文件来访问私有仓库。具体步骤：

1. 创建私有仓库认证文件
   在宿主机上创建config.json文件，替换为你的私有仓库用户名和密码：

{
  "auths": {
    "private.docker.net": {
      "username": "私有仓库用户名",
      "password": "私有仓库密码"
    }
  }
}

2. 修改Rancher启动命令
   在原启动命令中添加挂载配置，将宿主机的config.json挂载到容器内部containerd的认证配置路径：

sudo docker run -d --privileged --restart=unless-stopped \
  --name rancher \
  -p 8080:80 -p 8443:443 \
  -v /home/devbox/certs:/certificates \
  # 新增挂载私有仓库认证文件
  -v /path/to/your/config.json:/var/lib/rancher/k3s/agent/etc/containerd/config.json \
  -e SSL_CERT_DIR=/certificates \
  -e CATTLE_SYSTEM_DEFAULT_REGISTRY=private.docker.net \
  -e CATTLE_SYSTEM_CATALOG=bundled \
  private.docker.net/rancher/rancher:v2.7.5

注意：将/path/to/your/config.json替换为宿主机上实际的文件路径。

方法2：在Rancher容器内配置K3s registries.yaml #

如果已经启动了Rancher容器，可以进入容器内部配置K3s的镜像仓库规则，包含认证信息：

1. 进入Rancher容器

docker exec -it rancher /bin/sh

2. 创建/编辑K3s registries.yaml文件
   在/etc/rancher/k3s/路径下创建registries.yaml，内容如下：

mirrors:
  private.docker.net:
    endpoint:
      - "https://private.docker.net"
configs:
  private.docker.net:
    auth:
      username: "私有仓库用户名"
      password: "私有仓库密码"

3. 重启容器内的K3s服务

systemctl restart k3s

若容器内无systemctl，可直接重启Rancher容器：docker restart rancher

验证 #

重启Rancher后，进入Rancher UI查看local集群的节点状态，或通过容器内的K3s命令验证镜像拉取：

docker exec -it rancher kubectl get pods -n cattle-system

确认所有Pod（包括rancher-shell相关）均正常运行。

内容的提问来源于stack exchange，提问作者Luiz Omori