Kubernetes에 대한 에이전트 설치

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated
  • 이전 - GitLab Premium에서 GitLab Free로 14.5에서 이동되었습니다.
  • 소개 - GitLab 14.8에서 다중 아키텍처 이미지가 도입되었습니다. 첫 번째 다중 아키텍처 릴리스는 v14.8.1입니다. AMD64 및 ARM64 아키텍처를 지원합니다.
  • 소개 - ARM 아키텍처 지원이 GitLab 14.9에서 도입되었습니다.

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

준비 사항

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

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

설치 단계

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

  1. 에이전트 구성 파일을 생성.
  2. GitLab에 에이전트 등록.
  3. 클러스터에 에이전트 설치.

GitLab 14.2의 이 과정에 대한 안내를 시청하세요.

에이전트 구성 파일 생성

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

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

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

  1. 에이전트에 이름을 지정합니다. 에이전트 이름은 RFC 1123의 DNS 라벨 표준을 따라야 합니다. 이름은:

    • 해당 프로젝트에서 고유해야 합니다.
    • 63자 이상 포함할 수 없습니다.
    • 소문자 알파벳 문자 또는 -만 포함해야 합니다.
    • 알파벳 문자로 시작해야 합니다.
    • 알파벳 문자로 끝나야 합니다.

  2. 리포지터리의 기본 브랜치에서 다음 경로에 있는 에이전트 구성 파일을 생성합니다: 

    .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에서 활성화되었습니다.

준비 사항:

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

  1. 왼쪽 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다. 에이전트 구성 파일이 있으면 이 프로젝트에 있어야 합니다. 클러스터 매니페스트 파일도 이 프로젝트에 있어야 합니다.
  2. 운영 > Kubernetes 클러스터를 선택합니다.
  3. 클러스터 연결 (에이전트)를 선택합니다.
    • CI/CD 기본값으로 구성을 생성하려면 이름을 입력합니다.
    • 에이전트 구성 파일이 이미 있는 경우 디렉터리에서 선택합니다.
  4. 에이전트 등록을 선택합니다.

  5. GitLab은 에이전트를 위한 액세스 토큰을 생성합니다. 클러스터에 에이전트를 설치할 때 이 토큰이 필요합니다.

    caution
    에이전트 액세스 토큰을 안전하게 보관합니다. 악의적인 사용자가 이 토큰을 사용하여 에이전트의 구성 프로젝트에서 소스 코드에 액세스하거나 GitLab 인스턴스의 공개 프로젝트의 소스 코드에 액세스하거나 매우 특정한 조건하에서는 Kubernetes 매니페스트를 얻을 수 있습니다.
  6. 권장 설치 방법 아래의 명령어를 복사합니다. 클러스터에 에이전트를 설치할 때 이 명령어가 필요합니다.

클러스터에 에이전트 설치

- GitLab 14.10에서 소개된 바에 따르면, GitLab은 에이전트를 설치하는 데 Hel을 사용할 것을 권장합니다.

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

어떤 것을 선택할지 모르겠다면, Hel로 시작하는 것을 권장합니다.

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

Hel로 에이전트 설치

caution
단순성을 위해, 기본 Hel 차트 구성은 에이전트에 대한 서비스 계정을 cluster-admin 권한으로 설정합니다. 프로덕션 시스템에서는 이를 사용해서는 안 됩니다. 프로덕션 시스템에 배포하려면 Hel 설치 사용자 정의 안내에 따라 배포에 필요한 최소 권한을 갖는 서비스 계정을 생성하고 설치 중에 지정해야 합니다.

Hel을 사용하여 클러스터에 에이전트를 설치하려면 다음 작업을 수행합니다:

  1. Hel 설치를 수행합니다.
  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. 선택 사항. Hel 설치 사용자 정의. 프로덕션 시스템에 에이전트를 설치하는 경우, 서비스 계정의 권한을 사용자 정의하여야 합니다. Kubernetes용 GitLab 에이전트를 권한 제한으로 배포하는 방법을 참조하십시오.
Hel 설치 사용자 정의

GitLab에 의해 생성된 Hel 설치 명령은 기본적으로 다음 작업을 수행합니다:

  • 배포를 위한 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 리소스를 생성합니다.

사용 가능한 모든 사용자 정의 디렉터리을 보려면 Hel 차트의 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 에이전트 Hel 차트는 환경 변수 설정을 지원합니다.

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 \
  ...
note
HTTP_PROXY 또는 HTTPS_PROXY 환경 변수 중 하나라도 설정되면 DNS 리바인딩 보호가 해제되며 도메인 DNS를 해석할 수 없게 됩니다.

고급 설치 방법

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

에이전트 구성

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

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

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

  • 에이전트에 대해 다른 릴리스 이름을 사용하거나, 예를 들어 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 에이전트의 릴리스 페이지를 확인하세요.

에이전트 버전 업데이트

note
--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