GitLab Relay (KAS)는 GitLab과 함께 설치되는 컴포넌트입니다. GitLab과 외부 시스템 간의 양방향 gRPC 통신을 위한 중앙 통신 릴레이 역할을 하며, 다음을 포함합니다:

• Runner: Job Router 및 Runner Controllers 사용에 필요합니다.
• Kubernetes 클러스터: Kubernetes용 에이전트 사용에 필요합니다.

KAS는 이전에 Kubernetes Agent Server로 알려졌으며, Kubernetes를 넘어 발전된 역할을 반영하기 위해 이름이 변경되었습니다.

GitLab Relay (KAS)는 GitLab.com의 wss://kas.gitlab.com에 설치되어 사용 가능합니다. GitLab Self-Managed를 사용하는 경우 기본적으로 GitLab Relay (KAS)가 설치되어 사용 가능합니다.

설치 옵션#

GitLab 관리자는 GitLab Relay (KAS) 설치를 제어할 수 있습니다:

• Linux 패키지 설치의 경우.
• GitLab Helm 차트 설치의 경우.

Linux 패키지 설치의 경우#

Linux 패키지 설치의 GitLab Relay (KAS)는 단일 노드 또는 여러 노드에서 동시에 활성화할 수 있습니다. 기본적으로 GitLab Relay (KAS)는 활성화되어 ws://gitlab.example.com/-/kubernetes-agent/에서 사용 가능합니다.

단일 노드에서 비활성화#

단일 노드에서 GitLab Relay (KAS)를 비활성화하려면:

1. /etc/gitlab/gitlab.rb를 편집합니다:

   gitlab_kas['enable'] = false
   

2. GitLab을 재구성합니다.

여러 노드에서 KAS 활성화#

KAS 인스턴스는 잘 알려진 위치에서 Redis에 개인 주소를 등록하여 서로 통신합니다. 각 KAS는 다른 인스턴스가 도달할 수 있도록 개인 주소 세부 정보를 표시하도록 구성되어야 합니다.

여러 노드에서 KAS를 활성화하려면:

1. 공통 구성을 추가합니다.

2. 다음 옵션 중 하나에서 구성을 추가합니다:

   • 옵션 1 - 명시적 수동 구성
   • 옵션 2 - 자동 CIDR 기반 구성
   • 옵션 3 - 리스너 구성 기반 자동 구성

3. GitLab을 재구성합니다.

4. (선택 사항) 별도의 GitLab Rails 및 Sidekiq 노드가 있는 멀티 서버 환경을 사용하는 경우 Sidekiq 노드에서 KAS를 활성화합니다.

공통 구성#

각 KAS 노드에서 /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>'

# private_api_listen_address 예시, 하나를 선택합니다:

gitlab_kas['private_api_listen_address'] = 'A.B.C.D:8155' # 특정 IPv4에서 수신. 각 노드는 고유한 IP를 사용해야 합니다.
# gitlab_kas['private_api_listen_address'] = '[A:B:C::D]:8155' # 특정 IPv6에서 수신. 각 노드는 고유한 IP를 사용해야 합니다.
# gitlab_kas['private_api_listen_address'] = 'kas-N.gitlab.example.com:8155' # DNS 이름이 확인되는 모든 IPv4 및 IPv6 인터페이스에서 수신. 각 노드는 고유한 도메인을 사용해야 합니다.
# gitlab_kas['private_api_listen_address'] = ':8155' # 모든 IPv4 및 IPv6 인터페이스에서 수신.
# gitlab_kas['private_api_listen_address'] = '0.0.0.0:8155' # 모든 IPv4 인터페이스에서 수신.
# gitlab_kas['private_api_listen_address'] = '[::]:8155' # 모든 IPv6 인터페이스에서 수신.

# KAS to KAS TLS 통신을 활성화하려면 아래의 주석을 해제합니다
# gitlab_kas['private_api_certificate_file'] = '<path_to_kas_server_crt_file>'
# gitlab_kas['private_api_key_file'] = '<path_to_kas_server_certificate_key>'

gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_HOST' => '<server-name-from-cert>' # KAS->KAS 통신에 TLS를 사용하려면 추가합니다. 이 이름은 대상 KAS의 URL에 있는 호스트 대신 TLS 인증서 호스트 이름을 확인하는 데 사용됩니다.
  'SSL_CERT_DIR' => "/opt/gitlab/embedded/ssl/certs/",
}

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

다음과 같은 내부 주소를 수신하도록 private_api_listen_address를 설정하지 마세요:

• localhost
• 127.0.0.1 또는 ::1과 같은 루프백 IP 주소
• UNIX 소켓

다른 KAS 노드는 이러한 주소에 도달할 수 없습니다.

단일 노드 구성의 경우 private_api_listen_address를 내부 주소를 수신하도록 설정할 수 있습니다.

옵션 1 - 명시적 수동 구성#

각 KAS 노드에서 /etc/gitlab/gitlab.rb 파일을 편집하고 OWN_PRIVATE_API_URL 환경 변수를 명시적으로 설정합니다:

gitlab_kas['env'] = {
  # OWN_PRIVATE_API_URL 예시, 하나를 선택합니다. 각 노드는 고유한 IP 또는 DNS 이름을 사용해야 합니다.
  # private API 엔드포인트에서 TLS를 사용할 때는 grpcs://를 사용합니다.

  'OWN_PRIVATE_API_URL' => 'grpc://A.B.C.D:8155' # IPv4
  # 'OWN_PRIVATE_API_URL' => 'grpcs://A.B.C.D:8155' # IPv4 + TLS
  # 'OWN_PRIVATE_API_URL' => 'grpc://[A:B:C::D]:8155' # IPv6
  # 'OWN_PRIVATE_API_URL' => 'grpc://kas-N-private-api.gitlab.example.com:8155' # DNS 이름
}

옵션 2 - 자동 CIDR 기반 구성#

히스토리

• GitLab 16.5.0에서 도입되었습니다.
• GitLab 17.8.1에서 OWN_PRIVATE_API_CIDR에 여러 CIDR 지원이 추가되었습니다.

예를 들어 KAS 호스트에 IP 주소와 호스트 이름이 동적으로 할당되는 경우 OWN_PRIVATE_API_URL 변수에 정확한 IP 주소 또는 호스트 이름을 설정하지 못할 수 있습니다.

정확한 IP 주소 또는 호스트 이름을 설정할 수 없는 경우 OWN_PRIVATE_API_CIDR을 구성하여 하나 이상의 CIDR을 기반으로 OWN_PRIVATE_API_URL을 동적으로 구성하도록 KAS를 설정할 수 있습니다.

이 방법을 사용하면 CIDR이 변경되지 않는 한 각 KAS 노드가 정적 구성을 사용할 수 있습니다.

각 KAS 노드에서 /etc/gitlab/gitlab.rb 파일을 편집하여 OWN_PRIVATE_API_URL URL을 동적으로 구성합니다:

1. 공통 구성에서 OWN_PRIVATE_API_URL을 주석 처리하여 이 변수를 비활성화합니다.
2. KAS 노드가 수신하는 네트워크를 지정하도록 OWN_PRIVATE_API_CIDR을 구성합니다. KAS를 시작하면 지정된 CIDR과 일치하는 호스트 주소를 선택하여 사용할 개인 IP 주소를 결정합니다.
3. 다른 포트를 사용하도록 OWN_PRIVATE_API_PORT를 구성합니다. 기본적으로 KAS는 private_api_listen_address 파라미터의 포트를 사용합니다.
4. private API 엔드포인트에서 TLS를 사용하는 경우 OWN_PRIVATE_API_SCHEME=grpcs를 구성합니다. 기본적으로 KAS는 grpc 스킴을 사용합니다.

gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8', # IPv4 예시
  # 'OWN_PRIVATE_API_CIDR' => '2001:db8:8a2e:370::7334/64', # IPv6 예시
  # 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8,2001:db8:8a2e:370::7334/64', # 여러 CIDR 예시

  # 'OWN_PRIVATE_API_PORT' => '8155',
  # 'OWN_PRIVATE_API_SCHEME' => 'grpc',
}

옵션 3 - 리스너 구성 기반 자동 구성#

히스토리

• GitLab 16.5.0에서 도입되었습니다.
• private_api_listen_network 값을 기반으로 IPv4 및 IPv6 주소를 필터링하고 모든 비루프백 IP 주소를 수신 및 게시하도록 KAS가 업데이트되었습니다.

KAS 노드는 private_api_listen_network 및 private_api_listen_address 설정을 기반으로 사용 가능한 IP 주소를 결정할 수 있습니다:

• private_api_listen_address가 고정 IP 주소와 포트 번호(예: ip:port)로 설정된 경우 이 IP 주소를 사용합니다.
• private_api_listen_address에 IP 주소가 없거나(예: :8155) 지정되지 않은 IP 주소(예: [::]:8155 또는 0.0.0.0:8155)가 있는 경우 KAS는 모든 비루프백 및 비링크-로컬 IP 주소를 노드에 할당합니다. IPv4 및 IPv6 주소는 private_api_listen_network 값을 기반으로 필터링됩니다.
• private_api_listen_address가 hostname:PORT(예: kas-N-private-api.gitlab.example.com:8155)인 경우 KAS는 DNS 이름을 확인하고 모든 IP 주소를 노드에 할당합니다. 이 모드에서 KAS는 첫 번째 IP 주소에서만 수신합니다(Go 표준 라이브러리에 의해 정의된 동작). IPv4 및 IPv6 주소는 private_api_listen_network 값을 기반으로 필터링됩니다.

모든 IP 주소에서 KAS의 개인 API 주소를 노출하기 전에 이 작업이 조직의 보안 정책과 충돌하지 않는지 확인합니다. 개인 API 엔드포인트는 모든 요청에 대해 유효한 인증 토큰이 필요합니다.

각 KAS 노드에서 /etc/gitlab/gitlab.rb 파일을 편집합니다:

예시 1. 모든 IPv4 및 IPv6 인터페이스에서 수신:

# gitlab_kas['private_api_listen_network'] = 'tcp' # 이것이 기본값이므로 설정할 필요가 없습니다.
gitlab_kas['private_api_listen_address'] = ':8155' # 모든 IPv4 및 IPv6 인터페이스에서 수신

예시 2. 모든 IPv4 인터페이스에서 수신:

gitlab_kas['private_api_listen_network'] = 'tcp4'
gitlab_kas['private_api_listen_address'] = ':8155'

예시 3. 모든 IPv6 인터페이스에서 수신:

gitlab_kas['private_api_listen_network'] = 'tcp6'
gitlab_kas['private_api_listen_address'] = ':8155'

환경 변수를 사용하여 OWN_PRIVATE_API_URL을 구성하는 스킴과 포트를 재정의할 수 있습니다:

gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_PORT' => '8155',
  # 'OWN_PRIVATE_API_SCHEME' => 'grpc',
}

여러 KAS 인스턴스와 함께 로드 밸런서 또는 리버스 프록시 사용#

KAS는 다른 포트에서 트래픽을 처리합니다:

• 포트 8150 (listen_address): 에이전트 연결 (WebSocket/gRPC)

• 포트 8153 (internal_api_listen_address): GitLab Rails API (gRPC)

  [!warning] 포트 8153을 공개적으로 노출하지 마세요. 포트가 인증되더라도 GitLab Rails 인스턴스만 액세스할 수 있어야 합니다.

로드 밸런서 또는 리버스 프록시를 사용할 때 KAS를 보호하려면 두 개의 별도 엔드포인트를 구성합니다:

• 외부 엔드포인트: 포트 8150 (에이전트용)
• 내부 엔드포인트: 포트 8153 (GitLab Rails 전용, 네트워크 또는 방화벽으로 제한)

이 분리는 내부 API가 공개 액세스로부터 격리되도록 보장합니다.

예를 들어 NGINX에서 네트워크 제한이 있는 내부 엔드포인트를 구성합니다:

# 내부 엔드포인트 (네트워크 제한)
server {
  listen 8443 ssl http2;
  server_name kas-internal.example.com;

  # 선택 사항: allow 10.0.1.0/24; deny all;

  location /gitlab.agent. {
    grpc_pass grpc://kas-backend:8153;
  }
}

별도의 엔드포인트를 사용하도록 GitLab을 구성합니다(/etc/gitlab/gitlab.rb):

gitlab_rails['gitlab_kas_external_url'] = 'wss://kas-external.example.com'
gitlab_rails['gitlab_kas_internal_url'] = 'grpcs://kas-internal.example.com:8443'
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://kas-external.example.com/k8s-proxy/'

주요 구성 사항:

• 내부 트래픽에 별도의 도메인, 포트 또는 IP 제한을 사용합니다.
• 클라우드 로드 밸런서의 경우 포트 8150 및 8153에 대한 별도의 대상 그룹을 구성합니다.

GitLab Relay (KAS) 노드 설정#

각주:

1. 아웃바운드 연결에 대한 TLS는 OWN_PRIVATE_API_URL 또는 OWN_PRIVATE_API_SCHEME이 grpcs로 시작할 때 활성화됩니다.
2. 예를 들어 wss://kas.gitlab.example.com/.
3. 예를 들어 wss://gitlab.example.com/-/kubernetes-agent/.

독립형 KAS 노드 구성#

다른 컴포넌트와 별도로 KAS를 실행하도록 Omnibus를 구성합니다.

각 Rails 노드에서:

## KAS Config
gitlab_kas['enable'] = false

gitlab_rails['gitlab_kas_enabled'] = true
gitlab_rails['gitlab_kas_external_url'] = 'wss://kas.example.com/-/kubernetes-agent/'
gitlab_rails['gitlab_kas_internal_url'] = 'grpc://:8153' # 내부 LB 뒤에 있는 여러 KAS 노드를 구성하려면 'grpc://:<port>' 사용
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://kas.example.com/-/kubernetes-agent/k8s-proxy/'

각 KAS 노드에서:

### 외부 URL
external_url 'https://kas.example.com'

### 불필요한 서비스 실행 방지 ###
gitaly['enable'] = false
gitlab_workhorse['enable'] = false
nginx['enable'] = true
postgresql['enable'] = false
prometheus['enable'] = false
puma['enable'] = false
redis['enable'] = false
sidekiq['enable'] = false

### 'gitlab-ctl reconfigure' 중 데이터베이스 연결 방지 ###
gitlab_rails['rake_cache_clear'] = false
gitlab_rails['auto_migrate'] = false

gitlab_kas['redis_password'] = '<redis_password>'

# Redis 고가용성(Sentinel) 사용 시 아래 주석 해제
# gitlab_kas['redis_sentinels'] = [
#  {host: '', port: 26379},
#  {host: '', port: 26379},
#  {host: '', port: 26379},
# ]
# gitlab_kas['redis_sentinels_master_name'] = 'gitlab-redis'
# gitlab_kas['redis_sentinels_password'] = '<redis_sentinels_password>'

### GitLab Relay (KAS) ###
gitlab_kas['enable'] = true
gitlab_kas_external_url 'wss://kas.example.com/-/kubernetes-agent/'
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'] = ':8155'

gitlab_kas['listen_address'] = ':8150'
gitlab_kas['observability_listen_address'] = ':8151'
gitlab_kas['internal_api_listen_address'] = ':8153'
gitlab_kas['kubernetes_api_listen_address'] = ':8154'

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에서 제거되었습니다.

GitLab Relay (KAS)는 Kubernetes API 요청을 다음을 통해 Kubernetes용 GitLab 에이전트에 프록시합니다:

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

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

수신 에이전트 활성화#

히스토리

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

수신 에이전트를 사용하면 GitLab이 GitLab 인스턴스에 네트워크 연결을 설정할 수 없지만 GitLab이 연결할 수 있는 Kubernetes 클러스터와 통합할 수 있습니다.

필수 조건:

• 관리자 액세스.

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

1. 오른쪽 상단에서 Admin을 선택합니다.
2. 왼쪽 사이드바에서 Settings > General을 선택합니다.
3. GitLab Agent for Kubernetes를 확장합니다.
4. Enable receptive mode 토글을 켭니다.

Kubernetes API 프록시 응답 헤더 허용 목록 구성#

히스토리

• GitLab 18.3에서 kas_k8s_api_proxy_response_header_allowlist라는 플래그와 함께 도입되었습니다. 기본적으로 비활성화됩니다.
• GitLab 18.7에서 일반적으로 사용 가능합니다. 기능 플래그 kas_k8s_api_proxy_response_header_allowlist가 제거되었습니다.

KAS의 Kubernetes API 프록시는 응답 헤더에 허용 목록을 사용합니다. 안전하고 잘 알려진 Kubernetes 및 HTTP 헤더는 기본적으로 허용됩니다.

허용된 응답 헤더 목록은 응답 헤더 허용 목록을 참조하세요.

기본 허용 목록에 없는 응답 헤더가 필요한 경우 KAS 구성에 응답 헤더를 추가할 수 있습니다.

추가 허용 응답 헤더를 추가하려면:

agent:
  kubernetes_api:
    extra_allowed_response_headers:
      - 'X-My-Custom-Header-To-Allow'

더 많은 응답 헤더 추가 지원은 이슈 550614에서 추적됩니다.

트러블슈팅#

GitLab Relay (KAS)를 사용하는 동안 문제가 발생하면 다음 명령을 실행하여 서비스 로그를 확인합니다:

kubectl logs -f -l=app=kas -n 

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 :443: connect: connection refused#

GitLab Self-Managed를 실행 중이고 다음 조건 중 하나라도 해당하는 경우:

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

GitLab Relay (KAS)가 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'

오류: x509: certificate signed by unknown authority#

GitLab URL에 도달하려고 할 때 이 오류가 발생하면 GitLab 인증서를 신뢰하지 않는다는 의미입니다.

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

1. GitLab Relay (KAS)를 재시작합니다:

gitlab-ctl restart gitlab-kas

오류: GRPC::DeadlineExceeded in Clusters::Agents::NotifyGitPushWorker#

이 오류는 클라이언트가 기본 타임아웃 시간(5초) 내에 응답을 받지 못할 때 발생할 수 있습니다. 문제를 해결하려면 /etc/gitlab/gitlab.rb 구성 파일을 수정하여 클라이언트 타임아웃을 늘릴 수 있습니다.

해결 단계#

1. 타임아웃 값을 늘리기 위해 다음 구성을 추가하거나 업데이트합니다:

gitlab_kas['client_timeout_seconds'] = "10"

1. GitLab을 재구성하여 변경 사항을 적용합니다:

gitlab-ctl reconfigure

참고#

특정 요구 사항에 맞게 타임아웃 값을 조정할 수 있습니다. 시스템 성능에 영향을 미치지 않고 문제가 해결되었는지 확인하려면 테스트를 권장합니다.

오류: Blocked Kubernetes API proxy response header#

Kubernetes 클러스터에서 Kubernetes API 프록시를 통해 사용자에게 HTTP 응답 헤더가 전달되지 않는 경우 KAS 로그 또는 Sentry 인스턴스에서 다음 오류를 확인합니다:

Blocked Kubernetes API proxy response header. Please configure extra allowed headers for your instance in the KAS config with `extra_allowed_response_headers` and have a look at the troubleshooting guide at https://docs.gitlab.com/administration/clusters/kas/#troubleshooting.

이 오류는 Kubernetes API 프록시가 응답 헤더 허용 목록에 정의되지 않아 응답 헤더를 차단했음을 의미합니다.

응답 헤더 추가에 대한 자세한 내용은 응답 헤더 허용 목록 구성을 참조하세요.

더 많은 응답 헤더 추가 지원은 이슈 550614에서 추적됩니다.