Cloud Native 레퍼런스 아키텍처는 워크로드 특성에 따라 표준화된 네 가지 크기(S/M/L/XL)로 최신 클라우드 네이티브 배포 패턴에 맞춰 설계되었습니다. 이 아키텍처는 모든 GitLab 구성 요소를 Kubernetes에 배포하며, PostgreSQL, Redis, 오브젝트 스토리지는 관리형 서비스나 온프레미스 옵션을 포함한 외부 서드파티 솔루션을 사용합니다.

아키텍처 개요#

Cloud Native 아키텍처는 GitLab 구성 요소를 Kubernetes와 외부 서비스에 나눠 배포합니다.

@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

Kubernetes 구성 요소:

• Webservice - 웹 요청을 처리합니다
• Sidekiq - 백그라운드 job을 처리합니다
• Gitaly - 영구 볼륨이 연결된 StatefulSets로 Git 리포지터리를 관리합니다
• 지원 서비스 - Envoy Gateway, Toolbox, 모니터링 구성 요소입니다

외부 서비스:

• PostgreSQL - 고가용성을 위한 선택적 대기 복제본과 안정성 및 성능 향상을 위한 읽기 복제본을 함께 배포하는 관리형 데이터베이스 서비스입니다
• Redis - 캐시 인스턴스와 영구 인스턴스를 분리하며, 각각 고가용성을 위해 대기 복제본과 함께 배포할 수 있습니다
• 오브젝트 스토리지 - 아티팩트와 패키지를 저장하는 S3, Google Cloud Storage, Azure Blob Storage 같은 오브젝트 스토리지 서비스입니다

권장 관리형 서비스 공급자(GCP Cloud SQL, AWS RDS, Azure Database 등)는 인프라 및 서비스를 참고합니다.

사용 가능한 아키텍처#

이 아키텍처들은 일반적인 프로덕션 워크로드 패턴을 나타내는 타깃 RPS 범위를 기준으로 설계되었습니다. RPS 목표치는 출발점입니다. 실제로 필요한 용량은 워크로드 구성과 사용 패턴에 따라 달라집니다. RPS 구성과 조정이 필요한 시점은 RPS 구성 이해를 참고합니다.

예상 부하를 산정하고 적합한 크기를 선택하는 자세한 방법은 레퍼런스 아키텍처 사이징 가이드를 참고합니다.

주요 이점#

Cloud Native 아키텍처는 다음을 제공합니다.

• 자가 복구 인프라 - Kubernetes가 실패한 Pod를 자동으로 재시작하고 정상 노드로 워크로드를 재배치합니다
• 동적 리소스 스케일링 - Horizontal Pod Autoscaler와 Cluster Autoscaler가 실제 수요에 맞춰 용량을 조정합니다
• 배포 단순화 - GitLab 구성 요소에 기존 방식의 VM 관리가 필요 없고 모두 Kubernetes로 오케스트레이션됩니다
• 운영 부담 감소 - PostgreSQL, Redis, 오브젝트 스토리지를 외부 서비스로 쓰므로 데이터베이스와 캐시 유지 관리가 없어집니다
• 내장 고가용성 - 모든 구성 요소에 대해 자동 장애 조치를 지원하는 다중 영역 배포입니다
• 비용 효율 향상 - 피크 대응 용량은 유지하면서 수요가 낮은 시간대에는 리소스를 축소합니다

요구 사항#

Cloud Native 아키텍처를 배포하기 전에 다음을 준비합니다.

• 지원되는 Kubernetes 클러스터와 그 밖의 Charts 사전 요구 사항
• 데이터베이스, 사용자, 확장이 구성된 외부 PostgreSQL 인스턴스
• 외부 Redis 인스턴스
• 오브젝트 스토리지 서비스(S3, Google Cloud Storage, Azure Blob Storage 등)

네트워킹, 머신 유형, 클라우드 공급자 서비스를 포함한 전체 요구 사항은 레퍼런스 아키텍처 요구 사항을 참고합니다.

Kubernetes의 Gitaly 에만 해당하는 요구 사항과 제한 사항은 Kubernetes의 Gitaly 요구 사항을 참고합니다.

Small (S)#

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

워크로드 특성:

• 전체 RPS 범위: 초당 100 요청 이하
• Git 작업: 가벼운 Git push 및 pull 활동
• 리포지터리 크기: 활발히 사용되는 모노레포에는 적합하지 않습니다
• CI/CD 사용: 가벼운 동시 파이프라인 실행
• API 트래픽: 자동화 워크로드를 위한 가벼운 용량
• 사용자 패턴: 사용량 급증에 어느 정도 대응

Kubernetes 구성 요소#

Pod 스케일링 구성#

Gitaly 참고 사항: Git cgroups: 27 GB, 버퍼: 3 GB. 리포지터리 cgroups는 1로 설정됩니다. 튜닝 방법은 Gitaly cgroups 구성을 참고합니다.

외부 서비스#

Medium (M)#

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

워크로드 특성:

• 전체 RPS 범위: 초당 200 요청 이하
• Git 작업: 보통 수준의 Git push 및 pull 활동
• 리포지터리 크기: 가볍게 사용되는 모노레포를 지원합니다. 더 크거나 사용량이 많은 모노레포에는 더 큰 아키텍처 크기가 필요할 수 있습니다.
• CI/CD 사용: 보통 수준의 파이프라인 동시 실행
• API 트래픽: 표준 자동화 워크로드 지원
• 사용자 패턴: 사용량 변동에 대한 양호한 대응력

Kubernetes 구성 요소#

Pod 스케일링 구성#

Gitaly 참고 사항: Git cgroups: 56 GB, 버퍼: 6 GB. 리포지터리 cgroups는 1로 설정됩니다. 튜닝 방법은 Gitaly cgroups 구성을 참고합니다.

외부 서비스#

Large (L)#

타깃 부하: ≤500 RPS | 높은 수준의 전반적 부하

워크로드 특성:

• 전체 RPS 범위: 초당 500 요청 이하
• Git 작업: 활발한 Git push 및 pull 활동
• 리포지터리 크기: 보통 수준으로 사용되는 모노레포를 지원합니다. 더 크거나 사용량이 많은 모노레포에는 더 큰 아키텍처 크기가 필요할 수 있습니다.
• CI/CD 사용: Sidekiq 스케일링을 적절히 맞춘 높은 파이프라인 사용량
• API 트래픽: 상당한 규모의 자동화 워크로드 지원
• 사용자 패턴: 사용량 변동에 대한 강한 대응력

Kubernetes 구성 요소#

Pod 스케일링 구성#

Gitaly 참고 사항: Git cgroups: 120 GB, 버퍼: 6 GB. 리포지터리 cgroups는 1로 설정됩니다. 튜닝 방법은 Gitaly cgroups 구성을 참고합니다.

외부 서비스#

Extra Large (XL)#

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

워크로드 특성:

• 전체 RPS 범위: 초당 1000 요청 이하
• Git 작업: 집중적인 Git push 및 pull 활동
• 리포지터리 크기: 사용량이 많은 모노레포를 지원합니다. 집중적으로 사용되는 모노레포에는 더 큰 아키텍처 크기가 필요할 수 있습니다.
• CI/CD 사용: 집중적인 CI/CD 워크로드
• API 트래픽: 대량의 자동화 및 통합 트래픽
• 사용자 패턴: 다양한 접근 패턴을 고려해 설계되었습니다

Kubernetes 구성 요소#

Pod 스케일링 구성#

Gitaly 참고 사항: Git cgroups: 248 GB, 버퍼: 6 GB. 리포지터리 cgroups는 1로 설정됩니다. 튜닝 방법은 Gitaly cgroups 구성을 참고합니다.

외부 서비스#

추가 정보#

이 절에서는 머신 유형 선택, 구성 요소별 고려 사항, 스케일링 전략을 포함해 Cloud Native 아키텍처를 배포하고 운영하는 데 필요한 보충 지침을 다룹니다.

머신 유형 가이드#

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

• 최신 세대 머신 유형
• ARM 기반 인스턴스(AWS Graviton)
• 해당 사양을 충족하거나 상회하는 다른 머신 제품군
• 필요에 맞게 크기를 정한 커스텀 머신 유형

성능이 일정하지 않으므로 버스터블 인스턴스 유형은 사용하지 않습니다.

자세한 내용은 지원되는 머신 유형을 참고합니다.

Gitaly 고려 사항#

Cloud Native 아키텍처에서 Kubernetes의 Gitaly는 다음 사양의 StatefulSets를 사용합니다.

• 전용 노드 배치 - 노이지 네이버 문제를 피하기 위해 Gitaly Pod는 전용 노드에 배포됩니다.
• 리소스 할당 - Pod의 request와 limit은 노드 용량에서 오버헤드를 뺀 값으로 설정됩니다(Kubernetes 시스템 프로세스용으로 메모리 2 GB, vCPU 1 개 예약).
• Git cgroups 메모리 - 기본적으로 10% 버퍼를 두고 할당하며, 큰 Pod에서는 최대 6 GB로 제한됩니다. 예를 들어 Small은 3 GB 버퍼와 함께 27 GB를 Git cgroups에 할당하고, Medium 이상은 6 GB 상한을 사용합니다(Medium은 cgroups 56 GB, 버퍼 6 GB).

Gitaly 배포 모드:

설계상 Kubernetes의 Gitaly(비클러스터)는 각 Pod에 저장된 리포지터리에 대해 단일 장애점 서비스입니다. 데이터는 Pod 마다 단일 인스턴스에서 읽어 제공됩니다. 각 Gitaly Pod는 자체 리포지터리 집합을 관리하며, 리포지터리 분산을 통해 Git 스토리지를 수평 확장합니다.

Kubernetes의 Gitaly Cluster(Praefect)는 베타 상태이며 Cloud Native 아키텍처에는 포함되지 않습니다. 자세한 내용은 Kubernetes의 Gitaly Cluster와 Kubernetes의 Gitaly를 참고합니다.

리포지터리 분산:

Gitaly 스토리지를 여러 개 구성하면(예: default, storage1, storage2) GitLab은 기본적으로 모든 새 리포지터리를 default 스토리지에 만듭니다. 모든 Gitaly Pod에 리포지터리를 분산하려면 부하가 균형을 이루도록 스토리지 가중치를 구성합니다.

리포지터리 스토리지 가중치 구성 방법은 새 리포지터리를 저장할 위치 구성을 참고합니다.

Gitaly cgroups 구성#

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

다만 이 구성이 모든 워크로드에 최적은 아닙니다. 활성 리포지터리가 많거나 리소스 격리 요건이 뚜렷한 환경에서는 관측된 사용 패턴을 근거로 cgroups 구성을 조정해야 합니다. 여기에는 리포지터리 cgroup 수와 메모리 할당량 조정이 포함됩니다.

Gitaly cgroups를 측정하고 튜닝하고 구성하는 자세한 방법은 Gitaly cgroups를 참고합니다.

2 GB를 넘는 대형 모노레포나 집중적인 Git 워크로드에는 Gitaly를 추가로 조정해야 할 수 있습니다. 자세한 지침은 레퍼런스 아키텍처 사이징 가이드를 참고합니다.

외부 서비스 참고 사항#

• PostgreSQL은 고가용성을 위해 대기 복제본과 함께 배포할 수 있습니다. 안정성과 성능을 높이기 위해 읽기 복제본을 추가할 수도 있습니다. 규모가 큰 환경(L, XL)일수록 읽기 복제본으로 데이터베이스 부하를 분산하는 이점이 큽니다.
• Redis 인스턴스는 고가용성을 위해 대기 복제본과 함께 배포할 수 있습니다. GCP에서 Memorystore 인스턴스는 메모리 기준으로만 구성됩니다. 표시된 머신 사양은 참고용입니다.
• 인스턴스 구성이 필요한 모든 클라우드 공급자 서비스는 복원력 있는 클라우드 아키텍처 관행에 맞춰 서로 다른 가용 영역 세 곳에 노드를 최소 세 개 두는 것을 권장합니다.

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

모든 아키텍처는 Kubernetes Horizontal Pod Autoscaler(HPA)와 Cluster Autoscaler로 용량을 관리합니다.

• Webservice - 보수적인 최소 Pod 수를 두고 CPU 사용률에 따라 확장합니다
• Sidekiq - CPU 사용률에 따라 확장합니다
• Cluster Autoscaler - Pod 리소스 요청에 따라 노드를 자동으로 프로비저닝하고 제거합니다

최소 Pod 수는 비용 효율과 성능 신뢰성의 균형을 맞추기 위해 최대치의 약 3 분의 2로 설정되며, 이는 다음 목표를 달성하기 위한 내부 테스트 결과입니다.

• 수요 증가 시의 신속한 확장
• 노드 장애나 업그레이드 중의 충분한 용량
• 수요가 적은 기간의 비용 최적화

부하 패턴을 충분히 파악하고 있다면 필요에 맞게 최소치를 조정할 수 있습니다.

• 트래픽이 급격히 치솟거나 성능 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 인스턴스
• 생성된 오브젝트 스토리지 버킷
• 필요에 따라 인증용으로 생성한 Kubernetes 시크릿(PostgreSQL 비밀번호, Redis 비밀번호, 오브젝트 스토리지 자격 증명, GitLab 시크릿)

자세한 사전 요구 사항과 시크릿 구성은 GitLab chart 사전 요구 사항과 시크릿 구성을 참고합니다.

Helm charts로 배포하는 방법은 다음과 같습니다.

1. 사전 요구 사항에 설명된 대로 필요한 외부 서비스와 시크릿을 설정합니다
2. 적절한 노드 풀과 오토스케일러를 갖춘 Kubernetes 클러스터를 구성합니다
3. Helm Chart 구성 절에 제시된 Helm 값 구성을 적용합니다
4. helm install로 GitLab을 배포합니다

자세한 배포 단계는 Kubernetes에 GitLab 설치를 참고합니다.

Helm Chart 구성#

전체 Helm Chart 구성 예시와 자세한 배포 지침은 GitLab Charts 리포지터리를 참고합니다.

Cloud Native 아키텍처의 핵심 구성 영역은 다음과 같습니다.

• 리소스 사양 - Pod의 CPU와 메모리 limit은 위 각 아키텍처 크기의 사양과 일치합니다
• 오토스케일링 - HPA 구성은 최소 Pod 수를 최대치의 3 분의 2로 두고 CPU 기반 확장 목표를 설정합니다
• 노드 배치 - 노드 선택기로 워크로드가 적절한 노드 풀에 배포되도록 합니다(예: webservice, sidekiq, gitaly, support)
• 외부 서비스 - PostgreSQL, Redis, 오브젝트 스토리지 연결 정보입니다
• Gitaly - cgroups, 영속성, 스토리지 분산을 포함한 StatefulSet 구성입니다

아키텍처별 레플리카 수와 리소스 값은 위 각 크기 절의 사양을 참고합니다.

다음 단계#

배포 후에는 실제 워크로드 패턴에 맞추기 위해 모니터링과 튜닝이 필요한 경우가 일반적입니다.

모니터링 및 검증#

1. 리소스 사용률 모니터링 - Prometheus로 모든 구성 요소의 CPU, 메모리, 큐 깊이를 추적합니다
2. RPS 가정 검증 - 실제 RPS 분포를 가정한 80/10/10 구성과 비교합니다
3. 조정 대상 식별 - 사용률이 지속적으로 70% 를 넘는 구성 요소를 찾습니다
4. Gitaly cgroups 검토 - 리포지터리 접근 패턴에 맞춰 리포지터리 cgroup 수 튜닝을 검토합니다

필요에 따라 조정#

레퍼런스 아키텍처는 출발점입니다. 많은 환경이 다음을 근거로 조정할 때 이점을 얻습니다.

• 실제 워크로드 구성 - API/Web/Git 비중이 일반적인 패턴과 크게 다르면 RPS 구성 이해를 참고합니다
• 리포지터리 특성 - 모노레포 크기, 클론 빈도, 접근 패턴에 따라 구성 요소별 조정이 필요할 수 있습니다
• 성장 패턴 - 사용자 수 증가, CI/CD 확대, 자동화 확장

구성 요소별 조정 지침은 고급 스케일링을 참고합니다.

선택적 기능 구성#

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