설치 옵션
- Linux 패키지 설치용
  - 단일 노드에서 비활성화
    - KAS를 UNIX 소켓으로 수신하도록 설정
  - 여러 노드에서 활성화
    - 에이전트 서버 노드 설정
- GitLab Helm Chart에 대한 내용
Kubernetes API 프록시 쿠키
문제 해결
- 구성 파일을 찾을 수 없음
- dial tcp <GITLAB_INTERNAL_IP>:443: connect: connection refused

Kubernetes용 GitLab 에이전트 서버(KAS) 설치

Tier: Free, Premium, Ultimate Offering: Self-Managed

에이전트 서버는 GitLab과 함께 설치되는 컴포넌트입니다. 이는 GitLab Kubernetes 에이전트를 관리하는 데 필요합니다.

KAS 약어는 이전 이름인 Kubernetes 에이전트 서버를 나타냅니다.

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

설치 옵션

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

Linux 패키지 설치용.
GitLab Helm 차트 설치용.

Linux 패키지 설치용

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

단일 노드에서 비활성화

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

/etc/gitlab/gitlab.rb 파일을 편집합니다:
```
gitlab_kas['enable'] = false
```
GitLab 재구성.

KAS를 UNIX 소켓으로 수신하도록 설정

GitLab을 프록시 뒤에 두었을 때 KAS가 제대로 작동하지 않을 수 있습니다. 단일 노드 설치에서 이 문제를 해결하려면 KAS를 UNIX 소켓으로 수신하도록 설정할 수 있습니다.

KAS를 UNIX 소켓으로 수신하도록 설정하려면:

KAS 소켓을 위한 디렉터리를 만듭니다:

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

/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'
}

GitLab 재구성.

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

여러 노드에서 활성화

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

각 에이전트 서버 노드에 대해, /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를 사용하는 경우, private API 엔드포인트에 grpcs:// 사용
     
  # 'OWN_PRIVATE_API_HOST' => '<server-name-from-cert>' # KAS->KAS 통신에 TLS를 사용할 경우 추가합니다. 이를 통해 TLS 인증서 호스트 이름을 확인합니다.
     
  # '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/'

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

이러한 상황에서는 OWN_PRIVATE_API_CIDR을 구성하여 kas가 OWN_PRIVATE_API_URL를 동적으로 구성하도록 설정할 수 있습니다:

이 변수를 비활성화하려면 OWN_PRIVATE_API_URL을 주석 처리합니다.
kas가 수신할 네트워크를 지정하려면 OWN_PRIVATE_API_CIDR를 구성합니다. kas는 시작할 때 호스트에 할당된 IP 주소를 확인하고 지정된 CIDR과 일치하는 주소를 자체 개인 IP 주소로 사용합니다.
기본적으로 kas는 private_api_listen_address 매개변수의 포트를 사용합니다. 다른 포트를 사용하려면 OWN_PRIVATE_API_PORT를 구성합니다.
기본적으로 kas는 grpc 스키마를 사용합니다. TLS를 사용하는 경우, OWN_PRIVATE_API_SCHEME=grpcs를 구성합니다.

GitLab 재구성.

에이전트 서버 노드 설정

설정	설명
`gitlab_kas['private_api_listen_address']`	에이전트 서버가 수신하는 주소. 기타 클러스터 노드에서 접근 가능한 IP 주소 또는 `0.0.0.0`로 설정합니다.
`gitlab_kas['api_secret_key']`	KAS와 GitLab 간 인증에 사용되는 공유 비밀. 값은 반드시 Base64로 인코딩되어 있고 정확히 32바이트여야 합니다.
`gitlab_kas['private_api_secret_key']`	서로 다른 KAS 인스턴스 간의 인증에 사용되는 공유 비밀. 값은 반드시 Base64로 인코딩되어 있고 정확히 32바이트여야 합니다.
`OWN_PRIVATE_API_URL`	KAS가 서비스 검색에 사용하는 환경 변수. 구성 중인 노드의 호스트명 또는 IP 주소로 설정합니다. 클러스터 내 다른 노드에서 접근 가능해야 합니다.
`OWN_PRIVATE_API_HOST`	TLS 인증서 호스트 이름을 확인하는 데 사용되는 선택적 값.¹ 클라이언트는 이 값을 서버의 TLS 인증서 파일의 호스트명과 비교합니다.
`gitlab_kas_external_url`	클러스터 내 `agentk`의 사용자 대상 URL. 완전히 정규화된 도메인 또는 서브도메인², 또는 GitLab 외부 URL이 될 수 있습니다.³ 비어 있으면 기본적으로 GitLab 외부 URL로 설정됩니다.
`gitlab_rails['gitlab_kas_external_url']`	클러스터 내 `agentk`의 사용자 대상 URL. 비어 있으면 `gitlab_kas_external_url`로 기본 설정됩니다.
`gitlab_rails['gitlab_kas_external_k8s_proxy_url']`	Kubernetes API 프록시를 위한 사용자 대상 URL. 비어 있으면 `gitlab_kas_external_url`을 기반으로 하는 URL로 설정됩니다.
`gitlab_rails['gitlab_kas_internal_url']`	GitLab 백엔드가 KAS와 통신하기 위해 사용하는 내부 URL.

각주:

OWN_PRIVATE_API_URL 또는 OWN_PRIVATE_API_SCHEME이 grpcs로 시작할 때 TLS를 사용하여 외부 연결용 TLS가 활성화됩니다.
예: wss://kas.gitlab.example.com/.
예: wss://gitlab.example.com/-/kubernetes-agent/.

GitLab Helm Chart에 대한 내용

GitLab-KAS 차트를 사용하는 방법을 확인하세요.

Kubernetes API 프록시 쿠키

GitLab 15.10에 도입되었으며 기본으로 비활성화된 피처 플래그인 kas_user_access 및 kas_user_access_project가 있습니다.
GitLab 16.1에서는 kas_user_access 및 kas_user_access_project 피처 플래그가 활성화되었습니다.
GitLab 16.2에서는 kas_user_access 및 kas_user_access_project 피처 플래그가 제거되었습니다.

KAS는 Kubernetes API 요청을 GitLab 에이전트로 프록시하며 다음 중 하나로 이루어집니다:

사용자 자격 증명으로 인증하기 위해 Rails는 GitLab 프론트엔드에 대해 cookie를 설정합니다. 이 쿠키는 _gitlab_session 쿠키와 유사한 암호화된 세션 ID를 포함하는 _gitlab_kas라고 하며, 사용자를 인증하고 권한을 부여하기 위해 모든 요청에 대해 KAS 프록시 엔드포인트로 보내져야 합니다.

문제 해결

쿠버네티스용 에이전트 서버를 사용하는 도중 문제가 발생하면 다음 명령을 실행하여 서비스 로그를 확인하십시오:

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

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

또한 개별 에이전트 문제를 해결할 수도 있습니다.

구성 파일을 찾을 수 없음

다음과 같은 오류 메시지가 표시되는 경우:

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`

Self-Managed형 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'

Kubernetes용 GitLab 에이전트 서버(KAS) 설치

설치 옵션

Linux 패키지 설치용

단일 노드에서 비활성화

KAS를 UNIX 소켓으로 수신하도록 설정

여러 노드에서 활성화

에이전트 서버 노드 설정

GitLab Helm Chart에 대한 내용

Kubernetes API 프록시 쿠키

문제 해결

구성 파일을 찾을 수 없음

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

도움말

기능 사용 가능성과 제품 평가판

도움받기