Gitlab Agent在K3S集群注册失败问题求助

问题描述 #

使用GitLab提供的Helm命令在自建Rancher K3s集群安装gitlab-agent-2.0.0后，Agent Pod日志持续报错：

{"level":"error","time":"2024-05-22T07:39:03.393Z","msg":"Failed to register agent pod. Please make sure the agent version matches the server version","mod_name":"agent_registrar","error":"rpc error: code = Unavailable desc = unavailable"}

排查步骤 #

1. 验证版本兼容性 #

gitlab-agent chart 2.0.0对应Agent版本为v16.x，要求GitLab服务器版本必须为16.0及以上。请检查GitLab服务器版本（页面底部可查看），确保两者版本匹配，版本不兼容会直接导致注册失败。

2. 测试网络连通性 #

从Agent Pod内部测试能否访问GitLab Kas地址：

1. 进入Agent Pod：

   kubectl exec -it <agent-pod-name> -n gitlab-agent-k8s-connection-poc -- sh
   

2. 用curl测试HTTPS连通性（WSS基于HTTPS协议）：

   curl -v https://secf-gitlab-bis.secf.asso.fr/-/kubernetes-agent/
   

   若返回Connection refused或超时，说明集群与GitLab服务器之间存在防火墙/路由阻断，需开放443端口的访问权限。

3. 验证CA证书有效性 #

检查gitlab.crt是否为GitLab服务器的根CA证书，且能正确验证Kas的SSL证书：

1. 将证书复制到Pod内：

   kubectl cp gitlab.crt <agent-pod-name>:/tmp/gitlab.crt -n gitlab-agent-k8s-connection-poc
   

2. 执行证书验证：

   openssl s_client -connect secf-gitlab-bis.secf.asso.fr:443 -CAfile /tmp/gitlab.crt
   

   若输出末尾显示Verify return code: 0 (ok)，说明证书有效；若返回错误，需重新获取正确的CA证书。

4. 确认Agent Token有效性 #

• 检查Token是否为GitLab对应项目/群组中创建的Kubernetes Agent注册令牌，而非其他类型Token。
• 登录GitLab，进入项目/群组的基础设施 > Kubernetes集群页面，确认该Token未被撤销或过期。

5. 检查GitLab Kas服务状态 #

登录GitLab管理后台，进入监控 > 状态检查，确认GitLab Kas服务处于运行状态。若Kas服务未启动或异常，Agent将无法完成注册。

额外操作建议 #

若以上排查无误，可尝试重新安装Agent，确保Helm参数正确：

helm uninstall k8s-connection-poc -n gitlab-agent-k8s-connection-poc
helm upgrade --install k8s-connection-poc gitlab/gitlab-agent \
--namespace gitlab-agent-k8s-connection-poc \
--create-namespace \
--set config.token=<有效令牌> \
--set config.kasAddress=wss://secf-gitlab-bis.secf.asso.fr/-/kubernetes-agent/ \
--set-file config.kasCaCert=gitlab.crt

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