Kubernetes向けGitLabエージェントのトラブルシューティング

Kubernetes向けGitLabエージェントを使用しているときに、トラブルシューティングが必要な問題が発生する可能性があります。

まず、サービスログを表示することから始めます:

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

GitLab管理者の場合は、Kubernetes向け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とエージェントポッドの間に接続の問題がある場合に発生します。この問題を解決するには、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のエンコードにデコンプレッサーがインストールされていません

{
  "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エンコードされた証明書である必要があります。

agentkを設定されたconfig.kasCaCert値でデプロイすると、証明書が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) logsに同様のエラーが表示される場合があります:

{"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
```

エラー: `Failed to register agent pod`

エージェントポッドのログに、エラーメッセージFailed to register agent pod. Please make sure the agent version matches the server versionが表示される場合があります。

この問題を解決するには、エージェントのバージョンが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"
}

Kubernetes向け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によって発生します。この問題を解決するには、HelmのバージョンがKubernetesのバージョンと互換性があることを確認してください。

Kubernetes用ダッシュボードのエラー`GitLab Agent Server: Unauthorized`

Kubernetes用ダッシュボードページのGitLab Agent Server: Unauthorized. Trace ID: <...>のようなエラーは、次のいずれかが原因である可能性があります:

エージェントの設定ファイルのuser_accessエントリが存在しないか、間違っています。解決するには、Kubernetesアクセス権をユーザーに付与するを参照してください。
ブラウザーに複数の_gitlab_kas cookieがあり、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はこのユースケースをサポートしていません。詳細については、issue 416436を参照してください。

エージェントのバージョンの不一致

GitLabのKubernetesクラスターページのエージェントタブに、Agent version mismatch: The agent versions do not match each other across your cluster's pods.という警告が表示される場合があります。

この警告は、Kubernetes（kas）用のエージェントサーバーによって古いバージョンのエージェントがキャッシュされていることが原因である可能性があります。kasは、期限切れのエージェントのバージョンを定期的に削除するため、エージェントとGitLabが調整されるまで、少なくとも20分待つ必要があります。

警告が解決しない場合は、クラスターにインストールされているエージェントを更新してください。

Kubernetes APIプロキシの応答ヘッダーが失われるか、ブロックされます

KubernetesクラスターからKubernetes APIプロキシを介してユーザーに送信されると、HTTP応答ヘッダーがブロックされる可能性があります。

このエラーは、応答ヘッダーがKASのデフォルトの許可リストに含まれていない場合に発生する可能性があります。

この問題を解決する方法については、ブロックされた応答ヘッダーを参照してください。