Kubernetes용 에이전트 설치

티어 무료, Premium, Ultimate
제공: http://GitLab.com, 자체 관리형, GitLab 전용

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

전제 조건

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

로컬 터미널에서 연결할 수 있는 기존 Kubernetes 클러스터. 클러스터가 없는 경우 다음과 같은 클라우드 제공업체에서 클러스터를 만들 수 있습니다:
- Amazon Elastic Kubernetes Service (EKS)
- Azure Kubernetes Service (AKS)
- Digital Ocean
- Google Kubernetes Engine (GKE)
- 대규모로 인프라 리소스를 관리하려면 Infrastructure as Code techniques를 사용해야 합니다.
자체 관리형 GitLab 인스턴스에서는 GitLab 관리자가 에이전트 서버를 설정해야 합니다. 그러면 기본적으로 wss://gitlab.example.com/-/kubernetes-agent/에서 사용 가능합니다. http://GitLab.com에서 에이전트 서버는 wss://kas.gitlab.com에서 사용할 수 있습니다.

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

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

전제 조건:

다음 명령줄 도구가 설치되어 있어야 합니다:
- glab
- kubectl
- flux
kubectl 및 flux와 함께 작동하는 로컬 클러스터 연결
flux bootstrap을 사용하여 클러스터에 flux를 자동 부트스트랩
- 호환되는 디렉터리에서 Flux와 에이전트를 부트스트랩해야 합니다. --path 옵션을 사용하여 Flux를 부트스트랩한 경우, glab cluster agent bootstrap명령의 --manifest-path 옵션에 동일한 값을 전달해야 합니다.

에이전트를 설치하려면:

glab cluster agent bootstrap을 실행합니다:
glab cluster agent bootstrap <agent-name>

기본적으로 이 명령은:

에이전트를 등록합니다.
에이전트를 구성합니다.
에이전트를 위한 대시보드가 있는 환경을 구성합니다.
에이전트 토큰을 생성합니다.
클러스터에서 에이전트 토큰으로 쿠버네티스 시크릿을 생성합니다.
Flux Helm 리소스를 Git 리포지토리에 커밋합니다.
Flux reconciliation을 트리거합니다.

사용자 정의 옵션의 경우, glab cluster agent bootstrap --help를 실행합니다. 최소한 --path <flux_manifests_directory> 옵션을 사용하길 권장합니다.

에이전트 수동 설치

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

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

이 프로세스에 대한 안내를 참조하세요.

에이전트 구성 파일 생성

구성 설정의 경우 에이전트는 GitLab 프로젝트의 YAML 파일을 사용합니다. 에이전트 구성 파일을 추가하는 것은 선택 사항입니다. 다음과 같은 경우에는 반드시 이 파일을 만들어야 합니다:

GitLab CI/CD 워크플로우를 사용하며 다른 프로젝트 또는 그룹이 에이전트에 액세스할 수 있도록 권한을 부여하려는 경우
특정 프로젝트 또는 그룹 멤버가 Kubernetes에 액세스할 수 있도록 허용하는 경우

에이전트 구성 파일을 생성하려면:

에이전트의 이름을 선택합니다. 에이전트 이름은 DNS label standard from RFC 1123을 따릅니다. 이름은 반드시
- 프로젝트에서 고유해야 합니다.
- 최대 63자까지 포함해야 합니다.
- 소문자 영,숫자 또는 -만 포함해야 합니다.
- 영숫자로 시작해야 합니다.
- 영숫자로 끝나야 합니다.
리포지토리의 기본 브랜치에서 에이전트 구성 파일을 만듭니다:
.gitlab/agents/<agent-name>/config.yaml

지금은 파일을 비워두고 나중에 구성할 수 있습니다.

에이전트를 GitLab에 등록

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

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

에이전트를 등록해야만 클러스터에 에이전트를 설치할 수 있습니다. 에이전트를 등록하려면:

왼쪽 사이드바에서 검색을 선택하거나 이동하여 프로젝트를 찾습니다. 에이전트 구성 파일이 있는 경우 이 프로젝트에 있어야 합니다. 클러스터 매니페스트 파일도 이 프로젝트에 있어야 합니다.
Operate > Kubernetes clusters를 선택합니다.
Connect a cluster (agent)을 선택합니다.
Name of new agent 필드에 에이전트의 고유 이름을 입력합니다.
- 이 이름의 에이전트 구성 파일이 이미 존재하면 그 파일이 사용됩니다.
- 이 이름에 대한 구성이 없으면 기본 구성으로 새 에이전트가 만들어집니다.
Create and register을 선택합니다.
GitLab에서 에이전트에 대한 액세스 토큰을 생성합니다. 클러스터에 에이전트를 설치하려면 이 토큰이 필요합니다.
권장 설치 방법 아래에 있는 명령을 복사하세요. 원-라이너 설치 방법을 사용하여 클러스터에 에이전트를 설치할 때 필요합니다.

에이전트 액세스 토큰을 안전하게 저장합니다. 악의적인 공격자는 이 토큰을 사용하여 에이전트의 구성 프로젝트의 소스 코드에 액세스하거나, GitLab 인스턴스의 모든 공개 프로젝트에 있는 소스 코드에 액세스하거나, 매우 특정한 조건에서 Kubernetes 매니페스트를 얻을 수 있습니다.

옵션 2: GitLab이 에이전트(수신 에이전트)에 연결

티어: Ultimate
제공: 자체 관리형

깃랩 에이전트 헬름 차트 릴리즈는 mTLS 인증을 완전히 지원하지 않습니다. 대신 JWT 방법으로 인증해야 합니다. mTLS에 대한 지원은 issue 64에서 확인할 수 있습니다.

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

옵션 1의 단계에 따라 클러스터에 에이전트를 등록합니다. 에이전트 토큰과 설치 명령은 나중에 사용할 수 있도록 저장하되, 아직 에이전트를 설치하지 마세요.
인증 방법을 준비합니다.
GitLab-에이전트 연결은 일반 텍스트 gRPC(grpc://) 또는 암호화된 gRPC(grpcs://, 권장)를 사용할 수 있습니다. GitLab은 JWT 토큰을 사용하여 클러스터의 에이전트를 인증할 수 있습니다. grpc:// 및 grpcs://구성 모두에서 사용할 수 있습니다. 이 방법으로 클라이언트 인증서를 생성할 필요는 없습니다.
클러스터 에이전트 API를 사용하여 에이전트에 URL 구성을 추가합니다. URL 구성을 삭제하면 수신 에이전트는 일반 에이전트가 됩니다. 수신 에이전트는 한 번에 하나의 URL 구성에만 연결할 수 있습니다.
클러스터에 에이전트를 설치합니다. 에이전트를 등록할 때 복사한 명령을 사용하되 --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분 정도 걸릴 수 있습니다.

클러스터에 에이전트 설치

Helm을 사용하여 에이전트를 설치할 것을 권장합니다.

클러스터를 GitLab에 연결하려면 등록된 에이전트를 클러스터에 설치하세요. 다음 중 하나를 선택할 수 있습니다:

Helm으로 에이전트를 설치하세요.
또는 고급 설치 방법을 따르세요.

어느 것을 선택해야 할지 모르겠다면, 헬름으로 시작하는 것이 좋습니다.

수신 에이전트를 설치하려면 GitLab이 에이전트에 연결(수신 에이전트)의 단계를 따르세요.

여러 클러스터에 연결하려면 각 클러스터에 에이전트를 구성, 등록 및 설치해야 합니다. 각 에이전트에 고유한 이름을 지정해야 합니다.

Helm으로 에이전트 설치

간단하게 하기 위해 기본 Helm 차트 구성은 cluster-admin 권한이 있는 에이전트에 대한 서비스 계정을 설정합니다. 프로덕션 시스템에서는 이 설정을 사용하지 않아야 합니다. 프로덕션 시스템에 배포하려면 Helm 설치 사용자 정의의 지침에 따라 배포에 필요한 최소 권한이 있는 서비스 계정을 만들고 설치 중에 이를 지정합니다.

Helm을 사용하여 클러스터에 에이전트를 설치하려면:

Helm CLI를 설치합니다.
사용자 컴퓨터에서 터미널을 열고 클러스터에 연결합니다.
GitLab에 에이전트를 등록할 때 복사한 명령을 실행합니다. 명령은 다음과 같아야 합니다:
선택 사항. Helm 설치를 사용자 정의합니다. 프로덕션 시스템에 에이전트를 설치하는 경우, 서비스 계정의 권한을 제한하도록 Helm 설치를 사용자 정의해야 합니다. 관련 사용자 정의 옵션은 아래에 설명되어 있습니다.

Helm 설치 사용자 정의

기본적으로 Helm 설치 명령은 GitLab에서 생성합니다:

배포를 위한 네임스페이스 gitlab-agent를 생성합니다(--namespace gitlab-agent). 네임스페이스 생성은 --create-namespace 플래그를 건너뛰면 생략할 수 있습니다.
에이전트에 대한 서비스 계정을 설정하고 cluster-admin역할을 할당합니다:
- helm install명령에 --set serviceAccount.create=false를 추가하여 서비스 계정 생성을 생략할 수 있습니다. 이 경우 서비스 계정 이름을 기존 서비스 계정으로 설정해야 합니다.
- helm install 명령에 --set rbac.useExistingRole <사용자 역할 이름>을 추가하여 서비스 계정에 할당된 역할을 사용자 지정할 수 있습니다. 이 경우 서비스 계정에서 사용할 수 있는 제한된 권한으로 미리 생성된 역할이 있어야 합니다.
- helm install 명령에 --set rbac.create=false를 추가하여 역할 할당을 완전히 생략할 수 있습니다. 이 경우 ClusterRoleBinding을 수동으로 생성해야 합니다.
에이전트의 액세스 토큰에 대한 Secret리소스를 생성합니다. 토큰에 대한 자체 시크릿을 가져오려면, 토큰을 생략하고(--set token=...) 대신 --set config.secretName=<사용자 시크릿 이름>을 사용합니다.
agentk pod에 대한 Deployment 리소스를 생성합니다.

사용 가능한 사용자 정의의 전체 목록을 보려면 Helm 차트의 README를 참조하세요.

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

KAS가 자체 서명 인증서 뒤에 있는 경우 config.kasCaCert의 값을 인증서에 설정할 수 있습니다. 예를 들어:

이 예에서 my-custom-ca.pem은 KAS에서 사용하는 CA 인증서가 포함된 로컬 파일의 경로입니다. 인증서는 자동으로 구성 맵에 저장되고 agentk pod에 마운트됩니다.

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

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

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

이러한 변수는 키 이름과 값이 있는 객체 목록인 extraEnv 값을 사용하여 설정할 수 있습니다. 예를 들어, 환경 변수 HTTPS_PROXY만 https://example.com/proxy 값으로 설정하려면 다음과 같이 실행하면 됩니다:

HTTP_PROXY 또는 HTTPS_PROXY 환경 변수가 설정되어 있고 도메인 DNS를 확인할 수 없는 경우 DNS 리바인드 보호가 비활성화됩니다.

고급 설치 방법

GitLab은 에이전트를 위한 KPT 패키지도 제공합니다. 이 방법은 더 큰 유연성을 제공하지만 고급 사용자에게만 권장됩니다.

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

대부분의 경우 클러스터당 하나의 에이전트를 실행하고 다중 테넌시를 지원하기 위해 에이전트 위장 기능(프리미엄 및 얼티밋 전용)을 사용해야 합니다. 여러 에이전트를 실행해야 하는 경우에는 발생하는 문제에 대해 의견을 보내주시기 바랍니다. issue 454110에서 피드백을 제공해 주세요.

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

에이전트에 다른 릴리스 이름(예: second-gitlab-agent)을 사용합니다:
또는 다른 네임스페이스(예: different-namespace)에 에이전트를 설치합니다:

클러스터의 각 에이전트는 독립적으로 실행되기 때문에 Flux 모듈이 활성화된 모든 에이전트에 의해 조정이 트리거됩니다. Issue 357516은 이 동작을 변경할 것을 제안합니다.

다음과 같이 해결할 수 있습니다:

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

예제 프로젝트

다음 예제 프로젝트는 에이전트를 시작하는 데 도움이 될 수 있습니다.

업데이트 및 버전 호환성

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

최상의 환경을 위해 클러스터에 설치된 에이전트 버전이 GitLab 주 버전 및 부 버전과 일치해야 합니다. 이전 및 다음 마이너 버전도 지원됩니다. 예를 들어 GitLab 버전이 v14.9.4(주 버전 14, 부 버전 9)인 경우 에이전트의 버전은 v14.9.0 및 v14.9.1이 이상적이지만 에이전트의 v14.8.x 또는 v14.10.x 버전도 모두 지원됩니다. GitLab 에이전트의 릴리스 페이지를 참조하세요.

에이전트 버전 업데이트

--reuse-values를 사용하는 대신 필요한 모든 값을 지정해야 합니다. 이전 --set 인수를 검색하려면 helm get values <릴리스 이름>을 사용하세요. 값을 파일에 저장하려면 helm get values gitlab-agent > agent.yaml을 사용하고 -f를 사용하여 파일을 Helm에 전달할 수 있습니다: helm upgrade gitlab-agent gitlab/gitlab-agent -f agent.yaml. 이렇게 하면 --reuse-values의 동작이 안전하게 대체됩니다.

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

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

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

Kubernetes용 에이전트의 최신 릴리즈를 사용하려면 가장 최신 에이전트 이미지와 일치하도록 이미지 태그를 설정하세요.

에이전트 제거

Helm으로 에이전트를 설치한 경우, Helm으로 제거할 수도 있습니다. 예를 들어 릴리스와 네임스페이스가 모두 gitlab-agent인 경우, 다음 명령을 사용하여 에이전트를 제거할 수 있습니다:

Troubleshooting

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

Error: `failed to reconcile the GitLab Agent`

glab cluster agent bootstrap명령이 실패하고 GitLab 에이전트를 조정하지 못했다는 메시지가 표시되면, 이는 glab이 에이전트를 Flux와 조정할 수 없다는 뜻입니다.

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

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