- 
  Tier: Free, Premium, Ultimate

- Offering: GitLab Self-Managed

Cloud Native 레퍼런스 아키텍처는 워크로드 특성에 따라 표준화된 4가지 크기(S/M/L/XL)를 갖춘 현대적인 클라우드 네이티브 배포 패턴을 위해 설계되었습니다. 이 아키텍처는 모든 GitLab 구성 요소를 쿠버네티스에 배포하며, PostgreSQL, Redis, Object Storage는 관리형 서비스 또는 온프레미스 옵션을 포함한 외부 서드파티 솔루션을 사용합니다.

아키텍처 개요#

Cloud Native 아키텍처는 쿠버네티스와 외부 서비스에 GitLab 구성 요소를 배포합니다:

@startuml kubernetes skinparam linetype ortho

card "Kubernetes via Helm Charts" as kubernetes { collections "Webservice Pods\n//Auto-scaling//" as web #32CD32

collections "Sidekiq Pods\n//Auto-scaling//" as sidekiq #ff8dd1

collections "Gitaly Pods\n//StatefulSets//" as gitaly #FF8C00

collections "Supporting Pods\n//NGINX, Toolbox//" as support #e76a9b }

card "External Services" as external { collections "PostgreSQL" as database #4EA7FF

collections "Redis Cache" as redis_cache #FF6347

collections "Redis Persistent" as redis_persistent #FF6347

cloud "Object Storage" as object_storage #white }

kubernetes -[hidden]---> external

web -[#32CD32,norank]--> gitaly web -[#32CD32,norank]--> object_storage web -[#32CD32,norank]--> redis_cache web -[#32CD32,norank]--> redis_persistent web -[#32CD32,norank]--> database

sidekiq -[#ff8dd1,norank]--> gitaly sidekiq -[#ff8dd1,norank]--> object_storage sidekiq -[#ff8dd1,norank]--> redis_cache sidekiq -[#ff8dd1,norank]--> redis_persistent sidekiq -[#ff8dd1,norank]--> database

@enduml

쿠버네티스 구성 요소:

• Webservice - 웹 요청 처리

• Sidekiq - 백그라운드 job 처리

• Gitaly - 영구 볼륨이 있는 StatefulSets를 사용하여 Git 리포지터리 관리

• 지원 서비스 - Envoy Gateway, Toolbox, 모니터링 구성 요소

  쿠버네티스에 Gitaly를 배포할 때, Gitaly는 샤딩(non-cluster) 구성만 지원합니다. 클라이언트 재시도를 통해 다운타임 없이 Gitaly를 업그레이드할 수 있습니다. 각 Gitaly pod는 해당 pod가 서비스하는 리포지터리에 대한 단일 장애 지점입니다. Gitaly Cluster(Praefect)는 쿠버네티스에서 지원되지 않습니다.

자동 페일오버를 통한 Gitaly 고가용성이 필요한 경우, 상태 비저장 구성 요소는 쿠버네티스에서 실행하면서 Gitaly Cluster를 가상 머신에 배포하는 Cloud Native Hybrid 아키텍처를 고려하세요. 쿠버네티스에서의 Gitaly 요구 사항 및 제한 사항은 쿠버네티스의 Gitaly를 참조하세요.

외부 서비스:

• PostgreSQL - 고가용성을 위한 선택적 스탠바이 레플리카와 추가적인 안정성 및 성능을 위한 읽기 레플리카를 갖춘 관리형 데이터베이스 서비스

• Redis - 별도의 캐시 및 영구 인스턴스로, 각각 고가용성을 위한 선택적 스탠바이 레플리카와 함께 배포 가능

• Object Storage - 아티팩트 및 패키지를 위한 S3, Google Cloud Storage, Azure Blob Storage 등의 Object Storage 서비스

권장 관리형 서비스 제공업체(GCP Cloud SQL, AWS RDS, Azure Database 등)에 대한 정보는 권장 클라우드 제공업체 및 서비스를 참조하세요.

사용 가능한 아키텍처#

이 아키텍처는 일반적인 프로덕션 워크로드 패턴을 나타내는 타깃 RPS 범위를 기준으로 설계되었습니다. RPS 타깃은 시작점으로 사용되며, 실제 용량 요구 사항은 워크로드 구성 및 사용 패턴에 따라 달라집니다. RPS 구성 및 조정이 필요한 경우에 대한 가이드는 RPS 구성 이해를 참조하세요.

예상 부하 파악 및 적절한 크기 선택에 대한 자세한 가이드는 레퍼런스 아키텍처 사이징 가이드를 참조하세요.

주요 이점#

Cloud Native 아키텍처가 제공하는 이점:

• 자가 치유 인프라 - 쿠버네티스가 실패한 pod를 자동으로 재시작하고 정상 노드에 워크로드를 재스케줄링

• 동적 리소스 스케일링 - Horizontal Pod Autoscaler 및 Cluster Autoscaler가 실제 수요에 따라 용량 조정

• 간편한 배포 - GitLab 구성 요소에 대한 전통적인 VM 관리 불필요, 모두 쿠버네티스로 오케스트레이션

• 운영 오버헤드 감소 - PostgreSQL, Redis, Object Storage에 외부 서비스를 사용하여 데이터베이스 및 캐시 유지 관리 불필요

• 내장 고가용성 - 모든 구성 요소에 대한 자동 페일오버를 갖춘 멀티존 배포

• 향상된 비용 효율성 - 피크 시간대 용량을 유지하면서 수요가 낮은 기간에는 리소스 축소

요구 사항#

Cloud Native 아키텍처를 배포하기 전에 다음 사항을 확인하세요:

• 지원되는 쿠버네티스 클러스터 및 기타 Charts 전제 조건 준비

• 데이터베이스, 사용자 및 확장 기능이 구성된 외부 PostgreSQL 인스턴스

• 외부 Redis 인스턴스

• Object Storage 서비스(S3, Google Cloud Storage, Azure Blob Storage 또는 기타)

네트워킹, 머신 유형, 클라우드 제공업체 서비스를 포함한 전체 요구 사항은 레퍼런스 아키텍처 요구 사항을 참조하세요.

쿠버네티스의 Gitaly 관련 특정 요구 사항 및 제한 사항은 쿠버네티스 Gitaly 요구 사항을 참조하세요.

Small (S)#

타깃 부하: ≤100 RPS | 전반적으로 가벼운 부하

워크로드 특성:

• 총 RPS 범위: 초당 ≤100 요청

• Git 작업: 가벼운 Git 푸시 및 풀 활동

• 리포지터리 크기: 활발하게 사용되는 모노레포에는 적합하지 않음

• CI/CD 사용: 가벼운 동시 파이프라인 실행

• API 트래픽: 자동화 워크로드에 대한 가벼운 용량

• 사용자 패턴: 사용량 급증에 대한 일부 복원력

쿠버네티스 구성 요소#

Pod 스케일링 구성#

Gitaly 참고 사항: Git cgroups: 27 GB, 버퍼: 3 GB. 리포지터리 cgroup은 1로 설정. 튜닝 가이드는 Gitaly cgroups 구성을 참조하세요.

외부 서비스#

Medium (M)#

타깃 부하: ≤200 RPS | 보통 수준의 전반적인 부하

워크로드 특성:

• 총 RPS 범위: 초당 ≤200 요청

• Git 작업: 보통 수준의 Git 푸시 및 풀 활동

• 리포지터리 크기: 가볍게 사용되는 모노레포 지원. 더 크거나 많이 사용되는 모노레포는 더 큰 아키텍처 크기가 필요할 수 있음

• CI/CD 사용: 보통 수준의 파이프라인 동시성

• API 트래픽: 표준 자동화 워크로드 지원

• 사용자 패턴: 사용량 변동에 대한 양호한 복원력

쿠버네티스 구성 요소#

Pod 스케일링 구성#

Gitaly 참고 사항: Git cgroups: 56 GB, 버퍼: 6 GB. 리포지터리 cgroup은 1로 설정. 튜닝 가이드는 Gitaly cgroups 구성을 참조하세요.

외부 서비스#

Large (L)#

타깃 부하: ≤500 RPS | 전반적으로 무거운 부하

워크로드 특성:

• 총 RPS 범위: 초당 ≤500 요청

• Git 작업: 활발한 Git 푸시 및 풀 활동

• 리포지터리 크기: 보통 수준으로 사용되는 모노레포 지원. 더 크거나 많이 사용되는 모노레포는 더 큰 아키텍처 크기가 필요할 수 있음

• CI/CD 사용: Sidekiq 적절한 스케일링을 통한 무거운 파이프라인 사용

• API 트래픽: 상당한 자동화 워크로드 지원

• 사용자 패턴: 사용량 변동에 대한 강력한 복원력

쿠버네티스 구성 요소#

Pod 스케일링 구성#

Gitaly 참고 사항: Git cgroups: 120 GB, 버퍼: 6 GB. 리포지터리 cgroup은 1로 설정. 튜닝 가이드는 Gitaly cgroups 구성을 참조하세요.

외부 서비스#

Extra Large (XL)#

타깃 부하: ≤1000 RPS | 전반적으로 집중적인 부하

워크로드 특성:

• 총 RPS 범위: 초당 ≤1000 요청

• Git 작업: 집중적인 Git 푸시 및 풀 활동

• 리포지터리 크기: 많이 사용되는 모노레포 지원. 매우 집중적으로 사용되는 모노레포는 더 큰 아키텍처 크기가 필요할 수 있음

• CI/CD 사용: 집중적인 CI/CD 워크로드

• API 트래픽: 대규모 자동화 및 통합 트래픽

• 사용자 패턴: 다양한 접근 패턴에 맞게 설계

쿠버네티스 구성 요소#

Pod 스케일링 구성#

Gitaly 참고 사항: Git cgroups: 248 GB, 버퍼: 6 GB. 리포지터리 cgroup은 1로 설정. 튜닝 가이드는 Gitaly cgroups 구성을 참조하세요.

외부 서비스#

추가 정보#

이 섹션은 머신 유형 선택, 구성 요소별 고려 사항, 스케일링 전략을 포함하여 Cloud Native 아키텍처 배포 및 운영에 대한 보충 가이드를 제공합니다.

머신 유형 가이드#

표시된 머신 유형은 검증 및 테스트에 사용된 예시입니다. 다음을 사용할 수 있습니다:

• 최신 세대 머신 유형

• ARM 기반 인스턴스(AWS Graviton)

• 사양을 충족하거나 초과하는 다른 머신 패밀리

• 특정 요구에 맞게 크기를 조정한 커스텀 머신 유형

일관성 없는 성능으로 인해 버스터블 인스턴스 유형은 사용하지 마세요.

자세한 내용은 지원되는 머신 유형을 참조하세요.

Gitaly 고려 사항#

Cloud Native 아키텍처에서 쿠버네티스의 Gitaly는 다음 사양으로 StatefulSets를 사용합니다:

• 전용 노드 배치 - Gitaly pod는 노이지 네이버 문제를 방지하기 위해 전용 노드에 배포됨

• 리소스 할당 - Pod request 및 limit은 오버헤드(쿠버네티스 시스템 프로세스를 위해 2 GB 메모리, 1 vCPU 예약)를 뺀 노드 용량으로 설정됨

• Git cgroups 메모리 - 기본적으로 10% 버퍼로 할당되며, 대형 pod의 경우 최대 6 GB로 제한됨. 예를 들어, Small은 3 GB 버퍼와 함께 Git cgroups에 27 GB를 할당하고, Medium 이상의 크기는 6 GB 상한을 사용함(Medium의 경우 6 GB 버퍼와 함께 56 GB cgroups)

Gitaly 배포 모드:

설계상, 쿠버네티스의 Gitaly(non-Cluster)는 각 pod에 저장된 리포지터리에 대한 단일 장애 지점 서비스입니다. 데이터는 pod당 단일 인스턴스에서 소싱되고 서비스됩니다. 각 Gitaly pod는 자체 리포지터리 세트를 관리하며, 리포지터리 배포를 통해 Git 스토리지의 수평 스케일링을 제공합니다.

Gitaly Cluster(Praefect)는 Cloud Native 아키텍처에서 지원되지 않습니다. 쿠버네티스에서의 Gitaly 배포 제한 사항에 대한 맥락은 쿠버네티스의 Gitaly를 참조하세요.

리포지터리 배포:

여러 Gitaly 스토리지가 구성된 경우(예: default, storage1, storage2), GitLab은 기본적으로 모든 새 리포지터리를 default 스토리지에 생성합니다. 모든 Gitaly pod에 리포지터리를 배포하려면 스토리지 가중치를 구성하여 부하를 분산하세요.

리포지터리 스토리지 가중치 구성에 대한 가이드는 새 리포지터리가 저장되는 위치 구성을 참조하세요.

Gitaly cgroups 구성#

Gitaly는 개별 Git 작업으로 인한 리소스 고갈을 방지하기 위해 cgroups를 사용합니다. 기본 구성은 리포지터리 cgroup 수를 1로 설정하며, 이는 오버서브스크립션을 통해 단일 리포지터리가 전체 pod 리소스를 사용할 수 있는 시작점을 제공합니다.

그러나 이 구성은 모든 워크로드에 최적이 아닐 수 있습니다. 활성 리포지터리가 많거나 특정 리소스 격리 요구 사항이 있는 환경에서는 관찰된 사용 패턴을 기반으로 cgroups 구성을 조정해야 합니다. 여기에는 리포지터리 cgroup 수 및 메모리 할당 조정이 포함됩니다.

Gitaly cgroups 측정, 튜닝 및 구성에 대한 자세한 가이드는 Gitaly cgroups를 참조하세요.

대형 모노레포(2 GB 초과) 또는 집중적인 Git 워크로드의 경우 추가적인 Gitaly 조정이 필요할 수 있습니다. 자세한 가이드는 레퍼런스 아키텍처 사이징 가이드를 참조하세요.

외부 서비스 참고 사항#

• PostgreSQL은 고가용성을 위해 스탠바이 레플리카와 함께 배포할 수 있습니다. 추가 안정성 및 성능을 위해 읽기 레플리카를 추가할 수 있습니다. 더 큰 환경(L, XL)은 데이터베이스 부하를 분산하기 위해 읽기 레플리카의 이점을 더 많이 누릴 수 있습니다.

• Redis 인스턴스는 고가용성을 위해 스탠바이 레플리카와 함께 배포할 수 있습니다. GCP에서 Memorystore 인스턴스는 메모리만으로 구성됩니다. 머신 사양은 참고용으로 표시됩니다.

• 인스턴스 구성을 포함하는 모든 클라우드 제공업체 서비스에 대해 복원력 있는 클라우드 아키텍처 관행에 맞게 세 개의 서로 다른 가용성 영역에 최소 세 개의 노드를 구현하는 것이 권장됩니다.

오토스케일링 및 최소 Pod 수#

모든 아키텍처는 쿠버네티스 Horizontal Pod Autoscaler(HPA)와 Cluster Autoscaler를 사용하여 용량을 관리합니다:

• Webservice - 보수적인 최소 Pod 수로 CPU 사용률에 따라 스케일링

• Sidekiq - CPU 사용률에 따라 스케일링

• Cluster Autoscaler - Pod 리소스 요청에 따라 노드를 자동으로 프로비저닝 및 제거

최소 Pod 수는 다음 목표를 달성하기 위한 내부 테스트를 기반으로 비용 효율성과 성능 안정성 균형을 맞추기 위해 최대값의 약 2/3로 설정됩니다:

• 수요 증가 시 반응적인 스케일링

• 노드 장애 또는 업그레이드 중 충분한 용량

• 수요가 낮은 기간의 비용 최적화

워크로드 패턴을 잘 이해하고 있다면 필요에 따라 최소값을 조정할 수 있습니다:

• 급격한 트래픽 급증 또는 엄격한 성능 SLA가 있는 환경의 경우 최소값 증가

• 모니터링을 통해 지속적인 부하가 기본값보다 일관되게 낮음을 확인한 후 최소값 감소

고급 스케일링#

Cloud Native 아키텍처는 기본 사양을 초과하여 스케일링할 수 있도록 설계되었습니다. 다음과 같은 경우 용량을 조정해야 할 수 있습니다:

• 나열된 RPS 타깃보다 지속적으로 높은 처리량

• 비전형적인 워크로드 구성(RPS 구성 이해 참조)

• 대형 모노레포(2 GB 초과)

• 상당한 추가 워크로드

• 광범위한 GitLab Duo Agent Platform 사용

스케일링 전략은 구성 요소 유형에 따라 다릅니다.

수평 스케일링(Webservice 및 Sidekiq)#

용량 증가를 위해 최대 레플리카 수와 노드 풀 용량을 조정하여 수평으로 스케일링하세요:

• Webservice - Helm 값에서 maxReplicas를 늘리고 Webservice 노드 풀에 해당 노드 추가

• Sidekiq - maxReplicas를 늘려 더 높은 job 처리량을 처리하고 Sidekiq 노드 풀에 노드 추가

수평 스케일링은 이러한 상태 비저장 구성 요소에 권장되는 접근 방식입니다.

수직 스케일링(PostgreSQL, Redis, Gitaly)#

상태 저장 구성 요소의 경우 인스턴스 또는 pod 사양을 늘리세요:

• PostgreSQL 및 Redis - 서비스 제공업체를 통해 더 큰 인스턴스 유형으로 업그레이드

• Gitaly - Pod당 CPU 및 메모리 사양 증가. 이를 위해 Gitaly 노드 풀에서 더 큰 노드 유형과 Git cgroups 메모리 할당에 대한 해당 조정이 필요함

Sidekiq 큐 최적화#

기본적으로 Sidekiq은 단일 큐에서 모든 job 유형을 처리합니다. 다양한 워크로드 패턴이 있는 환경에서는 job 특성에 따라 별도의 큐를 구성할 수 있습니다:

• 높은 긴급도 큐 - CI 파이프라인 처리 및 웹훅 전달과 같은 시간에 민감한 job용

• CPU 집약적 큐 - 조정된 동시성 설정을 가진 계산 집약적 job용

• 기본 큐 - 표준 백그라운드 처리용

큐 분리는 job 처리 안정성을 개선하고 우선순위가 낮은 job이 시간에 민감한 작업을 차단하는 것을 방지할 수 있으며, 특히 대규모 자동화 워크로드가 있는 더 큰 환경(L, XL)에서 효과적입니다.

Sidekiq 큐 구성에 대한 자세한 내용은 특정 job 클래스 처리를 참조하세요.

GitLab Duo Agent Platform을 위한 스케일링#

GitLab Duo Agent Platform은 표준 GitLab 워크로드를 넘어 추가적인 인프라 요구 사항을 도입합니다. Agent Platform 채택을 위한 모니터링 및 스케일링에 대한 자세한 가이드는 GitLab Duo Agent Platform을 위한 스케일링을 참조하세요.

스케일링 고려 사항#

구성 요소를 크게 스케일링할 때:

• 의존하는 구성 요소의 리소스 포화도를 모니터링하세요. Webservice 또는 Sidekiq의 부하 증가는 PostgreSQL과 Gitaly에 영향을 줄 수 있습니다.

• 먼저 프로덕션 이외의 환경에서 스케일링 변경 사항을 테스트하세요.

• 서비스 간 병목 현상이 이동하는 것을 피하기 위해 상호 의존하는 구성 요소를 함께 스케일링하세요.

포괄적인 스케일링 가이드는 환경 스케일링을 참조하세요.

배포#

전제 조건:

• 필요한 데이터베이스, 사용자 및 권한이 설정된 외부 PostgreSQL

• 구성되고 접근 가능한 외부 Redis 인스턴스

• 생성된 Object Storage 버킷

• 필요에 따라 인증을 위한 쿠버네티스 시크릿 생성(PostgreSQL 비밀번호, Redis 비밀번호, Object Storage 자격 증명, GitLab 시크릿)

자세한 전제 조건 및 시크릿 구성은 GitLab 차트 전제 조건 및 시크릿 구성을 참조하세요.

Helm 차트를 사용하여 배포하는 방법:

• 전제 조건에 설명된 대로 필요한 외부 서비스 및 시크릿 설정

• 적절한 노드 풀 및 오토스케일러가 있는 쿠버네티스 클러스터 구성

• Helm Chart 구성 섹션에 표시된 Helm 값 구성 적용

• helm install을 사용하여 GitLab 배포

자세한 배포 단계는 쿠버네티스에 GitLab 설치를 참조하세요.

Helm Chart 구성#

완전한 Helm Chart 구성 예시 및 자세한 배포 가이드는 GitLab Charts 리포지터리를 참조하세요.

Cloud Native 아키텍처의 주요 구성 영역:

• 리소스 사양 - Pod CPU 및 메모리 제한은 위의 각 아키텍처 크기 사양과 일치

• 오토스케일링 - HPA 구성은 최소 Pod 수를 최대값의 2/3로 설정하고 CPU 기반 스케일링 타깃 사용

• 노드 배치 - 노드 셀렉터를 통해 워크로드가 적절한 노드 풀에 배포(예: webservice, sidekiq, gitaly, support)

• 외부 서비스 - PostgreSQL, Redis, Object Storage 연결 정보

• Gitaly - cgroups, 영구성, 스토리지 배포를 갖춘 StatefulSet 구성

아키텍처별 레플리카 수 및 리소스 값은 위의 각 크기 섹션 사양을 참조하세요.

다음 단계#

배포 후 환경은 일반적으로 실제 워크로드 패턴에 맞게 모니터링 및 튜닝이 필요합니다.

모니터링 및 검증#

• 리소스 사용률 모니터링 - Prometheus를 사용하여 모든 구성 요소의 CPU, 메모리, 큐 깊이 추적

• RPS 가정 검증 - 실제 RPS 분석을 80/10/10 구성 가정과 비교

• 잠재적 조정 사항 식별 - 지속적으로 70% 이상의 사용률을 보이는 구성 요소 파악

• Gitaly cgroups 검토 - 리포지터리 접근 패턴에 따라 리포지터리 cgroup 수 튜닝 고려

필요에 따라 조정#

레퍼런스 아키텍처는 시작점입니다. 많은 환경에서 다음 사항을 기반으로 조정의 이점을 누릴 수 있습니다:

• 실제 워크로드 구성 - API/Web/Git 분할이 일반적인 패턴과 크게 다른 경우 RPS 구성 이해 참조

• 리포지터리 특성 - 모노레포 크기, 클론 빈도, 접근 패턴에 따라 구성 요소별 조정이 필요할 수 있음

• 성장 패턴 - 사용자 수 증가, CI/CD 확장, 자동화 스케일링

구성 요소별 조정 가이드는 고급 스케일링을 참조하세요.

선택적 기능 구성#

요구 사항에 따라 GitLab의 추가 선택적 기능을 구성할 수 있습니다. 자세한 내용은 GitLab 설치 후 단계를 참조하세요.

선택적 기능에는 추가 용량이 필요할 수 있습니다. 요구 사항은 기능별 문서를 참조하세요.