Kubernetes 클러스터를 GitLab에 연결하면 클라우드 네이티브 솔루션을 배포하고 관리하며 모니터링할 수 있습니다.

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

에이전트는 클러스터 안에서 실행되며, 다음 용도로 사용할 수 있습니다.

• 방화벽이나 NAT 뒤에 있는 클러스터와 통신합니다.
• 클러스터의 API 엔드포인트에 실시간으로 접근합니다.
• 클러스터에서 발생하는 이벤트 정보를 전송합니다.
• 매우 낮은 지연으로 최신 상태를 유지하는 Kubernetes 객체 캐시를 활성화합니다.

에이전트의 목적과 아키텍처에 대한 자세한 내용은 아키텍처 문서를 참고합니다.

GitLab에 연결하려는 모든 클러스터마다 별도의 에이전트를 배포해야 합니다. 에이전트는 강력한 멀티테넌시 지원을 염두에 두고 설계되었습니다. 유지 관리와 운영을 단순하게 유지하려면 클러스터당 에이전트를 하나만 실행합니다.

에이전트는 항상 GitLab 프로젝트에 등록됩니다. 에이전트를 등록하고 설치한 뒤에는 클러스터에 대한 에이전트 연결을 다른 프로젝트, 그룹, 사용자와 공유할 수 있습니다. 이 방식을 사용하면 GitLab에서 직접 에이전트 인스턴스를 관리하고 구성할 수 있으며, 하나의 설치본을 여러 테넌트로 확장할 수 있습니다.

GitLab 기능에 대한 지원 Kubernetes 버전#

GitLab은 다음 Kubernetes 버전을 지원합니다. Kubernetes 클러스터에서 GitLab을 실행하려면 다른 버전의 Kubernetes가 필요할 수 있습니다.

• Helm 차트의 경우.
• GitLab Operator의 경우.

Kubernetes 버전은 언제든지 지원되는 버전으로 업그레이드할 수 있습니다.

• 1.36(GitLab 20.2가 릴리스되거나 1.39가 지원될 때 지원 종료)
• 1.35(GitLab 19.10이 릴리스되거나 1.38이 지원될 때 지원 종료)
• 1.34(GitLab 19.7이 릴리스되거나 1.37이 지원될 때 지원 종료)

GitLab은 새 Kubernetes 마이너 버전을 최초 릴리스 후 3개월 안에 지원하는 것을 목표로 합니다. GitLab은 언제나 프로덕션에 사용할 수 있는 Kubernetes 마이너 버전을 최소 세 개 지원합니다.

새 Kubernetes 버전이 릴리스되면 다음과 같이 진행됩니다.

• 약 4주 안에 초기 스모크 테스트 결과가 이 페이지에 반영됩니다.
• 새 Kubernetes 버전 지원이 지연되면 약 8주 안에 지원 예정 GitLab 버전이 이 페이지에 반영됩니다.

에이전트를 설치할 때는 Kubernetes 버전과 호환되는 Helm 버전을 사용합니다. 다른 버전의 Helm은 동작하지 않을 수 있습니다. 호환 버전 목록은 Helm 버전 지원 정책을 참고합니다.

GitLab이 더 이상 지원하지 않는 Kubernetes 버전에서만 제공되던 API라면, 사용 중단된 API에 대한 지원이 GitLab 코드베이스에서 제거될 수 있습니다.

일부 GitLab 기능은 여기에 없는 버전에서도 동작할 수 있습니다. Kubernetes 버전 지원은 이 에픽에서 추적합니다.

Kubernetes 배포 워크플로#

두 가지 주요 워크플로 중에서 선택할 수 있습니다. GitOps 워크플로를 권장합니다.

GitOps 워크플로#

GitLab은 GitOps용 Flux 사용을 권장합니다. 시작하려면 튜토리얼: GitOps용 Flux 설정을 참고합니다.

GitLab CI/CD 워크플로#

CI/CD 워크플로에서는 GitLab CI/CD가 Kubernetes API를 사용해 클러스터를 조회하고 업데이트하도록 구성합니다.

이 워크플로는 GitLab이 GitLab CI/CD의 요청을 클러스터로 보내기 때문에 푸시 기반으로 분류됩니다.

다음과 같은 경우 이 워크플로를 사용합니다.

• 파이프라인 중심의 프로세스를 사용하는 경우.
• 에이전트로 마이그레이션해야 하지만 GitOps 워크플로가 해당 사용 사례를 지원하지 않는 경우.

이 워크플로는 보안 모델이 상대적으로 약합니다. 프로덕션 배포에는 CI/CD 워크플로를 사용하지 않습니다.

에이전트 연결 기술 세부 정보#

에이전트는 통신을 위해 KAS로 양방향 채널을 엽니다. 이 채널은 에이전트와 KAS 사이의 모든 통신에 사용됩니다.

• 각 에이전트는 활성 스트림과 유휴 스트림을 포함해 최대 500개의 논리적 gRPC 스트림을 유지할 수 있습니다.
• gRPC 스트림이 사용하는 TCP 연결 수는 gRPC가 결정합니다.
• 각 연결의 최대 수명은 2시간이며, 1시간의 유예 기간이 있습니다.
  • KAS 앞단의 프록시가 연결의 최대 수명에 영향을 줄 수 있습니다. GitLab.com에서는 2시간입니다. 유예 기간은 최대 수명의 50%입니다.

채널 라우팅에 대한 자세한 내용은 에이전트의 KAS 요청 라우팅을 참고합니다.

리셉티브 에이전트(Receptive agents)#

히스토리

• GitLab 17.4에서 도입됨.

리셉티브 에이전트를 사용하면 GitLab 인스턴스로 네트워크 연결을 시작할 수는 없지만 GitLab이 연결할 수는 있는 Kubernetes 클러스터와 GitLab을 통합할 수 있습니다. 예를 들어 다음과 같은 경우입니다.

1. GitLab이 사설 네트워크나 방화벽 뒤에서 실행되어 VPN으로만 접근할 수 있는 경우.
2. Kubernetes 클러스터가 클라우드 공급자에 호스팅되어 있지만 인터넷에 노출되어 있거나 사설 네트워크에서 접근 가능한 경우.

이 기능을 활성화하면 GitLab이 제공된 URL로 에이전트에 연결합니다. 에이전트와 리셉티브 에이전트를 동시에 사용할 수 있습니다.

Kubernetes 통합 용어집#

이 용어집은 GitLab Kubernetes 통합과 관련된 용어 정의를 제공합니다.

관련 주제#

• GitOps 워크플로
• GitOps 예시 및 학습 자료
• GitLab CI/CD 워크플로
• 에이전트 설치
• 에이전트로 작업하기
• 기존 인증서 기반 통합에서 Kubernetes용 에이전트로 마이그레이션
• 문제 해결
• 프로덕션에 적합한 GitOps 설정을 위한 가이드 탐색 자료
• Kubernetes용 CI/CD 예시 및 학습 자료
• 에이전트 개발에 기여