Kubernetes에 대한 에이전트 설치

자세:

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

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

전제 조건

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

로컬 터미널에서 연결할 수 있는 기존 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에 에이전트 등록(클러스터에 등록)하기(#register-the-agent-with-gitlab).
클러스터에 에이전트 설치하기(#install-the-agent-in-the-cluster).

이 과정의 안내를 시청하세요.

에이전트 구성 파일 생성

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

GitLab CI/CD workflow를 사용하고 다른 프로젝트나 그룹에 에이전트 접근 권한을 부여하려는 경우
특정 프로젝트나 그룹 멤버가 Kubernetes에 접근하도록 허용하려는 경우

에이전트 구성 파일을 생성하려면 다음을 수행하세요.

에이전트의 이름을 선택하세요. 에이전트 이름은 RFC 1123의 DNS 라벨 표준을 따라야 합니다. 이름은:
- 프로젝트 내에서 고유해야 합니다.
- 63자를 최대 포함해야 합니다.
- 소문자 알파벳 문자 또는 - 문자만을 포함해야 합니다.
- 알파벳 문자로 시작해야 하고 숫자로 끝나야 합니다.
저장소의 기본 브랜치에서 다음 경로에 에이전트 구성 파일을 생성하세요:
```
.gitlab/agents/<agent-name>/config.yaml
```

일단 비어 둔 채로 파일을 생성하고 이후에 구성할 수 있습니다.

에이전트를 GitLab에 등록

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

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

클러스터에 에이전트를 설치하기 전에 반드시 에이전트를 등록해야 합니다.

에이전트를 등록하려면 다음을 수행하세요.

왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾으세요. 에이전트 구성 파일이 있어야 합니다. 클러스터 매니페스트 파일도 이 프로젝트에 있어야 합니다.
운영 > 쿠버네티스 클러스터를 선택하세요.
클러스터 연결(에이전트)를 선택하세요.
- CI/CD 기본값으로 구성하려면 이름을 입력하세요.
- 이미 에이전트 구성 파일이 있다면 목록에서 선택하세요.
에이전트 등록을 선택하세요.
GitLab은 에이전트를 위한 액세스 토큰을 생성합니다. 이 토큰은 클러스터에 에이전트를 설치할 때 필요합니다.
주의: 에이전트 액세스 토큰을 안전하게 보관하세요. 나쁜 사용자가 이 토큰을 사용하여 에이전트 구성 프로젝트에서 소스 코드에 액세스하거나 GitLab 인스턴스의 공개 프로젝트의 소스 코드에 액세스하거나 특정 조건 하에 Kubernetes 매니페스트를 획득할 수 있습니다.
추천 설치 방법 아래의 명령을 복사하세요. 클러스터에 에이전트를 설치할 때 이 명령이 필요합니다.

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

자세: Tier: Ultimate Offering: Self-managed

GitLab 17.4에서 소개되었습니다.

주의: GitLab 에이전트 Helm 차트 릴리스는 mTLS 인증을 완전히 지원하지 않습니다. 대신 JWT 방법으로 인증해야 합니다. mTLS 지원은 이슈 64에서 추적됩니다.

클러스터에 있는 에이전트를 등록하려면 옵션 1의 단계를 따르세요. 에이전트 토큰과 설치 명령을 나중에 사용하도록 저장하세요. 하지만 아직 에이전트를 설치하지는 마세요.
인증 방법을 준비하세요.
GitLab-to-agent 연결은 cleartext gRPC (grpc://) 또는 암호화된 gRPC (grpcs://, 권장)로 구성할 수 있습니다. GitLab은 다음 중 하나를 사용하여 클러스터의 에이전트에 인증할 수 있습니다: - JWT 토큰. cleartext gRPC(grpc://) 및 암호화된 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분이 걸릴 수 있습니다.

클러스터에 에이전트 설치

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 설치 사용자화

기본적으로, 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 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 환경 변수를 사용할 수 있습니다. 대소문자를 모두 사용할 수 있습니다.

환경 변수 HTTPS_PROXY를 값 https://example.com/proxy로 설정하려면, 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 \
  ...

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

고급 설치 방법

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

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

참고: 대부분의 경우, 클러스터 당 하나의 에이전트를 실행하고 에이전트 위장(프리미엄 및 얼티밋 전용) 기능을 사용하여 멀티텐넌시를 지원해야 합니다. 여러 에이전트를 실행해야 하는 경우, 발견한 문제에 대해 알려주세요. issue 454110에서 피드백을 제공할 수 있습니다.

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

에이전트의 다른 릴리스 이름을 사용하거나, 예를 들어, second-gitlab-agent: shell helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ...
또는, 다른 네임스페이스에 에이전트를 설치합니다, 예를 들어, different-namespace: shell helm upgrade --install gitlab-agent gitlab/gitlab-agent \ --namespace different-namespace \ ...

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

일시적인 해결책으로, 다음을 할 수 있습니다:

에이전트와 RBAC를 구성하여 필요한 Flux 리소스에만 액세스하도록합니다.
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 <릴리스 이름>을 사용합니다. 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