对适用于 Kubernetes 的极狐GitLab 代理进行故障排除

当您使用适用于 Kubernetes 的极狐GitLab 代理时，您可能会遇到需要进行故障排除的问题。

您可以从查看服务日志开始：

kubectl logs -f -l=app=gitlab-agent -n gitlab-agent

如果您是极狐GitLab 管理员，您还可以查看极狐GitLab 代理服务器日志。

Transport: Error while dialing failed to WebSocket dial 

{
  "level": "warn",
  "time": "2020-11-04T10:14:39.368Z",
  "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://gitlab-kas:443/-/kubernetes-agent\\\": dial tcp: lookup gitlab-kas on 10.60.0.10:53: no such host\""
}

当 kas-address 和您的代理 pod 之间存在连接问题时，会发生此错误。要解决此问题，请确保 kas-address 是准确的。

{
  "level": "error",
  "time": "2021-06-25T21:15:45.335Z",
  "msg": "Reverse tunnel",
  "mod_name": "reverse_tunnel",
  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc= \"transport: Error while dialing failed to WebSocket dial: expected handshake response status code 101 but got 301\""
}

当 kas-address 不包含尾部斜杠时会发生此错误。要解决此问题，请确保 wss 或 ws URL 以斜杠结尾，例如 wss://GitLab.host.tld:443/-/kubernetes-agent/ 或 ws:// GitLab.host.tld:80/-/kubernetes-agent/。

Error while dialing failed to WebSocket dial: failed to send handshake request 

{
  "level": "warn",
  "time": "2020-10-30T09:50:51.173Z",
  "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://GitLabhost.tld:443/-/kubernetes-agent\\\": net/http: HTTP/1.x transport connection broken: malformed HTTP response \\\"\\\\x00\\\\x00\\\\x06\\\\x04\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x00\\\\x05\\\\x00\\\\x00@\\\\x00\\\"\""
}

当您在代理端将 wss 配置为 kas-address 时会发生此错误，但代理服务器在 wss 不可用。要解决此问题，请确保双方都配置了相同的方案。

Decompressor is not installed for grpc-encoding 

{
  "level": "warn",
  "time": "2020-11-05T05:25:46.916Z",
  "msg": "GetConfiguration.Recv failed",
  "error": "rpc error: code = Unimplemented desc = grpc: Decompressor is not installed for grpc-encoding \"gzip\""
}

当代理的版本比代理服务器 (KAS) 的版本新时，会发生此错误。要修复它，请确保 agentk 和代理服务器版本相同。

Certificate signed by unknown authority 

{
  "level": "error",
  "time": "2021-02-25T07:22:37.158Z",
  "msg": "Reverse tunnel",
  "mod_name": "reverse_tunnel",
  "error": "Connect(): rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing failed to WebSocket dial: failed to send handshake request: Get \\\"https://GitLabhost.tld:443/-/kubernetes-agent/\\\": x509: certificate signed by unknown authority\""
}

当您的实例使用由代理未知的内部证书颁发机构签名的证书时，会发生此错误。

要解决此问题，您可以使用 Kubernetes configmap 将 CA 证书文件提供给代理，并将该文件安装在代理 /etc/ssl/certs 目录中，该文件将自动从该目录中获取。

例如，如果您的内部 CA 证书是 myCA.pem：

kubectl -n gitlab-agent create configmap ca-pemstore --from-file=myCA.pem

然后在 resources.yml 中：

    spec:
      serviceAccountName: gitlab-agent
      containers:
      - name: agent
        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
        args:
        - --token-file=/config/token
        - --kas-address
        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
        volumeMounts:
        - name: token-volume
          mountPath: /config
        - name: ca-pemstore-volume
          mountPath: /etc/ssl/certs/myCA.pem
          subPath: myCA.pem
      volumes:
      - name: token-volume
        secret:
          secretName: gitlab-agent-token
      - name: ca-pemstore-volume
        configMap:
          name: ca-pemstore
          items:
          - key: myCA.pem
            path: myCA.pem

或者，您可以将证书文件安装在不同的位置，并为 --ca-cert-file 代理参数指定它：

      containers:
      - name: agent
        image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:<version>"
        args:
        - --ca-cert-file=/tmp/myCA.pem
        - --token-file=/config/token
        - --kas-address
        - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com.
        # - wss://gitlab.host.tld:443/-/kubernetes-agent/
        # - wss://kas.gitlab.com # for GitLab.com users, use this KAS.
        # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker.
        volumeMounts:
        - name: token-volume
          mountPath: /config
        - name: ca-pemstore-volume
          mountPath: /tmp/myCA.pem
          subPath: myCA.pem

安装期间解析失败

当您安装代理时，您可以能遇到如下错误：

Error: parse error at (gitlab-agent/templates/observability-secret.yaml:1): unclosed action

此错误是典型地由 Helm 版本不兼容引起的。要解决此问题，需要确保您正在使用的 Helm 版本和您使用的 Kubernetes 版本是兼容的。

在 Kubernetes 仪表盘上出现 GitLab Agent Server: Unauthorized 错误

出现在 Kubernetes 仪表盘页面上的错误 GitLab Agent Server: Unauthorized. Trace ID: <...> 可能是由以下原因导致：

  • 代理配置文件中的 user_access 条目不存在或错误。要解决此问题，可查阅授予用户 Kubernetes 访问权限。

  • 在浏览器中有个多个 _gitlab_kas cookies 并发送到 KAS。最大的原因可能是在同一个站点上托管了多个极狐GitLab 实例。

    比如，jihulab.com 设置了 _gitlab_kas cookie，目标为 kas.jihulab.com，但是也会发送到 kas.staging.jihulab.com，导致 staging.jihulab.com 上出现错误。

    临时解决方案，从浏览器 cookie 存储中删除 gitlab.com 的 _gitlab_kas cookie。

  • 极狐GitLab 和 KAS 运行在不同的站点。比如极狐GitLab 在 gitlab.jihulab.com 上，而 KAS 在 kas.jihulab.com 上。极狐GitLab 不支持此种用法。

代理版本不匹配

在极狐GitLab 中，在 Kubernetes 集群页面的 代理 选项卡上，您可能会看到一条警告信息 Agent version mismatch: The agent versions do not match each other across your cluster's pods.。

此警告信息可能是由 Kubernetes agent server（kas）缓存了老旧版本的代理所导致的。因为 kas 会周期性地删除过期的代理版本，您应该等至少 20 分钟以让代理和极狐GitLab 完成调谐。

如果告警持续，那么更新您集群上的代理。