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와 에이전트 포드 간의 연결 문제가 있을 때 발생합니다. 이 문제를 해결하려면 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 인스턴스가 에이전트에 알려지지 않은 내부 인증기관에 의해 서명된 인증서를 사용하고 있을 때 발생합니다.

이 문제를 해결하려면 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

작업 부하에 대해 취약점 스캔을 수행하지 못했습니다: jobs.batch가 이미 존재합니다 

{
  "level": "error",
  "time": "2022-06-22T21:03:04.769Z",
  "msg": "작업 부하에 대해 취약점 스캔을 수행하지 못했습니다",
  "mod_name": "starboard_vulnerability",
  "error": "스캔 작업 실행: 작업 생성: jobs.batch \"scan-vulnerabilityreport-b8d497769\"가 이미 존재합니다"
}

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 버전을 사용하고 있는지 확인하십시오.

GitLab Agent Server: Unauthorized 오류가 Kubernetes 대시보드에 발생

GitLab Agent Server: Unauthorized. Trace ID: <...>와 같은 오류가 Dashboard for Kubernetes 페이지에 나타날 수 있습니다.

이는 다음 중 하나의 원인일 수 있습니다:

  • 에이전트 구성 파일의 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 쿠키를 삭제하십시오. Issue 418998는 이 알려진 문제에 대한 수정 제안을 하고 있습니다.

  • GitLab과 KAS가 서로 다른 사이트에서 실행됩니다. 예를 들어, GitLab은 gitlab.example.com에 있고 KAS는 kas.example.com에 있습니다. GitLab은 이러한 사용 사례를 지원하지 않습니다. 자세한 내용은 issue 416436를 참조하십시오.

에이전트 버전 불일치

GitLab의 Kubernetes 클러스터 페이지의 에이전트 탭에서 에이전트 버전 불일치: 클러스터의 포드들 간에 에이전트 버전이 서로 일치하지 않습니다.라는 경고를 볼 수 있습니다.

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

경고가 지속되면 클러스터에 설치된 에이전트를 업데이트하십시오.