GitLab 설치 요구 사항
GitLab v19.4Offering: GitLab Self-Managed
요약
GitLab Self-Managed는 배포 규모와 워크로드에 따라 달라지는 특정 하드웨어·구성 요소·인프라 요구 사항을 갖습니다. GitLab은 단일 노드에 배포하거나 여러 노드에 분산하여 배포할 수 있습니다. 단일 노드 설치의 경우 8 vCPU가 기준입니다.
GitLab Self-Managed는 배포 규모와 워크로드에 따라 달라지는 특정 하드웨어·구성 요소·인프라 요구 사항을 갖습니다. 더 크거나 분산된 배포의 경우 사이징 가이드를 사용해 환경에 맞는 사양을 결정합니다.
하드웨어#
GitLab은 단일 노드에 배포하거나 여러 노드에 분산하여 배포할 수 있습니다. 단일 노드 설치를 위한 최소 하드웨어 요구 사항은 아래에 나열되어 있습니다. 분산 배포의 경우 요구 사항은 구성 요소 유형별로 할당되며 부하에 따라 확장됩니다. 예상 부하와 워크로드 구성에 맞는 사양을 결정하려면 사이징 가이드를 사용합니다.
CPU#
단일 노드 설치의 경우 8 vCPU가 기준입니다. ARM 기반 프로세서를 지원합니다. 분산 배포의 경우 CPU는 구성 요소 유형별로 할당되며 부하에 따라 확장됩니다.
버스터블 인스턴스 유형은 성능이 일관되지 않아 권장하지 않습니다.
메모리#
단일 노드 설치의 경우 16GB가 기준입니다. 분산 배포의 경우 메모리는 구성 요소 유형별로 할당되며 부하에 따라 확장됩니다.
메모리가 제한된 환경에서 단일 노드로 설치하는 경우 GitLab은 최소 8GB의 메모리로도 실행할 수 있습니다. 자세한 내용은 메모리가 제한된 환경에서 GitLab 실행하기를 참고합니다.
가능하면 스왑을 비활성화합니다. 스왑은 부하가 걸릴 때 성능을 크게 저하시킬 수 있습니다. 스왑을 비활성화할 수 없다면 GitLab이 스왑을 전혀 사용하지 않도록 충분한 메모리를 확보합니다.
스토리지#
스토리지 요구 사항은 구성 요소별로 다릅니다. 단일 노드 설치의 경우 모든 요구 사항을 한 머신에 합산합니다. 분산 배포의 경우 각 요구 사항을 해당 노드 유형에 적용합니다.
| Component | Minimum storage | Notes |
|---|---|---|
| 애플리케이션 노드(Rails, Sidekiq, Puma) | 40GB | 패키지 설치(약 2.5GB)에 OS, 로그, 임시 파일을 더한 용량입니다. |
| 리포지터리 스토리지(Gitaly) | 모든 리포지터리를 합친 용량 이상 | Gitaly 디스크 요구 사항을 참고합니다. |
| 데이터베이스(PostgreSQL) | 5~12GB | PostgreSQL 스토리지 요구 사항을 참고합니다. |
NFS, Amazon EFS, Azure Files와 같은 네트워크 파일 시스템은 성능에 큰 영향을 줄 수 있으므로 피합니다. 자세한 내용은 클라우드 기반 파일 시스템 사용 피하기를 참고합니다.
최상의 성능을 위해 SSD 기반 스토리지를 사용합니다. I/O 사용량이 많은 Gitaly의 경우 특히 중요합니다. 버스터블 디스크 유형은 성능이 일관되지 않아 권장하지 않습니다.
인프라#
GitLab은 다양한 유형의 인프라에서 실행됩니다. 다음 섹션에서는 지원되는 플랫폼과 고가용성 요구 사항을 다룹니다.
지원되는 인프라#
GitLab은 기반 환경이 이 가이드에서 설명하는 하드웨어 및 구성 요소 요구 사항을 충족하는 한, 클라우드 제공업체와 자체 관리 인프라 모두에서 실행됩니다. 일반적으로 사용되는 클라우드 제공업체로는 AWS, GCP, Azure가 있습니다. GitLab Support는 GitLab 자체를 지원 범위로 하며, 기반 인프라나 플랫폼 관련 문제는 지원 범위 밖입니다.
Cloud Native 배포의 경우 GitLab은 GitLab Helm 차트 사전 요구 사항을 충족하는 모든 Kubernetes 배포판에서 실행됩니다. 네트워킹, 스토리지 클래스, 인증과 같은 Kubernetes 플랫폼별 동작은 GitLab Support 범위 밖입니다.
고가용성#
HA 배포에는 특정 네트워크 요구 사항이 있습니다.
- 동기 복제를 지원하려면 노드 간 지연 시간이 5ms 미만이어야 합니다.
- 복원력을 위해 가용 영역에 걸쳐 배포하는 것을 권장합니다. 쿼럼 요구 사항을 충족하려면 홀수 개의 영역을 사용합니다.
- 여러 자체 관리 데이터 센터에 걸쳐 배포하려면 동기 복제가 가능한 지연 시간, 중복 네트워크 링크, 동일한 지리적 리전 내 홀수 개의 센터가 필요합니다.
단일 GitLab 인스턴스는 여러 지리적 리전에 걸쳐 있어서는 안 됩니다. 다중 리전 배포의 경우 지리적으로 분산된 설치를 위해 설계된 GitLab Geo를 사용합니다. 다중 데이터 센터 배포에서 인프라 관련 문제는 GitLab Support 범위 밖일 수 있습니다.
구성 요소 요구 사항#
PostgreSQL#
PostgreSQL은 지원되는 유일한 데이터베이스이며 다음과 같은 방식으로 사용할 수 있습니다.
- Linux 패키지와 함께 제공되는 번들 인스턴스로 사용합니다.
- 다음과 같은 외부 서비스로 사용합니다.
외부 인스턴스에 대해서는 다음을 참고합니다.
- 외부 관리 인스턴스를 위한 필수 설정.
- 스키마 가이드를 위한 데이터베이스 스키마.
- 로케일 고려 사항을 위한 로케일 호환성을 확인해야 하는 시점.
지원되는 버전#
다음 GitLab 버전에서는 아래 PostgreSQL 버전을 사용합니다.
| GitLab version | Helm chart version | Minimum PostgreSQL version | Maximum PostgreSQL version |
|---|---|---|---|
| 19.x | 10.x | 17.x | 17.x |
| 18.x | 9.x | 16.5 | 17.x (GitLab 17.10 이상에서 테스트됨) |
| 17.x | 8.x | 14.14 | 16.x (GitLab 16.10 이상에서 테스트됨) |
| 16.x | 7.x | 13.6 | 15.x (GitLab 16.1 이상에서 테스트됨) |
PostgreSQL의 마이너 릴리스에는 버그 및 보안 수정 사항만 포함됩니다. 알려진 PostgreSQL 문제를 피하려면 항상 최신 마이너 버전을 사용합니다. 자세한 내용은 이슈 364763을 참고합니다.
명시된 버전보다 상위 메이저 버전의 PostgreSQL을 사용하려면 Linux 패키지에 상위 버전이 번들되어 있는지 확인합니다.
스토리지 요구 사항#
사용자 수에 따라 PostgreSQL 서버는 다음을 갖춰야 합니다.
- 대부분의 GitLab 인스턴스는 최소 5~10GB의 스토리지.
- GitLab Ultimate는 최소 12GB의 스토리지 (1GB의 취약점 데이터를 가져와야 함).
익스텐션#
익스텐션을 설치하려면 PostgreSQL에 슈퍼유저 권한이 필요합니다. 방법은 PostgreSQL 익스텐션 관리를 참고합니다.
| Extension | Minimum GitLab version | Type | Database |
|---|---|---|---|
amcheck |
18.4 | 필수 | Main |
btree_gist |
13.1 | 필수 | Main |
pg_trgm |
8.6 | 필수 | Main |
plpgsql |
11.7 | 필수 | Main, Geo 보조 트래킹 데이터베이스(최소 버전 9.0) |
pg_stat_statements |
- | 권장 | 전체 |
Gitaly Cluster (Praefect)#
Gitaly Cluster는 메인 GitLab 데이터베이스와
분리된 전용 PostgreSQL 인스턴스가 필요합니다. 완전한 HA를 위해서는 서드파티 PostgreSQL
솔루션을 사용합니다. Gitaly에 데이터베이스 수준의 중복성이 필요하지 않은 환경에서는 Linux
패키지를 사용하는 비 HA PostgreSQL 인스턴스로도 충분합니다. 자세한 내용은
omnibus-gitlab#7292 및
gitaly#3398을 참고합니다.
Redis 또는 Valkey#
Redis 또는 Valkey는 모든 사용자 세션과 백그라운드 작업을 저장합니다. Redis 또는 Valkey를 직접 관리하거나 관리형 클라우드 제공업체 서비스를 사용할 수 있습니다.
지원되는 Redis 또는 Valkey 버전은 다음과 같습니다.
| Datastore | Recommended version | Minimum version |
|---|---|---|
| Redis | 7.2 | 7.01 |
| Valkey | 7.2 | 7.2 |
1 Redis 7.0은 업스트림에서 EOL(End-Of-Life)에 도달했지만, 일부 경우 벤더가 계속 유지 관리하고 있습니다. 예를 들어 Amazon ElastiCache for Redis 7.1은 자체 버전 번호를 사용하지만 Redis 7.0을 기반으로 빌드되었습니다.
Redis의 EOL 날짜에 대한 자세한 내용은 Redis 문서를 참고합니다.
- 독립형 인스턴스를 사용합니다(고가용성 여부와 무관). Redis 클러스터는 지원되지 않습니다.
- 서버리스 Redis 및 Valkey는 지원되지 않습니다.
- 상황에 맞게 축출 정책을 설정합니다.
Puma#
권장 Puma 설정은 설치 방법에 따라 달라집니다. Linux 패키지는 기본적으로 권장 설정을 사용합니다.
Puma 설정을 조정하려면 다음을 참고합니다.
- Linux 패키지의 경우 Puma 설정을 참고합니다.
- GitLab Helm 차트의 경우
webservice차트를 참고합니다.
워커 및 스레드 사이징 가이드는 Puma 워커 및 스레드 사이징을 참고합니다.
Sidekiq#
Sidekiq은 여러 스레드를 사용해 백그라운드 작업을 처리합니다. 각 프로세스는 최소 200MB의 메모리가 필요하며 부하에 따라 크게 늘어날 수 있습니다. 사용자가 10,000명을 초과하는 환경에서는 Sidekiq 프로세스당 최소 1GB를 할당합니다.
오브젝트 스토리지#
오브젝트 스토리지는 분산 배포에는 필수이며 모든 설치에 권장됩니다. LFS 오브젝트, CI/CD 아티팩트, 업로드 파일, 컨테이너 레지스트리 데이터, 백업 등 바이너리 데이터를 저장합니다.
S3 호환 오브젝트 스토리지 서비스를 사용할 수 있습니다. 구성 방법과 테스트된 제공업체 목록은 오브젝트 스토리지를 참고합니다.
선택적 구성 요소#
이 구성 요소들은 GitLab 핵심 설치에 필수는 아니지만, 사용할 경우 별도의 인프라 또는 리소스 요구 사항을 갖습니다.
컨테이너 레지스트리#
GitLab Container Registry는 GitLab 프로젝트의 Docker 및 OCI 이미지를 저장하며 다음이 필요합니다.
- 도메인.
- TLS 인증서.
- 파일 시스템 또는 S3 호환 오브젝트 스토리지.
트래픽이 많은 환경에서는 레지스트리를 메인 GitLab 인스턴스와 분리된 전용 인프라에서 실행할 수 있습니다.
GitLab Pages#
GitLab Pages는 프로젝트와 그룹을 위한 정적 웹사이트를 호스팅합니다. 별도의 데몬으로 실행되며 와일드카드 DNS 레코드가 필요합니다. 커스텀 도메인을 지원하려면 보조 IP 주소와 TLS 인증서가 필요합니다.
Elasticsearch 및 OpenSearch#
고급 검색은 GitLab 콘텐츠 전반에서 더 빠르고 강력한 검색 기능을 제공합니다. 별도의 Elasticsearch 또는 OpenSearch 클러스터가 필요합니다. 클러스터 크기는 인덱싱된 데이터의 양에 따라 달라집니다.
Prometheus#
Prometheus 모니터링은 Linux 패키지에 번들되어 있으며 기본적으로 활성화되어 있습니다. 구성 또는 비활성화 방법은 Prometheus로 GitLab 모니터링하기를 참고합니다.
Zoekt#
Zoekt는 리포지터리 전반에 걸쳐 정확한 코드 검색을 제공하며 별도의 서비스로 실행됩니다. 리소스 요구 사항은 Zoekt 관리를 참고합니다.
ClickHouse#
ClickHouse는 제품 분석 기능에 사용되는 오픈소스 칼럼 지향 데이터베이스입니다. 별도의 데이터베이스 서비스로 실행됩니다. 리소스 요구 사항은 ClickHouse 구성을 참고합니다.
AI Gateway#
AI Gateway는 GitLab Duo AI 기능을 위한 백엔드 서비스를 제공합니다. Docker 또는 Kubernetes에 배포할 수 있는 독립형 서비스로 실행됩니다. 리소스 요구 사항은 설치 가이드를 참고합니다.
Secrets Manager#
GitLab Secrets Manager는 OpenBao 기반의 네이티브 시크릿 관리 기능을 제공합니다. 별도의 Kubernetes 서비스로 실행되며 전용 PostgreSQL 데이터베이스와 로드 밸런서가 필요합니다.
지원되는 웹 브라우저#
GitLab은 다음 웹 브라우저를 지원합니다.
GitLab은 Baseline의 Widely available 브라우저 세트를 목표로 합니다. 이는 모든 핵심 브라우저에서 안정적으로 지원되는 웹 플랫폼 기능을 지원하는 브라우저 버전입니다. 기능은 최소 30개월이 지나야 Widely available 상태에 도달합니다. Widely available 브라우저 세트에는 이들 브라우저의 데스크톱 버전과 모바일 버전이 모두 포함됩니다.
이들 브라우저에서 JavaScript를 비활성화한 상태로 GitLab을 실행하는 것은 지원되지 않습니다.