GitLab 아키텍처 개요

요약

GitLab에는 두 가지 소프트웨어 배포판이 있습니다: 오픈 소스 Community Edition (CE). 오픈 코어 Enterprise Edition (EE). EE 리포지터리는 보관(archived) 처리되었습니다.

소프트웨어 배포#

GitLab에는 두 가지 소프트웨어 배포판이 있습니다:

오픈 소스 Community Edition (CE).
오픈 코어 Enterprise Edition (EE).

EE 리포지터리는 보관(archived) 처리되었습니다. GitLab은 현재 단일 코드베이스로 운영됩니다.

GitLab은 다양한 구독 플랜으로 이용할 수 있습니다.

새 버전의 GitLab은 안정(stable) 브랜치에서 릴리즈되며, main 브랜치는 최신 개발 버전에 사용됩니다.

자세한 내용은 GitLab 릴리즈 프로세스를 참조하세요.

두 배포판 모두 추가 컴포넌트가 필요합니다. 이 컴포넌트들은 아래 컴포넌트 세부 정보 섹션에서 설명되며, 각각 독립적인 리포지터리를 갖습니다. 각 종속 컴포넌트의 새 버전은 보통 태그로 관리되지만, GitLab 코드베이스의 main 브랜치를 유지하면 해당 컴포넌트들의 최신 안정 버전을 사용할 수 있습니다. 새 버전은 일반적으로 GitLab 릴리즈와 거의 동시에 출시되며, 긴급 보안 업데이트는 예외일 수 있습니다.

컴포넌트#

GitLab의 일반적인 설치 환경은 GNU/Linux이지만, 쿠버네티스 플랫폼을 사용하는 배포 사례도 점점 증가하고 있습니다. 가장 큰 GitLab 인스턴스는 GitLab.com으로, 공식 GitLab Helm chart와 공식 Linux 패키지를 사용하여 배포됩니다.

일반적인 설치에서는 NGINX 또는 Apache를 웹 서버로 사용하여 GitLab Workhorse를 통해 Puma 애플리케이션 서버로 요청을 프록시합니다. GitLab은 Puma 애플리케이션 서버를 사용하여 웹 페이지와 GitLab API를 제공합니다. job 큐로는 Sidekiq을 사용하며, Sidekiq은 Redis를 job 정보, 메타데이터, 수신 job의 비영속(non-persistent) 데이터베이스 백엔드로 사용합니다.

기본적으로 Puma와 Workhorse 간의 통신은 Unix 도메인 소켓을 통해 이루어지지만, TCP를 통한 요청 전달도 지원됩니다. Workhorse는 gitlab/public 디렉터리에 접근하여 Puma 애플리케이션 서버를 거치지 않고 정적 페이지, 업로드(예: 아바타 이미지나 첨부 파일), 사전 컴파일된 에셋을 직접 제공합니다.

GitLab 애플리케이션은 영속적인 데이터베이스 정보(예: 사용자, 권한, 이슈, 기타 메타데이터)를 저장하기 위해 PostgreSQL을 사용합니다. GitLab은 베어(bare) Git 리포지터리를 설정 파일의 repositories: 섹션에 정의된 위치에 저장합니다. 또한 기본 브랜치와 훅 정보도 베어 리포지터리에 함께 보관합니다.

HTTP/HTTPS를 통해 리포지터리를 제공할 때 GitLab은 GitLab API를 사용하여 인가 및 접근을 처리하고 Git 오브젝트를 제공합니다.

애드온 컴포넌트인 GitLab Shell은 SSH를 통해 리포지터리를 제공합니다. 설정 파일의 GitLab Shell 섹션에 정의된 위치 내에서 SSH 키를 관리합니다. 해당 위치의 파일은 절대 수동으로 편집해서는 안 됩니다. GitLab Shell은 Gitaly를 통해 베어 리포지터리에 접근하여 Git 오브젝트를 제공하며, Redis와 통신하여 GitLab이 처리할 job을 Sidekiq에 제출합니다. GitLab Shell은 인가 및 접근 여부를 확인하기 위해 GitLab API를 조회합니다.

Gitaly는 GitLab Shell과 GitLab 웹 앱으로부터 Git 작업을 실행하며, GitLab 웹 앱에 Git 속성(예: 제목, 브랜치, 태그, 기타 메타데이터)을 가져오고 블롭(예: diff, 커밋, 파일)을 조회할 수 있는 API를 제공합니다.

GitLab.com의 프로덕션 아키텍처도 참고해 보세요.

기존 컴포넌트 수정 및 새 컴포넌트 도입#

애플리케이션이 전통적인 Linux 머신에 설치될 때와 쿠버네티스 같은 컨테이너화된 플랫폼에서 실행될 때는 동작 방식에 근본적인 차이가 있습니다.

공식 설치 방법과 비교하여 주요 차이점은 다음과 같습니다:

공식 Linux 패키지는 동일한 파일 시스템에서 여러 서비스가 파일에 접근할 수 있습니다. 공유 파일은 쿠버네티스 플랫폼에서 실행되는 애플리케이션에는 사용할 수 없는 옵션입니다.
공식 Linux 패키지는 기본적으로 공유 설정과 네트워크에 접근할 수 있는 서비스를 포함합니다. 쿠버네티스에서 실행되는 서비스는 완전히 격리되거나 특정 포트를 통해서만 접근 가능할 수 있으므로 이와 다를 수 있습니다.

즉, 새로운 기능을 설계하고 새 컴포넌트를 추가할 때는 서비스 간 공유 상태를 신중하게 고려해야 합니다. 동일한 파일에 접근해야 하는 서비스는 적절한 API를 통해 정보를 교환할 수 있어야 합니다. 가능하면 파일을 통한 방식은 지양해야 합니다.

API 우선 철학으로 작성된 컴포넌트는 두 가지 방법 모두와 호환되므로, 모든 새로운 기능과 서비스는 쿠버네티스 호환성을 우선으로 고려하여 작성해야 합니다.

이를 보장하는 가장 간단한 방법은 공식 GitLab Helm chart에 기능 또는 서비스 지원을 추가하거나 Distribution 팀에 문의하는 것입니다.

자세한 내용은 새 서비스 컴포넌트 추가 프로세스를 참조하세요.

간략한 컴포넌트 개요#

다음은 GitLab 아키텍처를 이해하기 위한 단순화된 아키텍처 다이어그램입니다.

전체 아키텍처 다이어그램은 아래의 컴포넌트 다이어그램에서 확인할 수 있습니다.

%%{init: {"flowchart": { "useMaxWidth": false } }}%% graph TB %% Component declarations and formatting HTTP((HTTP/HTTPS)) SSH((SSH)) GitLabPages(GitLab Pages) GitLabWorkhorse(GitLab Workhorse) GitLabShell(GitLab Shell) Gitaly(Gitaly) Puma("Puma (Gitlab Rails)") Sidekiq("Sidekiq (GitLab Rails)") PostgreSQL(PostgreSQL) Redis(Redis)

HTTP -- TCP 80,443 --> NGINX SSH -- TCP 22 --> GitLabShell

NGINX -- TCP 8090 --> GitLabPages NGINX --> GitLabWorkhorse

GitLabShell --> Gitaly GitLabShell --> GitLabWorkhorse

GitLabWorkhorse --> Gitaly GitLabWorkhorse --> Puma GitLabWorkhorse --> Redis

Sidekiq --> PostgreSQL Sidekiq --> Redis

Puma --> PostgreSQL Puma --> Redis Puma --> Gitaly

Gitaly --> GitLabWorkhorse

별도로 명시된 경우를 제외하고 모든 연결은 Unix 소켓을 사용합니다.

컴포넌트 다이어그램#

%%{init: {"flowchart": { "useMaxWidth": false } }}%% graph LR %% Anchor items in the appropriate subgraph. %% Link them where the destination* is.

subgraph Clients Browser((Browser)) Git((Git)) end

%% External Components / Applications Geo{{GitLab Geo}} -- TCP 80, 443 --> HTTP Geo -- TCP 22 --> SSH Geo -- TCP 5432 --> PostgreSQL Runner{{GitLab Runner}} -- TCP 443 --> HTTP K8sAgent{{GitLab agent}} -- TCP 443 --> HTTP

%% GitLab Application Suite subgraph GitLab subgraph Ingress HTTP[[HTTP/HTTPS]] SSH[[SSH]] NGINX[NGINX] GitLabShell[GitLab Shell]

    %% inbound/internal
    Browser -- TCP 80,443 --> HTTP
    Git -- TCP 80,443 --> HTTP
    Git -- TCP 22 --> SSH
    HTTP -- TCP 80, 443 --> NGINX
    SSH -- TCP 22 --> GitLabShell
end

subgraph GitLab Services
    %% inbound from NGINX
    NGINX --> GitLabWorkhorse
    NGINX -- TCP 8090 --> GitLabPages
    NGINX -- TCP 8150 --> GitLabKas
    NGINX --> Registry
    %% inbound from GitLabShell
    GitLabShell --> GitLabWorkhorse

    %% services
    Puma["Puma (GitLab Rails)"]
    Puma <--> Registry
    GitLabWorkhorse[GitLab Workhorse] <--> Puma
    GitLabKas[GitLab agent server] --> GitLabWorkhorse
    GitLabPages[GitLab Pages] --> GitLabWorkhorse
    Mailroom
    Sidekiq
end

subgraph Integrated Services
    %% Mattermost
    Mattermost
    Mattermost ---> GitLabWorkhorse
    NGINX --> Mattermost

    %% Grafana
    Grafana
    NGINX --> Grafana
end

subgraph Metadata
    %% PostgreSQL
    PostgreSQL
    PostgreSQL --> Consul

    %% Consul and inbound
    Consul
    Puma ---> Consul
    Sidekiq ---> Consul
    Migrations --> PostgreSQL

    %% PgBouncer and inbound
    PgBouncer
    PgBouncer --> Consul
    PgBouncer --> PostgreSQL
    Sidekiq --> PgBouncer
    Puma --> PgBouncer
end

subgraph State
    %% Redis and inbound
    Redis
    Puma --> Redis
    Sidekiq --> Redis
    GitLabWorkhorse --> Redis
    Mailroom --> Redis
    GitLabKas --> Redis

    %% Sentinel and inbound
    Sentinel <--> Redis
    Puma --> Sentinel
    Sidekiq --> Sentinel
    GitLabWorkhorse --> Sentinel
    Mailroom --> Sentinel
    GitLabKas --> Sentinel
end

subgraph Git Repositories
    %% Gitaly / Praefect
    Praefect --> Gitaly
    GitLabKas --> Praefect
    GitLabShell --> Praefect
    GitLabWorkhorse --> Praefect
    Puma --> Praefect
    Sidekiq --> Praefect
    Praefect <--> PraefectPGSQL[PostgreSQL]
    %% Gitaly makes API calls
    %% Ordered here to ensure placement.
    Gitaly --> GitLabWorkhorse
end

subgraph Storage
    %% ObjectStorage and inbound traffic
    ObjectStorage["Object storage"]
    Puma -- TCP 443 --> ObjectStorage
    Sidekiq -- TCP 443 --> ObjectStorage
    GitLabWorkhorse -- TCP 443 --> ObjectStorage
    Registry -- TCP 443 --> ObjectStorage
    GitLabPages -- TCP 443 --> ObjectStorage
    %% Gitaly can perform repository backups to object storage.
    Gitaly --> ObjectStorage
end

subgraph Monitoring
    %% Prometheus
    Grafana -- TCP 9090 --> Prometheus[Prometheus]
    Prometheus -- TCP 80, 443 --> Puma
    RedisExporter[Redis Exporter] --> Redis
    Prometheus -- TCP 9121 --> RedisExporter
    PostgreSQLExporter[PostgreSQL Exporter] --> PostgreSQL
    PgBouncerExporter[PgBouncer Exporter] --> PgBouncer
    Prometheus -- TCP 9187 --> PostgreSQLExporter
    Prometheus -- TCP 9100 --> NodeExporter[Node Exporter]
    Prometheus -- TCP 9168 --> GitLabExporter[GitLab Exporter]
    Prometheus -- TCP 9127 --> PgBouncerExporter
    Prometheus --> Alertmanager
    GitLabExporter --> PostgreSQL
    GitLabExporter --> GitLabShell
    GitLabExporter --> Sidekiq

    %% Alertmanager
    Alertmanager -- TCP 25 --> SMTP
end

%% end subgraph GitLab end

subgraph External subgraph External Services SMTP[SMTP Gateway] LDAP

    %% Outbound SMTP
    Sidekiq -- TCP 25 --> SMTP
    Puma -- TCP 25 --> SMTP
    Mailroom -- TCP 25 --> SMTP

    %% Outbound LDAP
    Puma -- TCP 369 --> LDAP
    Sidekiq -- TCP 369 --> LDAP

    %% Elasticsearch
    Elasticsearch
    Puma -- TCP 9200 --> Elasticsearch
    Sidekiq -- TCP 9200 --> Elasticsearch
    Elasticsearch --> Praefect

    %% Zoekt
    Zoekt --> Praefect
end
subgraph External Monitoring
    %% Sentry
    Sidekiq -- TCP 80, 443 --> Sentry
    Puma -- TCP 80, 443 --> Sentry

    %% Jaeger
    Jaeger
    Sidekiq -- UDP 6831 --> Jaeger
    Puma -- UDP 6831 --> Jaeger
    Gitaly -- UDP 6831 --> Jaeger
    GitLabShell -- UDP 6831 --> Jaeger
    GitLabWorkhorse -- UDP 6831 --> Jaeger
end

%% end subgraph External end

click Alertmanager "#alertmanager" click Praefect "#praefect" click Geo "#gitlab-geo" click NGINX "#nginx" click Runner "#gitlab-runner" click Registry "#registry" click ObjectStorage "#object-storage" click Mattermost "#mattermost" click Gitaly "#gitaly" click Jaeger "#jaeger" click GitLabWorkhorse "#gitlab-workhorse" click LDAP "#ldap-authentication" click Puma "#puma" click GitLabShell "#gitlab-shell" click SSH "#ssh-request-22" click Sidekiq "#sidekiq" click Sentry "#sentry" click GitLabExporter "#gitlab-exporter" click Elasticsearch "#elasticsearch" click Migrations "#database-migrations" click PostgreSQL "#postgresql" click Consul "#consul" click PgBouncer "#pgbouncer" click PgBouncerExporter "#pgbouncer-exporter" click RedisExporter "#redis-exporter" click Redis "#redis" click Prometheus "#prometheus" click Grafana "#grafana" click GitLabPages "#gitlab-pages" click PostgreSQLExporter "#postgresql-exporter" click SMTP "#outbound-email" click NodeExporter "#node-exporter"

컴포넌트 범례#

✅ - 기본 설치됨
⚙ - 추가 설정 필요
⤓ - 수동 설치 필요
❌ - 지원되지 않거나 안내 없음
N/A - 해당 없음

컴포넌트 상태는 각 컴포넌트의 설정 문서로 연결됩니다.

컴포넌트 목록#

컴포넌트	설명	Omnibus GitLab	GitLab Environment Toolkit (GET)	GitLab chart	minikube Minimal	GitLab.com	Source	GDK	CE/EE
AI Gateway	GitLab AI 네이티브 기능	⤓	❌	✅	❌	✅	⤓	✅	EE Only
GitLab Duo Workflow Service	GitLab AI 네이티브 기능	⤓	❌	✅	❌	✅	⤓	✅	EE Only
Certificate Management	TLS 설정, Let's Encrypt	✅	✅	✅	⚙	✅	⚙	⚙	CE & EE
Consul	데이터베이스 노드 검색, 장애 조치	⚙	✅	❌	❌	✅	❌	❌	EE Only
Database Migrations	데이터베이스 마이그레이션	✅	✅	✅	✅	✅	⚙	✅	CE & EE
Elasticsearch	GitLab 내 향상된 검색	⤓	⚙	⤓	⤓	✅	⤓	⚙	EE Only
Gitaly	GitLab의 모든 Git 호출을 처리하는 Git RPC 서비스	✅	✅	✅	✅	✅	⚙	✅	CE & EE
GitLab Exporter	다양한 GitLab 메트릭 생성	✅	✅	✅	✅	✅	❌	❌	CE & EE
GitLab Geo	지리적으로 분산된 GitLab 사이트	⚙	⚙	❌	❌	✅	❌	⚙	EE Only
GitLab Pages	정적 웹사이트 호스팅	⚙	⚙	⚙	❌	✅	⚙	⚙	CE & EE
GitLab agent for Kubernetes	클라우드 네이티브 방식으로 쿠버네티스 클러스터 통합	⚙	⚙	⚙	❌	❌	⤓	⚙	EE Only
GitLab self-monitoring: Alertmanager	Prometheus의 알림을 중복 제거, 그룹화 및 라우팅	⚙	⚙	✅	⚙	✅	❌	❌	CE & EE
GitLab self-monitoring: Grafana	메트릭 대시보드	✅	✅	⚙	⤓	✅	❌	⚙	CE & EE
GitLab self-monitoring: Jaeger	GitLab 인스턴스에서 생성된 트레이스 확인	❌	⚙	⚙	❌	❌	⤓	⚙	CE & EE
GitLab self-monitoring: Prometheus	시계열 데이터베이스, 메트릭 수집 및 쿼리 서비스	✅	✅	✅	⚙	✅	❌	⚙	CE & EE
GitLab self-monitoring: Sentry	GitLab 인스턴스에서 발생한 오류 추적	⤓	⤓	⤓	❌	✅	⤓	⤓	CE & EE
GitLab Shell	SSH를 통한 git 세션 처리	✅	✅	✅	✅	✅	⚙	✅	CE & EE
GitLab Workhorse	스마트 리버스 프록시, 대용량 HTTP 요청 처리	✅	✅	✅	✅	✅	⚙	✅	CE & EE
Inbound email (SMTP)	이슈 업데이트를 위한 메시지 수신	⤓	⤓	⚙	⤓	✅	⤓	⤓	CE & EE
Jaeger integration	배포된 앱의 분산 추적	⤓	⤓	⤓	⤓	⤓	⤓	⚙	EE Only
LDAP Authentication	중앙화된 LDAP 디렉터리에 대해 사용자 인증	⤓	⤓	⤓	⤓	❌	⤓	⚙	CE & EE
Mattermost	오픈 소스 Slack 대안	⚙	⚙	⤓	⤓	⤓	❌	⚙	CE & EE
Object storage	S3 호환 오브젝트 스토리지 서비스	⤓	⤓	✅	✅	✅	❌	⚙	CE & EE
NGINX	적절한 컴포넌트로 요청 라우팅, SSL 종료	✅	✅	✅	⚙	✅	⤓	⚙	CE & EE
Node Exporter	시스템 메트릭을 제공하는 Prometheus 엔드포인트	✅	✅	N/A	N/A	✅	❌	❌	CE & EE
Outbound email (SMTP)	사용자에게 이메일 메시지 전송	⤓	⤓	⚙	⤓	✅	⤓	⤓	CE & EE
Patroni	PostgreSQL HA 클러스터 리더 선출 및 복제 관리	⚙	✅	❌	❌	✅	❌	❌	EE Only
PgBouncer Exporter	PgBouncer 메트릭을 제공하는 Prometheus 엔드포인트	⚙	✅	❌	❌	✅	❌	❌	CE & EE
PgBouncer	데이터베이스 연결 풀링, 장애 조치	⚙	✅	❌	❌	✅	❌	❌	EE Only
PostgreSQL Exporter	PostgreSQL 메트릭을 제공하는 Prometheus 엔드포인트	✅	✅	✅	✅	✅	❌	❌	CE & EE
PostgreSQL	데이터베이스	✅	✅	✅	✅	✅	⤓	✅	CE & EE
Praefect	Git 클라이언트와 Gitaly 스토리지 노드 사이의 투명한 프록시	✅	✅	⚙	❌	❌	⚙	✅	CE & EE
Puma (GitLab Rails)	웹 인터페이스 및 API 요청 처리	✅	✅	✅	✅	✅	⚙	✅	CE & EE
Redis Exporter	Redis 메트릭을 제공하는 Prometheus 엔드포인트	✅	✅	✅	✅	✅	❌	❌	CE & EE
Redis	캐싱 서비스	✅	✅	✅	✅	✅	⤓	✅	CE & EE
Registry	컨테이너 레지스트리, 이미지 푸시 및 풀 허용	⚙	⚙	✅	✅	✅	⤓	⚙	CE & EE
Runner	GitLab CI/CD job 실행	⤓	⤓	✅	⚙	✅	⚙	⚙	CE & EE
Sentry integration	배포된 앱의 오류 추적	⤓	⤓	⤓	⤓	⤓	⤓	⤓	CE & EE
Sidekiq	백그라운드 job 처리기	✅	✅	✅	✅	✅	✅	✅	CE & EE
Token Revocation API	유출된 시크릿 수신 및 취소	❌	❌	❌	❌	✅	❌	❌	EE Only

컴포넌트 세부 정보#

이 문서는 GitLab 내부 구조와 컴포넌트 간 상호작용을 더 깊이 이해하고자 하는 시스템 관리자 및 GitLab 지원 엔지니어를 위해 작성되었습니다.

GitLab을 배포할 때는 아래에 설명된 프로세스들의 집합체로 이해해야 합니다. 문제를 해결하거나 디버깅할 때는 참조하는 컴포넌트를 최대한 구체적으로 명시하는 것이 좋습니다. 그렇게 하면 명확성이 높아지고 혼란을 줄일 수 있습니다.

레이어

프로세스 관점에서 GitLab은 두 가지 레이어로 구성됩니다:

모니터링(Monitoring): 이 레이어의 항목은 GitLab 애플리케이션을 제공하는 데 필수적이지는 않지만, 관리자에게 인프라와 서비스 전반의 상태에 대한 더 깊은 인사이트를 제공합니다.
코어(Core): GitLab 플랫폼 제공에 필수적인 프로세스입니다. 이 프로세스 중 하나라도 중단되면 GitLab 장애가 발생합니다. 코어 레이어는 다음과 같이 세분화할 수 있습니다:

프로세서(Processors): 실제 작업을 수행하고 서비스를 제공하는 프로세스입니다.

데이터(Data): GitLab 서비스를 위한 구조화된 데이터를 저장하거나 제공하는 서비스입니다.

GitLab 아키텍처 개요

소프트웨어 배포#

컴포넌트#

기존 컴포넌트 수정 및 새 컴포넌트 도입#

간략한 컴포넌트 개요#

컴포넌트 다이어그램#

컴포넌트 범례#

컴포넌트 목록#

컴포넌트 세부 정보#

Alertmanager#

AI Gateway#

GitLab Duo Workflow Service#

인증서 관리#

Consul#

데이터베이스 마이그레이션#

Elasticsearch#

Gitaly#

Praefect#

GitLab Geo#

GitLab Exporter#

GitLab agent for Kubernetes#

GitLab Pages#

GitLab Runner#

GitLab Shell#

GitLab Workhorse#

Grafana#

Jaeger#

Logrotate#

Mattermost#

오브젝트 스토리지#

NGINX#

Node Exporter#

Patroni#

PgBouncer#

PgBouncer Exporter#

PostgreSQL#

PostgreSQL Exporter#

Prometheus#

Redis#

Redis Exporter#

Registry#

Sentry#

Sidekiq#

Puma#

LDAP Authentication#

아웃바운드 이메일#

인바운드 이메일#

요청 유형별 GitLab#

GitLab 웹 HTTP 요청 사이클#

GitLab Git 요청 사이클#

웹 요청 (80/443)#

SSH 요청 (22)#

시스템 레이아웃#

설치 폴더 요약#

프로세스#

리포지터리 접근#

트러블슈팅#

서비스 Init 스크립트#

서비스 로그 위치#

GitLab 특정 설정 파일#

GitLab Rails에 새 설정 추가하기#

유지보수 작업#

GitLab.com#

AI 아키텍처#

GitLab 아키텍처 개요

소프트웨어 배포#

컴포넌트#

기존 컴포넌트 수정 및 새 컴포넌트 도입#

간략한 컴포넌트 개요#

컴포넌트 다이어그램#

컴포넌트 범례#

컴포넌트 목록#

컴포넌트 세부 정보#

Alertmanager#

AI Gateway#

GitLab Duo Workflow Service#

인증서 관리#

Consul#

데이터베이스 마이그레이션#

Elasticsearch#