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

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

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

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

KAS라는 약어는 이전 이름인 Kubernetes agent server를 나타냅니다.

Kubernetes용 에이전트 서버는 GitLab.com에서 wss://kas.gitlab.com에 설치되어 사용 가능합니다.

자체 관리하는 GitLab을 사용하는 경우, 기본적으로 에이전트 서버가 설치되어 사용 가능합니다.

설치 옵션

GitLab 관리자 역할을 수행하는 경우, 에이전트 서버 설치를 제어할 수 있습니다:

리눅스 패키지 설치용.
GitLab Helm 차트 설치용.

리눅스 패키지 설치용

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

단일 노드에서 비활성화

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

/etc/gitlab/gitlab.rb를 편집하세요:
```
gitlab_kas['enable'] = false  
```
GitLab 재구성하기.

UNIX 소켓에서 KAS 수신 구성

프록시 뒤에서 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' # private API 엔드포인트에서 TLS 사용 시 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/'  

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

이 경우, OWN_PRIVATE_API_CIDR를 구성하여 kas가 OWN_PRIVATE_API_URL을 동적으로 구성하도록 할 수 있습니다:

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

GitLab 재구성하기.

에이전트 서버 노드 설정

설정	설명
`gitlab_kas['private_api_listen_address']`	에이전트 서버가 수신하는 주소. `0.0.0.0` 또는 클러스터의 다른 노드에서 접근 가능한 IP 주소로 설정합니다.
`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가 활성화됩니다.
예: wss://kas.gitlab.example.com/.
예: 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 에이전트에 프록시합니다.

사용자 자격 증명으로 인증하기 위해 Rails는 GitLab 프런트엔드를 위해 쿠키를 설정합니다.

이 쿠키는 _gitlab_kas라고 하며 암호화된

세션 ID를 포함하고 있으며, _gitlab_session 쿠키와 유사합니다.

_gitlab_kas 쿠키는 모든 요청 시 KAS 프록시 엔드포인트에 사용자 인증 및 권한 부여를 위해 전송되어야 합니다.

수용 가능한 에이전트 활성화

Tier: Ultimate Offering: Self-managed

History

Introduced in GitLab 17.4.

수용 가능한 에이전트는 GitLab 인스턴스와 네트워크 연결을 설정할 수 없는 Kubernetes 클러스터와 통합할 수 있도록 해주지만, GitLab에 의해 연결될 수 있습니다.

수용 가능한 에이전트를 활성화하려면:

왼쪽 사이드바의 맨 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
GitLab Agent for Kubernetes를 확장합니다.
Enable receptive mode 토글을 켭니다.

문제 해결

Kubernetes에 대한 에이전트 서버를 사용할 때 문제가 발생하면, 다음 명령어를 실행하여 서비스 로그를 확인합니다:

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`

셀프 관리 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)

설치 옵션

리눅스 패키지 설치용

단일 노드에서 비활성화

UNIX 소켓에서 KAS 수신 구성

여러 노드에서 활성화

에이전트 서버 노드 설정

GitLab Helm 차트용

Kubernetes API 프록시 쿠키

수용 가능한 에이전트 활성화

문제 해결

구성 파일을 찾을 수 없음

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

도움말

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

도움받기