Help us learn about your current experience with the documentation. Take the survey.

GitLab Agent for Kubernetes 故障排除

在使用 GitLab Agent for Kubernetes 时，您可能会遇到需要排查的问题。

您可以先查看服务日志：

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

如果您是 GitLab 管理员，还可以查看 GitLab agent server for Kubernetes 日志。

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 与您的 agent 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\""
}

当 agent 版本比 agent server (KAS) 版本新时，会出现此错误。要解决此问题，请确保 agentk 和 agent server 是相同版本。

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

当您的 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 应用服务器的 agent server (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"}

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

或者，您可以将 agent server (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
```

Error: `Failed to register agent pod`

agent pod 日志可能显示错误消息 Failed to register agent pod. Please make sure the agent version matches the server version。

要解决此问题，请确保 agent 版本与 GitLab 版本匹配。

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

使用 gitlab-ctl status gitlab-kas 确保 gitlab-kas 正在运行。
检查 gitlab-kas 日志以确保 agent 正常工作。

Failed to perform vulnerability scan on workload: jobs.batch already exists

{
  "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 Agent for Kubernetes 通过创建作业来扫描每个工作负载来进行漏洞扫描。如果扫描被中断，这些作业可能会被遗留下来，需要在运行更多作业之前进行清理。您可以通过运行以下命令清理这些作业：

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

我们正在努力使这些作业的清理更加健壮。

Parse error during installation

安装 agent 时，您可能会遇到以下错误：

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

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

`GitLab Agent Server: Unauthorized` error on Dashboard for Kubernetes

在 Dashboard for Kubernetes 页面上出现类似 GitLab Agent Server: Unauthorized. Trace ID: <...> 的错误，可能由以下原因之一引起：

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

例如，gitlab.com 为 kas.gitlab.com 设置了一个 _gitlab_kas cookie，但该 cookie 也被发送到 kas.staging.gitlab.com，这导致在 staging.gitlab.com 上出现错误。

要临时解决，请从浏览器 cookie 存储中删除 gitlab.com 的 _gitlab_kas cookie。问题 418998 提出了针对此已知问题的修复方案。
GitLab 和 KAS 运行在不同的站点上。例如，GitLab 在 gitlab.example.com 上，KAS 在 kas.example.com 上。 GitLab 不支持这种用例。详细信息请参见问题 416436。

Agent version mismatch

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

此警告可能是由于 agent server for Kubernetes (kas) 缓存了旧版本的 agent 引起的。由于 kas 会定期删除过时的 agent 版本，您应该至少等待 20 分钟让 agent 和 GitLab 进行协调。

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