Kubernetes용 GitLab 에이전트를 사용할 때 문제 해결이 필요한 이슈가 발생할 수 있습니다.

서비스 로그를 확인하는 것부터 시작할 수 있습니다:

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

GitLab 관리자라면 Kubernetes용 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와 에이전트 파드 사이의 연결 문제가 있을 때 발생합니다. 이 문제를 해결하려면 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\\\"\""
}

이 오류는 에이전트 측에서 kas-address를 wss로 구성했지만 에이전트 서버가 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\""
}

이 오류는 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/"
 }

변경 사항을 적용하려면:

1. GitLab을 재구성합니다.

   sudo gitlab-ctl reconfigure
   

2. 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 버전과 일치하는지 확인하세요.

버전이 일치하고 오류가 계속 발생하는 경우:

1. gitlab-ctl status gitlab-kas로 gitlab-kas가 실행 중인지 확인합니다.
2. 에이전트가 올바르게 작동하는지 확인하기 위해 gitlab-kas 로그를 확인합니다.

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

Kubernetes용 GitLab 에이전트는 각 워크로드를 스캔하는 job을 생성하여 취약점 스캔을 수행합니다. 스캔이 중단되면 이러한 job들이 남아 더 많은 job이 실행되기 전에 정리해야 할 수 있습니다. 다음 명령어를 실행하여 이러한 job들을 정리할 수 있습니다:

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

이 job들의 정리를 더 견고하게 만들기 위해 작업 중입니다.

설치 중 파싱 오류#

에이전트를 설치할 때 다음과 같은 오류가 발생할 수 있습니다:

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

이 오류는 일반적으로 호환되지 않는 Helm 버전으로 인해 발생합니다. 이 문제를 해결하려면 Kubernetes 버전과 호환되는 Helm 버전을 사용하고 있는지 확인하세요.

Kubernetes 대시보드에서 GitLab Agent Server: Unauthorized 오류#

Kubernetes 대시보드 페이지에서 GitLab Agent Server: Unauthorized. Trace ID: <...>와 같은 오류는 다음 중 하나로 인해 발생할 수 있습니다:

• 에이전트 구성 파일의 user_access 항목이 존재하지 않거나 잘못되었습니다. 이를 해결하려면 사용자에게 Kubernetes 접근 권한 부여를 참조하세요.

• 브라우저에 여러 _gitlab_kas 쿠키가 있어 KAS로 전송됩니다. 가장 가능성 높은 원인은 동일한 사이트에 여러 GitLab 인스턴스가 호스팅되는 것입니다.

  예를 들어, gitlab.com이 kas.gitlab.com을 대상으로 하는 _gitlab_kas 쿠키를 설정했지만 해당 쿠키가 kas.staging.gitlab.com으로도 전송되어 staging.gitlab.com에서 오류가 발생합니다.

  임시 해결책으로 브라우저 쿠키 저장소에서 gitlab.com의 _gitlab_kas 쿠키를 삭제하세요. 이슈 418998에서 이 알려진 이슈에 대한 수정을 제안하고 있습니다.

• GitLab과 KAS가 서로 다른 사이트에서 실행됩니다. 예를 들어 GitLab이 gitlab.example.com에, KAS가 kas.example.com에 있는 경우입니다. GitLab은 이 사용 사례를 지원하지 않습니다. 자세한 내용은 이슈 416436을 참조하세요.

에이전트 버전 불일치#

GitLab의 Kubernetes 클러스터 페이지의 Agent 탭에서 Agent version mismatch: The agent versions do not match each other across your cluster's pods.라는 경고가 표시될 수 있습니다.

이 경고는 Kubernetes용 에이전트 서버(kas)가 에이전트의 오래된 버전을 캐시했기 때문에 발생할 수 있습니다. kas는 주기적으로 오래된 에이전트 버전을 삭제하므로, 에이전트와 GitLab이 조정되기까지 최소 20분을 기다려야 합니다.

경고가 계속 표시되면 클러스터에 설치된 에이전트를 업데이트하세요.

Kubernetes API 프록시 응답 헤더가 손실되거나 차단됨#

HTTP 응답 헤더가 Kubernetes API 프록시를 통해 Kubernetes 클러스터에서 사용자에게 전송될 때 차단될 수 있습니다.

이 오류는 응답 헤더가 KAS의 기본 허용 목록에 포함되지 않을 때 발생할 가능성이 높습니다.

이 문제 해결 단계는 차단된 응답 헤더를 참조하세요.