Kubernetes를 위한 에이전트 설치하기

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

14.5에서 GitLab Premium에서 GitLab Free로 이전되었습니다.
14.8 버전에서 다중 아키텍처 이미지를 도입했습니다. 첫 번째 다중 아키텍처 릴리스는 v14.8.1입니다. AMD64 및 ARM64 아키텍처를 지원합니다.
GitLab 14.9에서 ARM 아키텍처 지원을 도입했습니다.

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

전제 조건

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

기존의 Kubernetes 클러스터. 클러스터가 없는 경우 다음과 같은 클라우드 공급업체에서 생성할 수 있습니다:
Self-managed GitLab 인스턴스의 경우, GitLab 관리자는 에이전트 서버를 설정해야 합니다. 그런 다음 기본적으로 wss://gitlab.example.com/-/kubernetes-agent/에서 사용할 수 있습니다. GitLab.com의 경우, 에이전트 서버는 wss://kas.gitlab.com에서 사용할 수 있습니다.

설치 단계

클러스터에 에이전트를 설치하려면 다음을 수행하십시오:

에이전트 구성 파일 생성.
GitLab에서 에이전트 등록.
클러스터에 에이전트 설치.

GitLab 14.2 버전의 이 프로세스에 대한 워크스루 보기.

에이전트 구성 파일 생성

GitLab 13.7에서 도입된 에이전트 구성 파일은 리포지토리의 여러 디렉터리(또는 하위 디렉터리)에 추가할 수 있습니다.
그룹 권한 부여가 GitLab 14.3에서 도입되었습니다.

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

GitOps 워크플로를 사용하는 경우.
GitLab CI/CD 워크플로를 사용하고 다른 프로젝트에 권한을 부여하려는 경우.
특정 프로젝트 또는 그룹 구성원이 Kubernetes에 액세스할 수 있게 허용하는 경우.

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

에이전트에 이름을 지정합니다. 에이전트 이름은 RFC 1123에서 정의한 DNS 레이블 표준을 따라야 합니다. 이름은 다음과 같아야 합니다:
- 프로젝트 내에서 고유해야 합니다.
- 최대 63자까지 포함해야 합니다.
- 소문자 알파벳 문자 또는 -만 포함해야 합니다.
- 알파벳 문자로 시작해야 합니다.
- 알파벳 문자로 끝나야 합니다.
기본 브랜치에 있는 리포지토리에서 루트에 있는 에이전트 구성 파일을 생성합니다:
```
.gitlab/agents/<에이전트-이름>/config.yaml
```

현재는 파일을 비워 둘 수 있으며, 에이전트를 구성하기 위해 나중에 설정할 수 있습니다.

GitLab에서 에이전트 등록

GitLab 14.1에서 도입된 것으로, GitLab UI에서 새로운 에이전트 레코드를 직접 생성할 수 있습니다.
GitLab 14.9에서는 에이전트 구성 파일을 생성하지 않고도 에이전트를 등록할 수 있습니다.

GitLab 14.10에서 certificate_based_clusters이라는 플래그가 변경되어 Actions 메뉴가 인증서보다 에이전트에 초점을 맞추게 되었습니다. 이 플래그는 GitLab.com, GitLab Dedicated, 그리고 self-managed에서 활성화되어 있습니다.

전제 조건:

GitLab CI/CD 워크플로를 위해 GitLab CI/CD가 비활성화되지 않도록 확인합니다.

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

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

클러스터에 에이전트 설치

GitLab 14.10에서 소개된 바에 따르면, GitLab은 에이전트를 설치하기 위해 Helm을 사용하는 것을 권장합니다.

귀하의 클러스터를 GitLab에 연결하려면 등록된 에이전트를 클러스터에 설치하세요.

다음 중 하나를 선택할 수 있습니다:

Helm을 사용하여 에이전트 설치.
또는 고급 설치 방법을 따릅니다.

무엇을 선택해야 하는지 모르겠다면 Helm부터 시작하는 것을 권장합니다.

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

Helm을 사용하여 에이전트 설치

경고: 간단히 하기 위해, 기본 Helm 차트 구성은 cluster-admin 권한을 가진 서비스 계정을 설정합니다. 제품 시스템에서는 이를 사용해서는 안 됩니다. 제품 시스템으로 배포하려면, 설치 중에 필요한 최소한의 권한을 가진 서비스 계정을 생성하고 지정하는 Helm 설치를 사용자 정의의 지침을 따르세요.

Helm을 사용하여 클러스터에 에이전트를 설치하려면 다음을 수행하세요:

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

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 설치를 사용자 정의해야 합니다. How to deploy the GitLab Agent for Kubernetes with limited permissions를 참조하세요.

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 자원을 생성합니다. 대신 토큰을 가진 자체의 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 인증서가 포함된 로컬 파일의 경로입니다. 해당 인증서는 자동으로 config map에 저장되어 agentk 포드에 마운트됩니다.

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

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

GitLab 15.0에서 소개된 바에 따르면, GitLab 에이전트 Helm 차트는 환경 변수 설정을 지원합니다.

Helm 차트를 사용할 때 HTTP 프록시를 구성하려면 HTTP_PROXY, HTTPS_PROXY, 및 NO_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 패키지를 제공합니다. 이 방법은 더 큰 유연성을 제공하지만, 고급 사용자를 대상으로 권장됩니다.

에이전트 구성

에이전트를 구성하려면 config.yaml 파일에 내용을 추가하세요.

GitOps 워크플로우의 경우, 구성 참조보기.
GitLab CI/CD 워크플로우의 경우, 에이전트에 프로젝트 액세스 권한 부여하고, 그런 다음 .gitlab-ci.yml 파일에 kubectl 명령을 추가.

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

클러스터에 두 번째 에이전트를 설치하려면 이전 단계를 다시 따라야 합니다. 클러스터 내에서 리소스 이름 충돌을 피하려면 다음 방법 중 하나를 사용해야 합니다:

에이전트에 대해 다른 릴리스 이름을 사용합니다. 예를 들어, 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 \
  ...

예제 프로젝트

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

업데이트 및 버전 호환성

GitLab 14.8에서 도입되었으며, 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에 전달할 수 있습니다: -f로 helm get values gitlab-agent > agent.yaml를 사용하여 파일에 값을 저장한 다음 파일을 Helm에 전달합니다: 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를 위한 에이전트 설치하기

전제 조건

설치 단계

에이전트 구성 파일 생성

GitLab에서 에이전트 등록

클러스터에 에이전트 설치

Helm을 사용하여 에이전트 설치

Helm 설치 사용자 정의

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

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

고급 설치 방법

에이전트 구성

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

예제 프로젝트

업데이트 및 버전 호환성

에이전트 버전 업데이트

에이전트 제거

도움말

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

도움받기