Rancher 创建 RKE2 集群，日志错误：system-default-registry: registries must be valid RFC 3986 URI

Posted 2023-01-06 catoop

问题回溯

1、先安装的 k3s，然后在 k3s 上基于 helm 部署的 rancher 2.6.6 版本
2、离线安装，私服使用的 harbor，地址为 https://harbor.test.com
3、在 harbor 中创了项目 dockerhub_proxy，该项目代理了 dockerhub 仓库，所以前缀地址为 https://harbor.test.com/dockerhub_proxy。以 docker.io/library/alpine 为例，对应的 harbor 地址就变成了 https://harbor.test.com/dockerhub_proxy/library/alpine，如下图所示：

4、helm 安装 rancher 的指定了 systemDefaultRegistry，如下所示（这是问题点先记住此处）：

helm template rancher ./rancher-2.6.6.tgz --output-dir . \\
 --no-hooks \\
 --namespace cattle-system \\
 --set hostname=rancher2.test.com \\
 --set rancherImage=harbor.test.com/dockerhub_proxy/rancher/rancher \\
 --set ingress.tls.source=secret \\  
 --set privateCA=true \\
 --set systemDefaultRegistry=harbor.test.com/dockerhub_proxy \\
 --set useBundledSystemChart=true \\
 --kube-version=v1.23.6

rancher 部署成功后在全局设置中可以看到这个默认私服，如下图：

5、通过 rancher 界面上创建集群，选择使用 RKE2，除了私服选项如下图配置外，其他均正常默认即可

6、创建集群后，注册主机节点

7、节点注册过程中，UI 界面上出现错误后（具体忘了截图），查看服务器日志，出现如下错误

journalctl -u rancher-system-agent.service -f
journalctl -u rke2-server.service -f

在 journalctl -u rke2-server.service -f 日志中发出错误内容 level=fatal msg="failed to parse system-default-registry: registries must be valid RFC 3986 URI authorities: harbor.test.com/dockerhub_proxy"

至此，整个过程回溯完毕，下文陈述错误原因及解决方法。

问题分析过程

错误含义：错误日志表达的意思就是我们设置的 systemDefaultRegistry 不是一个有效的 RFC 3986 URI。

然后查看官网文档，在文档中发现也对此做了说明：

这里再说一下我为什么想着要使用 harbor.test.com/dockerhub_proxy，因为如果我只设置 harbor.test.com，就会导致在部署集群的时候所有下载的镜像都是 harbor.test.com/rancher/xxxx:1.0.0 这样的，这肯定会下载镜像失败因为这是不符合我私服代理 dockerhub 仓库的规则的。

按照官方的解释，systemDefaultRegistry 是在创建集群时，Rancher Server 拉取镜像的私有仓库。比如默认拉取镜像的地址是 docker.io/rancher/system-agent，配置该参数后实际拉取地址就变成了 <systemDefaultRegistry>/rancher/system-agent。

按照官方要求，我更新 rancher 部署，把 systemDefaultRegistry 修改为 harbor.test.com，然后删除注册失败的节点，重新输入命令重新注册节点。

不出意外的话肯定会出错，按照规则，集群部署时所需要的镜像下载地址中就没有 dockerhub_proxy，例如 /rancher/system-agent 的拉取地址就是 harbor.test.com/rancher/system-agent，这不符合我私服代理 dockerhub 的 URL 规则，那怎么办呢？

问题解决方法

如果你的应用场景和我一样，那么解决方案有如下三种：

1、【首选推荐】通过 nginx 新增一个域名 dockerio.harbor.test.com，通过 nginx 的 location 策略，把所有请求 /rancher/* 的地址都反向代理到 dockerhub_proxy/rancher/* 上，然后将 rancher 的 systemDefaultRegistry 设置为 dockerio.harbor.test.com。

2、在 harbor 中创建一个名称为 rancher 的项目，然后把你需要的所有镜像都弄进去，这样访问地址就符合规则了（这个就失去了自动代理的意义，个人觉得比较麻烦，而且你还得很清楚所有需要的镜像清单，漏一个都会出现未知问题导致集群安装失败）。

3、【其次推荐】编辑创建的 rke2 集群的 yml 文件，给 mirrors 添加 rewrite 规则 "^rancher/(.*)": "dockerhub_proxy/rancher/$1"，然后将 rancher 的 systemDefaultRegistry 去掉小尾巴正常设置为 harbor.test.com，截图如下：

这个问题也有人遇到，并且在官方提了（就是创建集群时配置的 system-default-registry 不生效依然会去取 rancher 全局的 system-default-registry），可以点击 issue 查看。

本文使用版本是 rancher-v2.6.6，不知后续版本是否会修复该问题。

这里还建议官方为创建 rke2 的配置界面增加 rewrite 配置输入框，这样就不用手工修改 yml 文件了。

---

（END）