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

GitLab 에이전트 서버 설치하기(KAS)

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

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

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

쿠버네티스를 위한 에이전트 서버는 GitLab.com에서 wss://kas.gitlab.com의 주소로 설치되어 사용할 수 있습니다. Self-managed GitLab을 사용하는 경우, 기본적으로 에이전트 서버가 설치되어 있고 사용할 수 있습니다.

설치 옵션

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

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

리눅스 패키지 설치용

리눅스 패키지 설치에 대한 에이전트 서버는 단일 노드 또는 한 번에 여러 노드에 대해 활성화될 수 있습니다. 기본적으로, 에이전트 서버는 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를 사용하는 경우, 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 주석 처리하십시오.
kas는 지정된 CIDR에 대해 수신 대기하도록 구성됩니다. kas를 시작할 때, kas는 호스트에 할당된 IP 주소를 확인하고 지정된 CIDR과 일치하는 주소를 자신의 개인 IP 주소로 사용합니다.
기본적으로 kas는 private_api_listen_address 매개변수의 포트를 사용합니다. 다른 포트를 사용하려면 OWN_PRIVATE_API_PORT를 구성하십시오.
기본적으로 kas는 grpc 스키마를 사용합니다. 개인 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 Chart에 대한

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

GitLab 17.4에서 도입되었습니다.

수용 에이전트는 GitLab이 Kubernetes 클러스터와 통신 연결을 설정할 수 없는 지역에서 통합할 수 있도록 합니다.

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

왼쪽 사이드바에서 맨 아래에서 관리자를 선택하세요.
설정 > 일반을 선택하세요.
GitLab 에이전트용 Kubernetes를 확장하세요.
수용 모드 활성화 토글을 켜세요.

문제 해결

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'

GitLab 에이전트 서버 설치하기(KAS)

설치 옵션

리눅스 패키지 설치용

단일 노드에서 비활성화

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

여러 노드에서 활성화

에이전트 서버 노드 설정

GitLab Helm Chart에 대한

Kubernetes API 프록시 쿠키

수용 에이전트 활성화

문제 해결

구성 파일을 찾을 수 없음

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

도움말

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

도움받기