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

사전 요구 사항#

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

• 로컬 터미널에서 연결할 수 있는 기존 Kubernetes 클러스터. 클러스터가 없는 경우 다음과 같은 클라우드 공급자에서 생성할 수 있습니다:
  • Amazon Elastic Kubernetes Service (EKS)
  • Azure Kubernetes Service (AKS)
  • Digital Ocean
  • Google Kubernetes Engine (GKE)
  • 대규모 인프라 리소스 관리에는 Infrastructure as Code 기술을 사용해야 합니다.
• 에이전트 서버에 대한 접근:
  • GitLab.com에서 에이전트 서버는 wss://kas.gitlab.com에서 사용할 수 있습니다.
  • GitLab Self-Managed에서 GitLab 관리자가 에이전트 서버를 설정해야 합니다. 그런 다음 기본적으로 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. 상단 표시줄에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다. 에이전트 구성 파일이 있는 경우 이 프로젝트에 있어야 합니다. 클러스터 매니페스트 파일도 이 프로젝트에 있어야 합니다.

2. 운영 > Kubernetes 클러스터를 선택합니다.

3. **클러스터 연결 (에이전트)**을 선택합니다.

4. 새 에이전트 이름 필드에 에이전트의 고유한 이름을 입력합니다.

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

5. 생성 및 등록을 선택합니다.

6. GitLab은 에이전트에 대한 접근 토큰을 생성합니다. 클러스터에 에이전트를 설치할 때 이 토큰이 필요합니다.

   [!warning] 에이전트 접근 토큰을 안전하게 보관합니다. 악의적인 행위자는 이 토큰을 사용하여 에이전트의 구성 프로젝트의 소스 코드, GitLab 인스턴스의 공개 프로젝트 소스 코드에 접근하거나 매우 특정한 조건 하에서 Kubernetes 매니페스트를 얻을 수도 있습니다.

7. 권장 설치 방법 아래의 명령을 복사합니다. 클러스터에 에이전트를 설치할 때 단일 명령 설치 방법을 사용하는 경우 필요합니다.

옵션 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 설치를 사용자 정의해야 합니다. 관련 사용자 정의 옵션은 아래에 설명되어 있습니다.

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 파드에 대한 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 인증서가 포함된 로컬 파일의 경로입니다. 인증서는 자동으로 구성 맵에 저장되고 agentk 파드에 마운트됩니다.

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

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

히스토리

• GitLab 15.0에서 도입. GitLab 에이전트 Helm 차트는 환경 변수 설정을 지원합니다.

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은 이 동작을 변경할 것을 제안합니다.

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

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

예시 프로젝트#

다음 예시 프로젝트를 사용하여 에이전트를 시작할 수 있습니다.

• 별도의 애플리케이션 및 매니페스트 저장소 예시
• CI/CD 워크플로를 사용하는 Auto DevOps 설정
• CI/CD 워크플로를 사용하는 클러스터 관리 프로젝트 템플릿 예시

업데이트 및 버전 호환성#

GitLab은 클러스터에 설치된 에이전트 버전을 업데이트하라는 에이전트 목록 페이지의 경고를 표시합니다.

최상의 경험을 위해 클러스터에 설치된 에이전트 버전은 GitLab의 주요 및 부 버전과 일치해야 합니다. 이전 및 다음 부 버전도 지원됩니다. 예를 들어 GitLab 버전이 v14.9.4(주요 버전 14, 부 버전 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를 가리켜야 합니다.