Kubernetes용 에이전트 설치

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

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

사전 요건

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

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

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

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

사전 요건:

다음 명령줄 도구가 설치되어 있어야 합니다:
- glab
- kubectl
- flux
kubectl 및 flux와 함께 작동하는 로컬 클러스터 연결이 있어야 합니다.
flux bootstrap을 사용하여 클러스터에 Flux를 부트스트랩했습니다.

에이전트를 설치하려면:

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

기본적으로, 이 명령은:

에이전트를 등록합니다.
에이전트를 구성합니다.
에이전트를 위한 대시보드 환경을 구성합니다.
에이전트 토큰을 생성합니다.
클러스터에서 에이전트 토큰으로 Kubernetes 비밀을 생성합니다.
Flux Helm 리소스를 Git 리포지토리에 커밋합니다.
Flux 조정을 트리거합니다.

사용자 정의 옵션을 보려면 glab cluster agent bootstrap --help를 실행하십시오.

에이전트를 수동으로 설치

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

선택 사항. 에이전트 구성 파일 만들기.
GitLab에 에이전트 등록하기.
클러스터에 에이전트 설치하기.

이 프로세스의 walkthrough 비디오를 시청하십시오.

에이전트 구성 파일 만들기

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

GitLab CI/CD 워크플로우를 사용하고 다른 프로젝트 또는 그룹이 에이전트에 액세스하도록 허용하고자 할 경우.
특정 프로젝트 또는 그룹 구성원이 Kubernetes에 접근할 수 있도록 허용할 경우.

에이전트 구성 파일을 만들려면:

에이전트 이름을 선택합니다. 에이전트 이름은
RFC 1123의 DNS 레이블 표준을 따릅니다. 이름은 다음과 같아야 합니다:
- 프로젝트 내에서 고유해야 합니다.
- 63자를 초과할 수 없습니다.
- 소문자 알파벳 숫자 또는 -만 포함할 수 있습니다.
- 알파벳 숫자로 시작해야 합니다.
- 알파벳 숫자로 끝나야 합니다.
리포지토리에서 기본 브랜치에 다음 경로에 에이전트 구성 파일을 생성합니다:
```
.gitlab/agents/<agent-name>/config.yaml
```

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

GitLab에 에이전트 등록

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

GitLab UI에서 직접 새로운 에이전트 레코드를 생성할 수 있습니다.

에이전트 구성 파일을 생성하지 않고도 에이전트를 등록할 수 있습니다.

클러스터에 에이전트를 설치하기 전에 에이전트를 등록해야 합니다. 에이전트를 등록하려면:

왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요.
에이전트 구성 파일이 이 프로젝트에 있어야 합니다.
클러스터 매니페스트 파일도 이 프로젝트에 있어야 합니다.
작업 > Kubernetes 클러스터를 선택합니다.
클러스터 연결(에이전트)를 선택합니다.
- CI/CD 기본값으로 구성을 생성하려면 이름을 입력하세요.
- 이미 에이전트 구성 파일이 있는 경우 목록에서 선택합니다.
에이전트 등록을 선택합니다.
GitLab이 에이전트를 위한 액세스 토큰을 생성합니다. 이 토큰은 클러스터에 에이전트를 설치하는 데 필요합니다.

경고:
에이전트 액세스 토큰을 안전하게 저장하세요. 악의적인 사용자가 이 토큰을 사용하여 에이전트의 구성 프로젝트에서 소스 코드에 접근하거나, GitLab 인스턴스의 공용 프로젝트에서 소스 코드에 접근하거나, 특정 조건 하에 Kubernetes 매니페스트를 얻을 수 있습니다.
권장 설치 방법 아래의 명령을 복사하세요. 이 명령은 클러스터에 에이전트를 설치할 때 원라인 설치 방법을 사용할 때 필요합니다.

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

세부정보:
Tier: Ultimate Offering: Self-managed

도입됨 GitLab 17.4에서.

참고:
GitLab Agent Helm Chart 릴리즈는 mTLS 인증을 완전히 지원하지 않습니다. 대신 JWT 방식으로 인증해야 합니다.
mTLS 지원은
문제 64에서 추적됩니다.

수용형 에이전트는 GitLab이 GitLab 인스턴스와 네트워크 연결을 설정할 수 없는 Kubernetes 클러스터와 통합할 수 있게 합니다. 하지만 GitLab이 이들 클러스터에 연결할 수 있습니다.

클러스터에 에이전트를 등록하기 위해 옵션 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>

GitLab이 새로운 에이전트와의 연결을 설정하기 시작하는 데 최대 10분이 소요될 수 있습니다.

클러스터에 에이전트 설치하기

GitLab에서는 에이전트를 설치하기 위해 Helm을 사용할 것을 추천합니다.

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

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

어떤 것을 선택해야 할지 모르겠다면, Helm으로 시작하는 것을 추천합니다.

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

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

Helm으로 에이전트 설치하기

경고: 단순성을 위해, 기본 Helm 차트 구성은 cluster-admin 권한을 가진 에이전트용 서비스 계정을 설정합니다. 이 설정은 운영 시스템에서 사용하지 않길 권장합니다. 운영 시스템에 배포하려면 Helm 설치 사용자 지정의 지침을 따라 배포에 필요한 최소 권한으로 서비스 계정을 생성하고 설치 중에 이를 지정해야 합니다.

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

Helm CLI 설치하기를 수행하세요.
컴퓨터에서 터미널을 열고 클러스터에 연결하기를 수행하세요.

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>

선택 사항. Helm 설치 사용자 지정하기.

운영 시스템에 에이전트를 설치하는 경우, 서비스 계정의 권한을 제한하기 위해 Helm 설치를 사용자 지정해야 합니다. 관련 사용자 지정 옵션은 아래에 설명되어 있습니다.

Helm 설치 사용자 지정하기

기본적으로 GitLab에서 생성한 Helm 설치 명령은 다음과 같습니다:

배포를 위한 namespace gitlab-agent를 생성합니다(--namespace gitlab-agent). --create-namespace 플래그를 생략하여 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 인증서가 포함된 로컬 파일의 경로입니다. 인증서는 자동으로 구성 맵에 저장되고 agentk 포드에 마운트됩니다.

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

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

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

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

이러한 변수를 설정하려면 extraEnv 값을 사용하여 name 및 value 키가 있는 객체 목록으로 설정할 수 있습니다. 예를 들어, 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 \
  ...

참고: HTTP_PROXY 또는 HTTPS_PROXY 환경 변수가 설정되면 DNS 리바인드 보호가 비활성화되며, 도메인 DNS를 확인할 수 없습니다.

고급 설치 방법

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

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

참고: 대부분의 경우, 클러스터당 하나의 에이전트를 실행하고, 에이전트 가장하기 기능(프리미엄 및 얼티밋 전용)을 사용하여 다중 테넌트를 지원해야 합니다. 여러 에이전트를 실행해야 하는 경우, 발생하는 문제에 대해 귀하의 의견을 듣고 싶습니다. 문제 454110에 피드백을 제공할 수 있습니다.

클러스터에 두 번째 에이전트를 설치하려면 이전 단계를 두 번째로 따를 수 있습니다. 클러스터 내에서 리소스 이름 충돌을 피하기 위해서는 다음 중 하나를 선택해야 합니다:

에이전트에 대해 다른 릴리스 이름을 사용합니다. 예: 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 모듈을 비활성화합니다.

예제 프로젝트

다음의 예제 프로젝트는 에이전트를 사용하여 시작하는 데 도움을 줄 수 있습니다.

업데이트 및 버전 호환성

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

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

에이전트 버전 업데이트

--reuse-values를 사용하는 대신, 필요한 모든 값을 지정해야 합니다.
--reuse-values를 사용하는 경우, 새로운 기본값을 놓치거나 사용되지 않는 값을 사용하게 될 수 있습니다.
이전의 --set 인수를 검색하려면 helm get values <release name>을 사용하세요.
값을 파일에 저장하려면 helm get values gitlab-agent > agent.yaml을 사용하고, 파일을 Helm에 -f로 전달하세요:
helm upgrade gitlab-agent gitlab/gitlab-agent -f agent.yaml. 이것은 --reuse-values의 동작을 안전하게 대체합니다.

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

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용 에이전트 설치

사전 요건

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

에이전트를 수동으로 설치

에이전트 구성 파일 만들기

GitLab에 에이전트 등록

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

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

클러스터에 에이전트 설치하기

Helm으로 에이전트 설치하기

Helm 설치 사용자 지정하기

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

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

고급 설치 방법

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

예제 프로젝트

업데이트 및 버전 호환성

에이전트 버전 업데이트

에이전트 제거

도움말

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

도움받기