• 설치 옵션
  • Linux 패키지 설치
    • 단일 노드에서 비활성화
      • KAS를 UNIX 소켓에서 수신하도록 구성
    • 다중 노드에서 활성화
      • 에이전트 서버 노드 설정
  • GitLab Helm 차트용
• Kubernetes API 프록시 쿠키
• 문제 해결
  • 구성 파일을 찾을 수 없는 경우
  • dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused

GitLab 에이전트 서버를 Kubernetes (KAS)에 설치하세요

• 소개: GitLab 13.10에서 도입된 GitLab 에이전트 서버(KAS)는 wss://kas.gitlab.com에서 GitLab.com에서 사용할 수 있게 되었습니다.
• 이전: GitLab 프리미엄에서 GitLab 무료로 14.5에서 이동되었습니다.

에이전트 서버는 GitLab과 함께 설치되는 구성 요소입니다. 이는 GitLab 쿠버네티스 에이전트를 관리하는 데 필요합니다.

약어 KAS는 이전 이름인 쿠버네티스 에이전트 서버를 나타냅니다.

Kubernetes의 에이전트 서버는 wss://kas.gitlab.com에서 설치되어 GitLab.com에서 사용할 수 있습니다. Self-Managed GitLab을 사용하는 경우, 기본적으로 에이전트 서버가 설치되어 사용할 수 있습니다.

설치 옵션

GitLab 관리자로서 에이전트 서버 설치를 제어할 수 있습니다:

• Linux 패키지 설치를 위한.
• GitLab Helm 차트 설치를 위한.

Linux 패키지 설치

Linux 패키지 설치를 위한 에이전트 서버는 단일 노드 또는 한꺼번에 여러 노드에서 활성화할 수 있습니다. 기본적으로 에이전트 서버는 ws://gitlab.example.com/-/kubernetes-agent/에서 활성화되어 사용할 수 있습니다.

단일 노드에서 비활성화

단일 노드에서 에이전트 서버를 비활성화하려면:

1. /etc/gitlab/gitlab.rb를 편집하세요:

   gitlab_kas['enable'] = false
   

2. GitLab 재구성.

KAS를 UNIX 소켓에서 수신하도록 구성

GitLab을 프록시 뒤에서 사용하는 경우, KAS가 올바르게 작동하지 않을 수 있습니다. 단일 노드 설치에서 이 문제를 해결할 수 있습니다. KAS를 UNIX 소켓에서 수신하도록 구성할 수 있습니다.

KAS를 UNIX 소켓에서 수신하도록 구성하려면:

1. KAS 소켓을 위한 디렉터리를 만드세요:

   sudo mkdir -p /var/opt/gitlab/gitlab-kas/sockets/
   

2. /etc/gitlab/gitlab.rb를 편집하세요:

   gitlab_kas['internal_api_listen_network'] = 'unix'
   gitlab_kas['internal_api_listen_address'] = '/var/opt/gitlab/gitlab-kas/sockets/internal-api.socket'
   gitlab_kas['private_api_listen_network'] = 'unix'
   gitlab_kas['private_api_listen_address'] = '/var/opt/gitlab/gitlab-kas/sockets/private-api.socket'
   gitlab_kas['env'] = {
     'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/",
     'OWN_PRIVATE_API_URL' => 'unix:///var/opt/gitlab/gitlab-kas/sockets/private-api.socket'
   }
   

3. GitLab 재구성.

추가 구성 옵션에 대해서는 gitlab.rb.template의 GitLab Kubernetes 에이전트 서버 섹션을 참조하세요.

다중 노드에서 활성화

여러 노드에 에이전트 서버를 활성화하려면:

1. 각 에이전트 서버 노드에 대해, /etc/gitlab/gitlab.rb를 편집하세요:

   gitlab_kas_external_url 'wss://kas.gitlab.example.com/'
   
   gitlab_kas['api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
   gitlab_kas['private_api_secret_key'] = '<32_bytes_long_base64_encoded_value>'
   gitlab_kas['private_api_listen_address'] = '0.0.0.0:8155'
   gitlab_kas['env'] = {
     'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/",
     'OWN_PRIVATE_API_URL' => 'grpc://<ip_or_hostname_of_this_host>:8155' # TLS를 사용하는 경우, grpcs://를 사용합니다.
   
     # 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8', # IPv4 예시
     # 'OWN_PRIVATE_API_CIDR' => '2001:db8:8a2e:370::7334/64', # IPv6 예시
     # 'OWN_PRIVATE_API_PORT' => '8155',
     # 'OWN_PRIVATE_API_SCHEME' => 'grpc',
   }
   
   gitlab_rails['gitlab_kas_external_url'] = 'wss://gitlab.example.com/-/kubernetes-agent/'
   gitlab_rails['gitlab_kas_internal_url'] = 'grpc://kas.internal.gitlab.example.com'
   gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://gitlab.example.com/-/kubernetes-agent/k8s-proxy/'
   

   OWN_PRIVATE_API_URL 변수에 정확한 IP 주소 또는 호스트 이름을 지정할 수 없을 수 있습니다. 예를 들어, kas 호스트가 동적으로 IP를 할당받는 경우입니다.

   이 상황에서는, kas를 동적으로 자신의 개인 API URL을 구성하도록 OWN_PRIVATE_API_CIDR로 설정할 수 있습니다:

   • 이 변수를 비활성화하려면 OWN_PRIVATE_API_URL를 비활성화하세요.
   • kas가 수신하는 네트워크를 지정하도록 OWN_PRIVATE_API_CIDR를 구성하세요. kas를 시작할 때, kas는 호스트에 할당된 IP 주소를 확인하고 지정된 CIDR과 일치하는 주소를 자신의 개인 IP 주소로 사용합니다.
   • 기본적으로 kas는 private_api_listen_address 매개변수에서 포트를 사용합니다. 다른 포트를 사용하려면 OWN_PRIVATE_API_PORT를 구성하세요.
   • 선택 사항. 기본적으로 kas는 grpc 프로토콜을 사용합니다. 개인 API 엔드포인트에 TLS를 사용하는 경우, OWN_PRIVATE_API_SCHEME=grpcs를 구성하세요.

2. GitLab 재구성.

에이전트 서버 노드 설정

각주:

1. 예: wss://kas.gitlab.example.com/.
2. 예: wss://gitlab.example.com/-/kubernetes-agent/.

GitLab Helm 차트용

GitLab-KAS 차트 사용 방법을 참조하세요.

Kubernetes API 프록시 쿠키

• 도입됨 GitLab 15.10에서 기능 플래그인 kas_user_access 및 kas_user_access_project로 비활성화됨.
• 기능 플래그 kas_user_access 및 kas_user_access_project가 GitLab 16.1에서 활성화됨.
• 기능 플래그 kas_user_access 및 kas_user_access_project가 GitLab 16.2에서 제거됨.

KAS는 다음과 같이 Kubernetes API 요청을 GitLab 에이전트로 프록시합니다.

• CI/CD 작업.
• GitLab 사용자 자격 증명.

사용자 자격 증명으로 인증하려면 Rails는 GitLab 프론트엔드에 대한 쿠키를 설정합니다.
이 쿠키는 _gitlab_session 쿠키와 같이 암호화된 세션 ID를 포함하며,
사용자를 인증하고 권한 부여하기 위해 모든 요청에 대해 KAS 프록시 엔드포인트로 전송되어야 합니다.

문제 해결

Kubernetes용 에이전트 서버 사용 중 문제가 발생하는 경우 다음 명령을 실행하여 서비스 로그를 확인하세요.

kubectl logs -f -l=app=kas -n <YOUR-GITLAB-NAMESPACE>

Linux 패키지 설치의 경우, /var/log/gitlab/gitlab-kas/에서 로그를 찾을 수 있습니다.

개별 에이전트의 문제를 해결하는 방법을 참고할 수도 있습니다.
### GitOps: 프로젝트 정보를 가져오지 못하는 경우

다음과 같은 오류 메시지를 받으면:

{"level":"warn","time":"2020-10-30T08:37:26.123Z","msg":"GitOps: failed to get project info","agent_id":4,"project_id":"root/kas-manifest001","error":"error kind: 0; status: 404"}

매니페스트에 지정된 프로젝트(root/kas-manifest001)가 존재하지 않거나, 매니페스트가 있는 프로젝트가 비공개 상태일 수 있습니다. 이 문제를 해결하려면 프로젝트 경로가 올바른지 확인하고, 프로젝트의 가시성이 공개로 설정되었는지 확인하세요.

구성 파일을 찾을 수 없는 경우

다음과 같은 오류 메시지를 받으면:

time="2020-10-29T04:44:14Z" level=warning msg="Config: failed to fetch" agent_id=2 error="configuration file not found: \".gitlab/agents/test-agent/config.yaml\

다음 중 하나에 대한 경로가 올바르지 않습니다:

• 에이전트가 등록된 저장소.
• 에이전트 구성 파일.

이 문제를 해결하려면 경로가 올바른지 확인하세요.

dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused

자체 관리형 GitLab을 실행 중이고 다음과 같은 경우:

• 인스턴스가 SSL 종료 프록시 뒤에서 실행되지 않습니다.
• GitLab 인스턴스 자체에 HTTPS가 구성되어 있지 않습니다.
• 인스턴스의 호스트명이 내부 IP 주소로 로컬로 해결됩니다.

에이전트 서버가 GitLab API에 연결을 시도할 때, 다음 오류가 발생할 수 있습니다:

{"level":"error","time":"2021-08-16T14:56:47.289Z","msg":"GetAgentInfo()","correlation_id":"01FD7QE35RXXXX8R47WZFBAXTN","grpc_service":"gitlab.agent.reverse_tunnel.rpc.ReverseTunnel","grpc_method":"Connect","error":"Get \"https://gitlab.example.com/api/v4/internal/kubernetes/agent_info\": dial tcp 172.17.0.4:443: connect: connection refused"}

Linux 패키지 설치의 경우 이 문제를 해결하려면 /etc/gitlab/gitlab.rb에서 다음 매개변수를 설정하십시오. gitlab.example.com을 GitLab 인스턴스의 호스트명으로 대체하세요:

gitlab_kas['gitlab_address'] = 'http://gitlab.example.com'