对极狐GitLab Kubernetes 代理进行故障排查

传输：拨号失败到 WebSocket 拨号时出错
拨号失败到 WebSocket 拨号：发送握手请求失败时出错
grpc-encoding 未安装解压器
由未知机构签署的证书
错误：无法注册代理 Pod
无法执行漏洞扫描：jobs.batch 已存在
安装期间解析错误
Kubernetes 仪表板上的 极狐GitLab 代理服务器：未授权 错误
代理版本不匹配

当您使用极狐GitLab 的 Kubernetes 代理时，可能会遇到需要解决的问题。

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

kubectl logs -f -l=app.kubernetes.io/name=gitlab-agent -n gitlab-agent

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

传输：拨号失败到 WebSocket 拨号时出错

{
  "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/。

拨号失败到 WebSocket 拨号：发送握手请求失败时出错

{
  "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 上不可用时，会发生此错误。要解决此问题，请确保双方配置了相同的方案。

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 和代理服务器是相同版本。

由未知机构签署的证书

{
  "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\""
}

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

要解决此问题，您可以通过自定义 Helm 安装向代理提供 CA 证书文件。在 helm install 命令中添加 --set-file config.kasCaCert=my-custom-ca.pem。文件应该是有效的 PEM 或 DER 编码证书。

当您用设置的 config.kasCaCert 值部署 agentk 时，证书会被添加到 configmap 中，证书文件会被挂载到 /etc/ssl/certs。

例如，使用命令 kubectl get configmap -lapp=gitlab-agent -o yaml：

apiVersion: v1
items:
- apiVersion: v1
  data:
    ca.crt: |-
      -----BEGIN CERTIFICATE-----
      MIIFmzCCA4OgAwIBAgIUE+FvXfDpJ869UgJitjRX7HHT84cwDQYJKoZIhvcNAQEL
      ...truncated certificate...
      GHZCTQkbQyUwBWJOUyOxW1lro4hWqtP4xLj8Dpq1jfopH72h0qTGkX0XhFGiSaM=
      -----END CERTIFICATE-----
  kind: ConfigMap
  metadata:
    annotations:
      meta.helm.sh/release-name: self-signed
      meta.helm.sh/release-namespace: gitlab-agent-self-signed
    creationTimestamp: "2023-03-07T20:12:26Z"
    labels:
      app: gitlab-agent
      app.kubernetes.io/managed-by: Helm
      app.kubernetes.io/name: gitlab-agent
      app.kubernetes.io/version: v15.9.0
      helm.sh/chart: gitlab-agent-1.11.0
    name: self-signed-gitlab-agent
    resourceVersion: "263184207"
kind: List

您可能会在极狐GitLab 应用服务器的代理服务器（KAS）日志中看到类似的错误：

{"level":"error","time":"2023-03-07T20:19:48.151Z","msg":"AgentInfo()","grpc_service":"gitlab.agent.agent_configuration.rpc.AgentConfiguration","grpc_method":"GetConfiguration","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": x509: certificate signed by unknown authority"}

要解决此问题，请在 /etc/gitlab/trusted-certs 目录中安装您内部 CA 的公共证书。

或者，您可以配置代理服务器（KAS）从自定义目录读取证书。在 /etc/gitlab/gitlab.rb 中添加以下配置：

gitlab_kas['env'] = {
   'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/"
 }

要应用更改：

重新配置极狐GitLab。
```
sudo gitlab-ctl reconfigure
```
重启 gitlab-kas。
```
gitlab-ctl restart gitlab-kas
```

错误：`无法注册代理 Pod`

代理 Pod 日志可能会显示错误消息 无法注册代理 Pod。请确保代理版本与服务器版本匹配。

要解决此问题，请确保代理版本与极狐GitLab 版本匹配。

如果版本匹配且错误仍然存在：

确保 gitlab-kas 正在运行 gitlab-ctl status gitlab-kas。
检查 gitlab-kas 日志以确保代理正常运行。

无法执行漏洞扫描：jobs.batch 已存在

{
  "level": "error",
  "time": "2022-06-22T21:03:04.769Z",
  "msg": "Failed to perform vulnerability scan on workload",
  "mod_name": "starboard_vulnerability",
  "error": "running scan job: creating job: jobs.batch \"scan-vulnerabilityreport-b8d497769\" already exists"
}

极狐GitLab 代理通过创建作业来扫描每个工作负载以执行漏洞扫描。如果扫描中断，这些作业可能会被留下，需要清理后才能运行更多作业。您可以通过运行以下命令清理这些作业：

kubectl delete jobs -l app.kubernetes.io/managed-by=starboard -n gitlab-agent

安装期间解析错误

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

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

此错误通常是由不兼容的 Helm 版本引起的。要解决此问题，请确保您使用的是与您的 Kubernetes 版本兼容的 Helm 版本。

Kubernetes 仪表板上的 `极狐GitLab 代理服务器：未授权` 错误

在 Kubernetes 仪表板页面上，可能会出现 极狐GitLab 代理服务器：未授权。跟踪 ID：<...> 的错误，可能是由以下原因之一引起的：

代理配置文件中的 user_access 条目不存在或错误。要解决，请参阅授予用户 Kubernetes 访问权限。
浏览器中存在多个_gitlab_kas cookie并发送到 KAS。最可能的原因是在同一站点上托管多个极狐GitLab 实例。

例如，gitlab.com 设置了一个 _gitlab_kas cookie 目标为 kas.gitlab.com，但该 cookie 也发送到 kas.staging.gitlab.com，这会导致 staging.gitlab.com 上的错误。

要临时解决，请从浏览器 cookie 存储中删除 gitlab.com 的 _gitlab_kas cookie。
极狐GitLab 和 KAS 运行在不同的站点。例如，极狐GitLab 在 gitlab.example.com 上运行，KAS 在 kas.example.com 上运行。极狐GitLab 不支持此用例。

代理版本不匹配

在极狐GitLab 的 Kubernetes 集群页面的代理选项卡上，您可能会看到一个警告，显示 代理版本不匹配：代理版本在您的集群的 Pod 之间不匹配。

此警告可能是由于代理服务器为 Kubernetes (kas) 缓存了较旧版本的代理引起的。由于 kas 会定期删除过时的代理版本，您应该至少等待 20 分钟，以便代理和极狐GitLab 完成协调。

如果警告仍然存在，请更新安装在您的集群上的代理。