설치 옵션
- Linux 패키지 설치용
  - 단일 노드에서 비활성화
    - KAS를 UNIX 소켓에서 수신하도록 구성
  - 여러 노드에서 활성화
    - 에이전트 서버 노드 설정
- GitLab Helm 차트용
Kubernetes API 프록시 쿠키
문제 해결

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

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

GitLab 13.10에서 소개된 GitLab 에이전트 서버(KAS)는 wss://kas.gitlab.com에서 GitLab.com에 사용 가능해졌습니다.
GitLab 14.5에서 GitLab Premium에서 GitLab Free로 이동되었습니다.

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

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

Kubernetes용 에이전트 서버는 wss://kas.gitlab.com에서 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를 사용하는 경우 개인 API 엔드포인트에 grpcs://를 사용합니다
     
  # '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 시작 시 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']`	에이전트 서버가 수신하는 주소입니다. `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 주소로 설정합니다. 클러스터의 다른 노드에서 접근 가능해야 합니다.
`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입니다.

각주:

예: 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가 활성화됨: GitLab 16.1.
피처 플래그 kas_user_access 및 kas_user_access_project가 제거됨: GitLab 16.2.

KAS는 Kubernetes API 요청을 GitLab 에이전트로 프록시하며 다음 중 하나를 사용합니다:

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

문제 해결

Kubernetes용 에이전트 서버를 사용하는 동안 문제가 발생하면 다음 명령을 실행하여 서비스 로그를 확인하세요.

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

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

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

GitOps: 프로젝트 정보 가져오기 실패

다음 오류 메시지를 받으면:

{"level":"warn","time":"2020-10-30T08:37:26.123Z","msg":"GitOps: failed to get project info","agent_id":4,"project_id":"root/kas-manifest001","error":"error kind: 0; status: 404"}

매니페스트에서 지정된 프로젝트(root/kas-manifest001)가 존재하지 않거나 매니페스트가 보관된 프로젝트가 비공개인 경우입니다. 이 문제를 해결하려면 프로젝트 경로가 올바른지 확인하고 프로젝트의 가시성이 공개로 설정되어 있는지 확인하세요.

구성 파일을 찾을 수 없음

다음 오류 메시지를 받으면:

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 (KAS)용 GitLab 에이전트 서버 설치

설치 옵션

Linux 패키지 설치용

단일 노드에서 비활성화

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

여러 노드에서 활성화

에이전트 서버 노드 설정

GitLab Helm 차트용

Kubernetes API 프록시 쿠키

문제 해결

GitOps: 프로젝트 정보 가져오기 실패

구성 파일을 찾을 수 없음

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

도움말

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

도움받기