Kubernetes 에이전트 설치

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

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

준비 사항

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

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

설치 단계

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

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

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

에이전트 구성 파일 생성

에이전트 구성 파일은 리포지터리의 여러 디렉터리(또는 하위 디렉터리)에 추가할 수 있습니다. 구성 설정에 대해, 에이전트는 GitLab 프로젝트의 YAML 파일을 사용합니다. 다음 경우에는 이 파일을 생성해야 합니다:

에이전트 구성 파일을 생성하려면 다음을 수행합니다:

  1. 에이전트의 이름을 선택합니다. 해당 이름은 RFC 1123의 DNS 레이블 표준을 따라야 합니다. 해당 이름은 다음과 같아야 합니다:

    • 프로젝트 내에서 고유해야 합니다.
    • 최대 63자까지 포함해야 합니다.
    • 소문자 알파벳 문자 또는 -만 포함해야 합니다.
    • 알파벳 문자로 시작해야 합니다.
    • 알파벳 문자로 끝나야 합니다.

  2. 리포지터리의 기본 브랜치 내에서 루트에 있는 상태에서 다음과 같이 에이전트 구성 파일을 생성합니다: 

    .gitlab/agents/<에이전트 이름>/config.yaml

일단 이 파일은 비워둘 수 있으며, 나중에 구성할 수 있습니다.

에이전트를 GitLab에 등록

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

certificate_based_clusters라는 플래그는 Actions 메뉴를 인증서가 아닌 에이전트를 중점으로 설정하도록 변경했습니다. 이 플래그는 GitLab.com, GitLab Dedicated, Self-Managed에서 활성화되었습니다.

준비 사항:

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

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

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

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

클러스터에 에이전트 설치

GitLab은 에이전트를 설치하기 위해 Helm을 사용하는 것을 권장합니다.

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

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

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

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

caution
간편함을 위해, 기본 Helm 차트 구성에서는 에이전트의 서비스 계정을 cluster-admin 권한으로 설정합니다. 실제 시스템에는 이를 사용해서는 안 됩니다. 프로덕션 시스템에 배포하려면 Helm 설치를 사용자 정의하는 방법을 따르세요.

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

  1. Helm을 설치합니다.
  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=<현재 에이전트 버전> \
    --set config.token=<당신의 토큰> \
    --set config.kasAddress=<GitLab_KAS_인스턴스_주소>
  4. 선택 사항. Helm 설치를 사용자 정의합니다. 에이전트를 프로덕션 시스템에 설치하는 경우, 서비스 계정의 권한을 제한해야 합니다. Kubernetes에 제한된 권한으로 GitLab Kubernetes 에이전트 배포하는 방법을 참조하세요.
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 <역할 이름>을 추가하여 서비스 계정에 할당된 역할을 사용자 정의할 수 있습니다. 이 경우, 서비스 계정이 사용할 제한된 권한이 있는 미리 생성된 역할이 있어야 합니다.
    • --helm install 명령에 --set rbac.create=false를 추가하여 역할 할당을 건너뛸 수 있습니다. 이 경우, ClusterRoleBinding을 매뉴얼으로 생성해야 합니다.
  • 에이전트의 액세스 토큰을 위한 Secret 리소스를 생성합니다. --set token=...을 생략하고 대신 --set config.secretName=<당신의 시크릿 이름>을 사용하여 자체 시크릿과 함께 사용할 수 있습니다.
  • 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 pod에 장착됩니다.

만약 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 \
  ...
note
HTTP_PROXY 또는 HTTPS_PROXY 환경 변수 중 하나가 설정되고 도메인 DNS가 해결되지 않으면 DNS 리바인드 보호가 비활성화됩니다.

고급 설치 방법

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

에이전트 구성하기

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

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

note
대부분의 경우 클러스터 당 하나의 에이전트를 실행하고, 멀티 테넌시를 지원하려면 에이전트 위장 기능(Premium 및 Ultimate 전용)을 사용하세요. 여러 에이전트를 실행해야 하는 경우 발생하는 문제에 대해 알려주시기 바랍니다. issue 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 모듈이 활성화된 모든 에이전트에 의해 조정이 트리거됩니다. Issue 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 에이전트의 릴리스 페이지를 참조하십시오.

에이전트 버전 업데이트

note
--reuse-values 대신 필요한 모든 값을 명시해야 합니다. --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의 동작을 안전하게 대체합니다.

최신 버전의 에이전트로 업데이트하려면 다음을 실행할 수 있습니다: 

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