GitLab更新后GitLab Kubernetes Agent无法正常工作

问题描述 #

一周前按照GitLab官方说明通过Helm在Kubernetes集群部署GitLab Kubernetes Agent，操作仅为复制粘贴，GitLab更新前运行正常。更新后Agent出现如下错误：

{"level":"warn","time":"2023-06-06T10:07:54.918Z","msg":"GetConfiguration failed","error":"rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: failed to WebSocket dial: failed to send handshake request: Get \\\"https://kas.gitlab.com\\\": remote error: tls: handshake failure\""}

环境信息 #

• Kubernetes版本：v1.27.2
• 宿主系统：Ubuntu 22.04.2 LTS
• 集群架构：1个控制平面节点 + 2个工作节点
• Helm版本：v3.12.0
• GitLab Agent版本：v16.1.2

已尝试重新部署所有组件，问题依旧。

解决方案 #

1. 对齐Agent与GitLab版本兼容性 #

GitLab 16.x版本开始，Agent版本需要与GitLab主版本严格匹配（比如GitLab 16.2对应Agent 16.2.x），Kas（Kubernetes Agent Server）的API和TLS握手规则会随GitLab版本迭代更新。若GitLab已升级到16.2及以上，需将Agent升级至对应版本：

# 替换<GITLAB_VERSION>为当前GitLab的主版本号，比如v16.2.0
helm upgrade gitlab-agent gitlab/gitlab-agent --namespace gitlab-agent --set image.tag=<GITLAB_VERSION>

2. 更新集群节点的根CA证书 #

Ubuntu 22.04的系统根CA证书可能未包含kas.gitlab.com使用的新根证书，导致TLS握手失败：

• 在所有集群节点执行证书更新：

  sudo update-ca-certificates
  

• 重启Agent Pod使新证书生效：

  kubectl rollout restart deployment/gitlab-agent -n gitlab-agent
  

• 若仍无效，可通过Helm配置让Agent容器挂载主机的根证书目录：

  helm upgrade gitlab-agent gitlab/gitlab-agent --namespace gitlab-agent \
    --set extraVolumes[0].name=host-ca \
    --set extraVolumes[0].hostPath.path=/etc/ssl/certs \
    --set extraVolumeMounts[0].name=host-ca \
    --set extraVolumeMounts[0].mountPath=/etc/ssl/certs \
    --set extraVolumeMounts[0].readOnly=true
  

3. 验证TLS握手与网络连通性 #

在Agent Pod内测试与kas.gitlab.com的TLS握手，定位具体问题：

• 进入Agent容器：

  kubectl exec -it $(kubectl get pods -n gitlab-agent -l app=gitlab-agent -o name) -n gitlab-agent -- sh
  

• 执行TLS握手测试：

  openssl s_client -connect kas.gitlab.com:443
  

  若输出中出现Verify return code: 0 (ok)则证书验证正常；若出现证书链缺失或不支持的TLS版本，需确认Agent镜像的TLS支持能力（升级Agent版本通常可解决此问题）。

4. 确认Kas Endpoint配置 #

检查Agent的ConfigMap中Kas地址是否正确，GitLab更新后若Kas地址变更会导致连接失败：

kubectl get configmap gitlab-agent -n gitlab-agent -o yaml

确保kasAddress字段值为wss://kas.gitlab.com（GitLab SaaS的默认地址），若有错误需通过Helm重新设置：

helm upgrade gitlab-agent gitlab/gitlab-agent --namespace gitlab-agent --set kasAddress=wss://kas.gitlab.com

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