Kubernetes 클러스터를 GitLab에 연결하려면 클러스터에 에이전트를 설치해야 합니다.

사전 요구 사항#

클러스터에 에이전트를 설치하려면 다음이 필요합니다:

• 로컬 터미널에서 연결할 수 있는 기존 Kubernetes 클러스터. 클러스터가 없다면 다음과 같은 클라우드 공급자에서 생성할 수 있습니다:
  • Amazon Elastic Kubernetes Service (EKS)
  • Azure Kubernetes Service (AKS)
  • Digital Ocean
  • Google Kubernetes Engine (GKE)
  • 대규모 인프라 리소스 관리에는 Infrastructure as Code 기법을 사용하는 편이 좋습니다.
• 에이전트 서버에 대한 액세스:
  • GitLab.com에서 에이전트 서버는 grpcs://kas.gitlab.com에서 사용할 수 있습니다. WebSocket 주소 wss://kas.gitlab.com도 사용할 수 있습니다.
  • GitLab Self-Managed에서는 GitLab 관리자가 에이전트 서버를 설정해야 합니다. 설정 후에는 기본적으로 grpcs://gitlab.example.com에서 사용할 수 있으며, HTTPS가 없거나 상대 URL 루트를 사용하는 인스턴스에서는 wss://gitlab.example.com/-/kubernetes-agent/에서 사용할 수 있습니다.
  • GitLab Dedicated에서 에이전트 서버는 wss://kas.<instance-domain>에서 사용할 수 있습니다. 예를 들면 wss://kas.example.gitlab-dedicated.com 입니다. GitLab Dedicated 인스턴스에 사용자 지정 도메인을 사용한다면 KAS 서비스에도 사용자 지정 도메인을 사용할 수 있습니다.

Flux 지원으로 에이전트 부트스트랩 (권장)#

GitLab CLI(glab)와 Flux로 에이전트를 부트스트랩하여 설치할 수 있습니다.

사전 요구 사항:

• 다음 명령줄 도구가 설치되어 있어야 합니다:
  • glab
  • kubectl
  • flux
• kubectl 및 flux로 동작하는 로컬 클러스터 연결이 있어야 합니다.
• flux bootstrap으로 클러스터에 Flux를 부트스트랩해야 합니다.
  • Flux와 에이전트를 호환되는 디렉터리에 부트스트랩해야 합니다. --path 옵션으로 Flux를 부트스트랩했다면 glab cluster agent bootstrap 명령의 --manifest-path 옵션에 같은 값을 전달해야 합니다.

에이전트를 설치하려면 다음 중 하나를 수행합니다:

• 대상 프로젝트의 Git 리포지터리 디렉터리 안에서 glab cluster agent bootstrap을 실행합니다:

  glab cluster agent bootstrap <agent-name> --manifest-path <same_path_used_in_flux_bootstrap>
  

• 대상 프로젝트의 Git 리포지터리 밖에서 명령을 실행해야 한다면 glab -R path-with-namespace cluster agent bootstrap을 실행합니다:

  glab -R <full/path/to/project> cluster agent bootstrap <agent-name> --manifest-path <same_path_used_in_flux_bootstrap>
  

이 명령은 기본적으로 다음을 수행합니다:

1. 에이전트를 등록합니다.
2. 에이전트를 구성합니다.
3. 에이전트용 대시보드가 포함된 환경을 구성합니다.
4. 에이전트 토큰을 생성합니다.
5. 클러스터에 에이전트 토큰이 담긴 Kubernetes 시크릿을 생성합니다.
6. Flux Helm 리소스를 Git 리포지터리에 커밋합니다.
7. Flux 재조정을 트리거합니다.

사용자 지정 옵션은 glab cluster agent bootstrap --help를 실행하여 확인합니다. 최소한 --path <flux_manifests_directory> 옵션은 사용하는 편이 좋습니다.

에이전트 수동 설치#

클러스터에 에이전트를 설치하는 과정은 세 단계로 이루어집니다:

1. 선택 사항. 에이전트 구성 파일을 생성합니다.
2. 에이전트를 GitLab에 등록합니다.
3. 클러스터에 에이전트를 설치합니다.

이 과정을 따라가는 영상을 시청합니다.

에이전트 구성 파일 생성#

에이전트는 구성 설정에 GitLab 프로젝트의 YAML 파일을 사용합니다. 에이전트 구성 파일 추가는 선택 사항입니다. 다음 경우에는 이 파일을 생성해야 합니다:

• GitLab CI/CD 워크플로를 사용하면서 다른 프로젝트나 그룹에 에이전트 액세스를 허가하려는 경우.
• 특정 프로젝트 또는 그룹 멤버가 Kubernetes에 액세스하도록 허용하는 경우.

에이전트 구성 파일을 생성하려면 다음 단계를 수행합니다:

1. 에이전트 이름을 정합니다. 에이전트 이름은 RFC 1123의 DNS 레이블 표준을 따릅니다. 이름은 다음 조건을 충족해야 합니다:

   • 프로젝트 안에서 고유해야 합니다.
   • 63자를 넘지 않아야 합니다.
   • 소문자 영숫자 또는 -만 포함해야 합니다.
   • 영숫자로 시작해야 합니다.
   • 영숫자로 끝나야 합니다.

2. 리포지터리의 기본 브랜치에서 다음 위치에 에이전트 구성 파일을 생성합니다:

   .gitlab/agents/<agent-name>/config.yaml
   

지금은 파일을 비워 두고 나중에 구성해도 됩니다.

에이전트를 GitLab에 등록#

옵션 1: 에이전트가 GitLab에 연결#

GitLab UI에서 바로 새 에이전트 레코드를 생성할 수 있습니다. 에이전트 구성 파일을 만들지 않고도 에이전트를 등록할 수 있습니다.

클러스터에 에이전트를 설치하려면 먼저 에이전트를 등록해야 합니다. 에이전트를 등록하려면 다음 단계를 수행합니다:

1. 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다. 에이전트 구성 파일이 있다면 해당 파일은 이 프로젝트에 있어야 합니다. 클러스터 매니페스트 파일도 이 프로젝트에 두는 편이 좋습니다.

2. Operate > Kubernetes clusters를 선택합니다.

3. **Connect a cluster (agent)**를 선택합니다.

4. Name of new agent 필드에 에이전트의 고유한 이름을 입력합니다.

   • 이 이름의 에이전트 구성 파일이 이미 있으면 해당 파일이 사용됩니다.
   • 이 이름에 해당하는 구성이 없으면 기본 구성으로 새 에이전트가 생성됩니다.

5. Create and register를 선택합니다.

6. GitLab이 에이전트용 액세스 토큰을 생성합니다. 클러스터에 에이전트를 설치할 때 이 토큰이 필요합니다.

   [!warning] 에이전트 액세스 토큰은 안전하게 보관합니다. 악의적인 행위자가 이 토큰으로 에이전트 구성 프로젝트의 소스 코드에 접근하거나, GitLab 인스턴스의 모든 공개 프로젝트 소스 코드에 접근하거나, 매우 특정한 조건에서는 Kubernetes 매니페스트를 획득할 수 있습니다.

7. Recommended installation method 아래의 명령을 복사합니다. 클러스터에 에이전트를 설치할 때 한 줄 설치 방식을 사용하려면 이 명령이 필요합니다.

옵션 2: GitLab이 에이전트에 연결 (리셉티브 에이전트)#

히스토리

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

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

1. 옵션 1의 단계를 따라 클러스터에 에이전트를 등록합니다. 에이전트 토큰과 설치 명령은 나중에 쓰도록 저장해 두되, 아직 에이전트를 설치하지는 않습니다.

2. 인증 방식을 준비합니다.

   GitLab과 에이전트 사이의 연결은 평문 gRPC(grpc://) 또는 암호화된 gRPC(grpcs://, 권장)를 사용할 수 있습니다. GitLab은 다음 방식으로 클러스터의 에이전트에 인증할 수 있습니다:

   • JWT 토큰. grpc://와 grpcs:// 구성 모두에서 사용할 수 있습니다. 이 방식에서는 클라이언트 인증서를 생성할 필요가 없습니다.

3. 클러스터 에이전트 API로 에이전트에 URL 구성을 추가합니다. URL 구성을 삭제하면 리셉티브 에이전트는 일반 에이전트가 됩니다. 리셉티브 에이전트는 한 번에 URL 구성 하나에만 연결할 수 있습니다.

4. 클러스터에 에이전트를 설치합니다. 에이전트를 등록할 때 복사한 명령을 사용하되 --set config.kasAddress=... 매개변수는 제거합니다.

   JWT 토큰 인증 예시입니다. 추가된 config.receptive.enabled=true 및 config.api.jwt 설정에 유의합니다:

   helm repo add gitlab https://charts.gitlab.io
   helm repo update
   helm upgrade --install my-agent gitlab/gitlab-agent \
    --namespace ns \
    --create-namespace \
    --set config.token=.... \
    --set config.receptive.enabled=true \
    --set config.api.jwtPublicKey=<public_key from the response>
   

GitLab이 새 에이전트로 연결을 시도하기 시작하기까지 최대 10분이 걸릴 수 있습니다.

클러스터에 에이전트 설치#

클러스터를 GitLab에 연결하려면 등록한 에이전트를 Helm으로 설치합니다.

리셉티브 에이전트를 설치하려면 GitLab이 에이전트에 연결 (리셉티브 에이전트)의 단계를 따릅니다.

Helm으로 에이전트 설치#

Helm으로 클러스터에 에이전트를 설치하려면 다음 단계를 수행합니다:

1. Helm CLI를 설치합니다.

2. 사용 중인 컴퓨터에서 터미널을 열고 클러스터에 연결합니다.

3. 에이전트를 GitLab에 등록할 때 복사한 명령을 실행합니다. 명령은 다음과 같은 형태입니다:

   helm repo add gitlab https://charts.gitlab.io
   helm repo update
   helm upgrade --install test gitlab/gitlab-agent \
       --namespace gitlab-agent-test \
       --create-namespace \
       --set image.tag=<current agentk version> \
       --set config.token=<your_token> \
       --set config.kasAddress=<address_to_GitLab_KAS_instance>
   

4. 선택 사항. Helm 설치를 사용자 지정합니다. 프로덕션 시스템에 에이전트를 설치한다면 서비스 계정의 권한을 제한하도록 Helm 설치를 사용자 지정하는 편이 좋습니다. 관련 사용자 지정 옵션은 아래에 설명되어 있습니다.

OCI 레지스트리에서 에이전트 설치#

https://charts.gitlab.io Helm 리포지터리를 추가하는 대신 OCI 레지스트리에서 에이전트를 직접 설치합니다.

사전 요구 사항:

• 차트 2.32.0 이상.
• Helm 3.8 이상.

OCI 레지스트리에서 에이전트를 직접 설치하려면 다음과 같이 합니다.

helm upgrade --install test oci://registry.gitlab.com/charts/charts.gitlab.io/release/gitlab-agent \
  --version <chart_version> \
  --namespace gitlab-agent-test \
  --create-namespace \
  --set image.tag=<current agentk version> \
  --set config.token=<your_token> \
  --set config.kasAddress=<address_to_GitLab_KAS_instance>

OCI 레지스트리에서 직접 가져올 때 Helm은 최신 차트 버전을 확인하지 않으므로 --version을 지정해야 합니다. 나중에 에이전트를 업데이트하려면 새 차트 버전으로 같은 명령을 실행합니다.

Helm 설치 사용자 지정#

GitLab이 생성하는 Helm 설치 명령은 기본적으로 다음을 수행합니다:

• 배포용 네임스페이스 gitlab-agent를 생성합니다(--namespace gitlab-agent). --create-namespace 플래그를 빼면 네임스페이스 생성을 건너뛸 수 있습니다.
• 에이전트용 서비스 계정을 설정하고 cluster-admin 역할을 할당합니다. 다음과 같이 조정할 수 있습니다:
  • helm install 명령에 --set serviceAccount.create=false를 추가하여 서비스 계정 생성을 건너뜁니다. 이 경우 serviceAccount.name을 기존 서비스 계정으로 설정해야 합니다.
  • helm install 명령에 --set rbac.useExistingRole <your role name>을 추가하여 서비스 계정에 할당할 역할을 지정합니다. 이 경우 서비스 계정이 사용할 수 있도록 권한이 제한된 역할을 미리 만들어 두어야 합니다.
  • helm install 명령에 --set rbac.create=false를 추가하여 역할 할당을 아예 건너뜁니다. 이 경우 ClusterRoleBinding을 직접 생성해야 합니다.
• 에이전트의 액세스 토큰용 Secret 리소스를 생성합니다. 토큰이 담긴 자체 시크릿을 사용하려면 토큰(--set token=...)을 생략하고 대신 --set config.secretName=<your secret name>을 사용합니다.
• agentk Pod용 Deployment 리소스를 생성합니다.

사용할 수 있는 사용자 지정 항목 전체 목록은 Helm 차트의 README를 참고합니다.

KAS가 자체 서명 인증서 뒤에 있을 때 에이전트 사용#

KAS가 자체 서명 인증서 뒤에 있을 때는 config.kasCaCert 값을 해당 인증서로 설정할 수 있습니다. 예를 들면 다음과 같습니다:

helm upgrade --install gitlab-agent gitlab/gitlab-agent \
  --set-file config.kasCaCert=my-custom-ca.pem

이 예시에서 my-custom-ca.pem은 KAS가 사용하는 CA 인증서가 담긴 로컬 파일의 경로입니다. 인증서는 자동으로 config map에 저장되어 agentk Pod에 마운트됩니다.

KAS를 GitLab 차트로 설치했고 차트가 자동 생성된 자체 서명 와일드카드 인증서를 제공하도록 구성되어 있다면, RELEASE-wildcard-tls-ca 시크릿에서 CA 인증서를 추출할 수 있습니다.

HTTP 프록시 뒤에서 에이전트 사용#

Helm 차트를 사용할 때 HTTP 프록시를 구성하려면 환경 변수 HTTP_PROXY, HTTPS_PROXY, NO_PROXY를 사용합니다. 대문자와 소문자 모두 사용할 수 있습니다.

이 변수들은 name과 value 키를 가진 객체 목록 형태로 extraEnv 값에 설정할 수 있습니다. 예를 들어 환경 변수 HTTPS_PROXY만 https://example.com/proxy 값으로 설정하려면 다음을 실행합니다:

helm upgrade --install gitlab-agent gitlab/gitlab-agent \
  --set extraEnv[0].name=HTTPS_PROXY \
  --set extraEnv[0].value=https://example.com/proxy \
  ...

클러스터에 여러 에이전트 설치#

클러스터에 두 번째 에이전트를 설치하려면 앞의 단계를 한 번 더 수행합니다. 클러스터 안에서 리소스 이름이 충돌하지 않도록 다음 중 하나를 수행해야 합니다:

• 에이전트에 다른 릴리스 이름을 사용합니다. 예를 들면 second-gitlab-agent 입니다:

  helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ...
  

• 또는 에이전트를 다른 네임스페이스에 설치합니다. 예를 들면 different-namespace 입니다:

  helm upgrade --install gitlab-agent gitlab/gitlab-agent \
    --namespace different-namespace \
    ...
  

클러스터의 각 에이전트는 독립적으로 실행되므로, Flux 모듈이 활성화된 모든 에이전트가 재조정을 트리거합니다. 이슈 357516에서 이 동작을 변경할 것을 제안하고 있습니다.

해결 방법으로 다음을 수행할 수 있습니다:

• 에이전트가 필요한 Flux 리소스에만 접근하도록 RBAC을 구성합니다.
• Flux 모듈을 사용하지 않는 에이전트에서는 해당 모듈을 비활성화합니다.

예시 프로젝트#

다음 예시 프로젝트는 에이전트를 시작하는 데 도움이 됩니다.

• 애플리케이션과 매니페스트 리포지터리를 분리한 예시
• CI/CD 워크플로를 사용하는 Auto DevOps 설정
• CI/CD 워크플로를 사용하는 클러스터 관리 프로젝트 템플릿 예시

업데이트 및 버전 호환성#

클러스터에 설치된 에이전트 버전을 업데이트해야 하면 GitLab이 에이전트 목록 페이지에서 알려 줍니다.

가장 좋은 경험을 얻으려면 클러스터에 설치한 에이전트의 버전이 GitLab의 major 및 minor 버전과 일치해야 합니다. 이전 minor 버전과 다음 minor 버전도 지원합니다. 예를 들어 GitLab 버전이 v14.9.4(major 버전 14, minor 버전 9)이면 에이전트 v14.9.0 및 v14.9.1이 가장 적합하지만, v14.8.x 또는 v14.10.x 버전의 에이전트도 지원합니다. Kubernetes용 GitLab 에이전트의 릴리스 페이지를 참고합니다.

에이전트 버전 업데이트#

에이전트를 최신 버전으로 업데이트하려면 다음을 실행합니다:

helm repo update
helm upgrade --install gitlab-agent gitlab/gitlab-agent \
  --namespace gitlab-agent

특정 버전을 지정하려면 image.tag 값을 재정의합니다. 예를 들어 버전 v14.9.1을 설치하려면 다음을 실행합니다:

helm upgrade gitlab-agent gitlab/gitlab-agent \
  --namespace gitlab-agent \
  --set image.tag=v14.9.1

Helm 차트는 Kubernetes용 에이전트와 별도로 업데이트되므로 때때로 에이전트 최신 버전보다 뒤처질 수 있습니다. helm repo update를 실행하면서 이미지 태그를 지정하지 않으면 에이전트는 차트에 명시된 버전으로 실행됩니다.

Kubernetes용 에이전트의 최신 릴리스를 사용하려면 이미지 태그를 가장 최근 에이전트 이미지에 맞춰 설정합니다.

에이전트 제거#

Helm으로 에이전트를 설치했다면 Helm으로 제거할 수도 있습니다. 예를 들어 릴리스와 네임스페이스가 모두 gitlab-agent라면 다음 명령으로 에이전트를 제거할 수 있습니다:

helm uninstall gitlab-agent \
    --namespace gitlab-agent

문제 해결#

Kubernetes용 에이전트를 설치할 때 다음 문제가 발생할 수 있습니다.

오류: failed to reconcile the GitLab Agent#

glab cluster agent bootstrap 명령이 failed to reconcile the GitLab Agent 메시지와 함께 실패하면, glab이 Flux로 에이전트를 재조정하지 못했다는 뜻입니다.

이 오류의 원인은 다음과 같습니다:

• Flux 설정이 glab이 에이전트용 Flux 매니페스트를 둔 디렉터리를 가리키지 않습니다. --path 옵션으로 Flux를 부트스트랩했다면 glab cluster agent bootstrap 명령의 --manifest-path 옵션에 같은 값을 전달해야 합니다.
• Flux가 kustomization.yaml이 없는 프로젝트 루트 디렉터리를 가리켜, Flux가 YAML 파일을 찾아 하위 디렉터리를 탐색합니다. 에이전트를 사용하려면 .gitlab/agents/<agent-name>/config.yaml에 에이전트 구성 파일이 있어야 하는데, 이 파일은 유효한 Kubernetes 매니페스트가 아닙니다. Flux는 이 파일을 적용하지 못하고 오류를 일으킵니다. 이 문제를 해결하려면 Flux가 루트 대신 하위 디렉터리를 가리키도록 설정합니다.