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

• 러너: Job Router와 Runner Controllers를 사용하려면 필요합니다.
• Kubernetes 클러스터: Kubernetes용 에이전트를 사용하려면 필요합니다.

KAS는 이전에 Kubernetes Agent Server로 불렸습니다. Kubernetes를 넘어 확장된 역할을 반영하기 위해 이름이 변경되었습니다.

GitLab Relay (KAS)는 GitLab.com에 설치되어 grpcs://kas.gitlab.com에서 사용할 수 있습니다. WebSocket 주소 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 examples, pick one:

gitlab_kas['private_api_listen_address'] = 'A.B.C.D:8155' # Listen on a particular IPv4. Each node must use its own unique IP.
# gitlab_kas['private_api_listen_address'] = '[A:B:C::D]:8155' # Listen on a particular IPv6. Each node must use its own unique IP.
# gitlab_kas['private_api_listen_address'] = 'kas-N.gitlab.example.com:8155' # Listen on all IPv4 and IPv6 interfaces that the DNS name resolves to. Each node must use its own unique domain.
# gitlab_kas['private_api_listen_address'] = ':8155' # Listen on all IPv4 and IPv6 interfaces.
# gitlab_kas['private_api_listen_address'] = '0.0.0.0:8155' # Listen on all IPv4 interfaces.
# gitlab_kas['private_api_listen_address'] = '[::]:8155' # Listen on all IPv6 interfaces.

# Uncomment below to enable KAS to KAS TLS communication
# 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>' # Add if you want to use TLS for KAS->KAS communication. This name is used to verify the TLS certificate host name instead of the host in the URL of the destination KAS.
  '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 examples, pick one. Each node must use its own unique IP or DNS name.
  # Use grpcs:// when using TLS on the private API endpoint.

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

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

히스토리

• GitLab 17.8.1에서 OWN_PRIVATE_API_CIDR에 다중 CIDR 지원이 추가되었습니다.

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

정확한 IP 주소나 호스트 이름을 설정할 수 없다면 OWN_PRIVATE_API_CIDR을 구성해, 하나 이상의 CIDR을 기반으로 KAS가 OWN_PRIVATE_API_URL을 동적으로 구성하도록 설정할 수 있습니다:

이 방식을 사용하면 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. 사설 API 엔드포인트에서 TLS를 사용한다면 OWN_PRIVATE_API_SCHEME=grpcs를 구성합니다. 기본적으로 KAS는 grpc 스킴을 사용합니다.

gitlab_kas['env'] = {
  # 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8', # IPv4 example
  # 'OWN_PRIVATE_API_CIDR' => '2001:db8:8a2e:370::7334/64', # IPv6 example
  # 'OWN_PRIVATE_API_CIDR' => '10.0.0.0/8,2001:db8:8a2e:370::7334/64', # multiple CIRDs example

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

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

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 값에 따라 필터링됩니다.

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

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

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

# gitlab_kas['private_api_listen_network'] = 'tcp' # this is the default value, no need to set it.
gitlab_kas['private_api_listen_address'] = ':8155' # Listen on all IPv4 and IPv6 interfaces

예시 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에서 네트워크 제한이 적용된 내부 엔드포인트는 다음과 같이 구성합니다:

# Internal endpoint (network-restricted)
server {
  listen 8443 ssl http2;
  server_name kas-internal.example.com;

  # Optional: 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. OWN_PRIVATE_API_URL 또는 OWN_PRIVATE_API_SCHEME 이 grpcs로 시작하면 아웃바운드 연결에 TLS가 활성화됩니다.
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' # If you want to configure multiple KAS nodes that are behind an internal LB, then use 'grpc://:<port>'
gitlab_rails['gitlab_kas_external_k8s_proxy_url'] = 'https://kas.example.com/-/kubernetes-agent/k8s-proxy/'

각 KAS 노드에서 다음을 설정합니다:

### External URL
external_url 'https://kas.example.com'

### Avoid running unnecessary services ###
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

### Prevent database connections during 'gitlab-ctl reconfigure' ###
gitlab_rails['rake_cache_clear'] = false
gitlab_rails['auto_migrate'] = false

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

# Uncomment below if using Redis high availability with 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 Relay (KAS)는 다음 중 하나를 사용해 Kubernetes API 요청을 Kubernetes용 GitLab 에이전트로 프록시합니다:

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

사용자 자격 증명으로 인증할 때 Rails는 GitLab 프론트엔드용 쿠키를 설정합니다. 이 쿠키의 이름은 _gitlab_kas 이며, _gitlab_session 쿠키처럼 암호화된 세션 ID를 담고 있습니다. _gitlab_kas 쿠키는 사용자를 인증하고 인가하기 위해 모든 요청과 함께 KAS 프록시 엔드포인트로 전송되어야 합니다.

수신 에이전트 활성화#

히스토리

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

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

사전 요구 사항:

• 관리자 액세스 권한.

수신 에이전트를 활성화하려면 다음 단계를 따릅니다.

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에서 추적됩니다.