リファレンスアーキテクチャ

プラン: Free、Premium、Ultimate
提供形態: GitLab Self-Managed

GitLabリファレンスアーキテクチャは、GitLabを大規模にデプロイするために検証済みの本番環境に対応した設計になっています。各アーキテクチャは、要件に応じて使用または調整できる詳細な仕様を提供します。

利用可能なリファレンスアーキテクチャ

次のリファレンスアーキテクチャは、推奨される環境の開始地点として利用できます。

これらのアーキテクチャは、ユーザー数または1秒あたりのリクエスト数（RPS）に基づいた、ピーク負荷に合わせて名前が付けられています。RPSは、平均的な実際のデータに基づいて計算されます。

各アーキテクチャは、スケーラブルかつ柔軟性を持ったデザインになっています。ワークロードに応じて、上方または下方に適宜調整できます。たとえば、既知の負荷が高いシナリオには、大規模なモノレポの使用や、かなりの量の追加のワークロードなどがあります。

各リファレンスアーキテクチャのテスト対象の詳細については、各ページのテスト手法セクションを参照してください。

GitLabパッケージ（Omnibus）

Linuxパッケージベースのリファレンスアーキテクチャのリストを次に示します:

最大20 RPSまたは1,000ユーザーAPI: 20 RPS、Web: 2 RPS、Git（プル）: 2 RPS、Git（プッシュ）: 1 RPS
最大40 RPSまたは2,000ユーザーAPI: 40 RPS、Web: 4 RPS、Git（プル）: 4 RPS、Git（プッシュ）: 1 RPS
最大60 RPSまたは3,000ユーザーAPI: 60 RPS、Web: 6 RPS、Git（プル）: 6 RPS、Git（プッシュ）: 1 RPS
最大100 RPSまたは5,000ユーザーAPI: 100 RPS、Web: 10 RPS、Git（プル）: 10 RPS、Git（プッシュ）: 2 RPS
最大200 RPSまたは10,000ユーザーAPI: 200 RPS、Web: 20 RPS、Git（プル）: 20 RPS、Git（プッシュ）: 4 RPS
最大500 RPSまたは25,000ユーザーAPI: 500 RPS、Web: 50 RPS、Git（プル）: 50 RPS、Git（プッシュ）: 10 RPS
最大1000 RPSまたは50,000ユーザーAPI: 1000 RPS、Web: 100 RPS、Git（プル）: 100 RPS、Git（プッシュ）: 20 RPS

クラウドネイティブハイブリッド

次は、選択された推奨コンポーネントをKubernetesで実行できる、クラウドネイティブハイブリッドリファレンスアーキテクチャのリストです:

最大40 RPSまたは2,000ユーザーAPI: 40 RPS、Web: 4 RPS、Git（プル）: 4 RPS、Git（プッシュ）: 1 RPS
最大60 RPSまたは3,000ユーザーAPI: 60 RPS、Web: 6 RPS、Git（プル）: 6 RPS、Git（プッシュ）: 1 RPS
最大100 RPSまたは5,000ユーザーAPI: 100 RPS、Web: 10 RPS、Git（プル）: 10 RPS、Git（プッシュ）: 2 RPS
最大200 RPSまたは10,000ユーザーAPI: 200 RPS、Web: 20 RPS、Git（プル）: 20 RPS、Git（プッシュ）: 4 RPS
最大500 RPSまたは25,000ユーザーAPI: 500 RPS、Web: 50 RPS、Git（プル）: 50 RPS、Git（プッシュ）: 10 RPS
最大1000 RPSまたは50,000ユーザーAPI: 1000 RPS、Web: 100 RPS、Git（プル）: 100 RPS、Git（プッシュ）: 20 RPS

はじめに

まず、Self-Managedアプローチがご自身とその要件に適した選択肢であるかどうかを検討してください。

本番環境ではどんなアプリケーションでも実行は複雑であり、それはGitLabにおいても同様です。できる限りスムーズに実行できることを目指していますが、設計に基づく一般的な複雑さは依然として存在します。通常、ハードウェア、オペレーティングシステム、ネットワーク構築、ストレージ、セキュリティ、GitLab自体など、すべての側面を管理する必要があります。これには、環境の初期設定だけでなく長期的なメンテナンスも含まれます。

このアプローチを採用することを決定した場合、本番環境でのアプリケーションの実行と保守に関する実務知識が必要です。実務知識がない場合、プロフェッショナルサービスチームが導入サービスを提供します。より長期的なマネージドソリューションを希望する方は、GitLab SaaSやGitLab Dedicatedなどの他のプランをご検討ください。

GitLab Self-Managedアプローチの使用を検討している場合は、このページ全体、特に次のセクションをよくお読みになることをおすすめします:

どのアーキテクチャで始めるかを決定する

リファレンスアーキテクチャは、パフォーマンス、復元性、コストという3つの重要な要素のバランスを取るように設計されています。これらは、GitLabを大規模にセットアップするのを容易にする目的があります。ただし、どれが要件を満たし、どこから開始すればよいかを知ることは依然として難しい場合があります。

一般的なガイドとして、環境のパフォーマンスや復元性を高めたいほど、複雑になります。

このセクションでは、リファレンスアーキテクチャを選択する際に考慮すべき事項について説明します。

予想される負荷（RPSまたはユーザー数）

適切なアーキテクチャのサイズは、主に環境で予想されるピーク負荷によって決まります。この負荷のもっとも客観的な尺度は、ピーク時に環境へ送られる1秒あたりのリクエスト数（RPS）です。

各アーキテクチャは、さまざまなタイプのリクエスト（API、Web、Git）に対して特定のRPSターゲットを処理するように設計されています。これらの詳細については、各ページのテスト手法セクションで説明されています。

包括的なRPS分析とデータに基づいたサイジングの決定については、リファレンスアーキテクチャのサイジングを参照してください。このセクションでは、次の情報を提供します:

ピーク時および持続的なRPSメトリクスを抽出するための詳細なPromQLクエリ。
コンポーネント固有の調整を特定するためのワークロードパターン分析。
モノレポ、ネットワーキングの使用状況、および成長計画の評価開発手法。

迅速なRPSの推定のために、いくつかの潜在的なオプションがあります:

次のようなPrometheusのクエリ:

sum(irate(gitlab_transaction_duration_seconds_count{controller!~'HealthController|MetricsController'}[1m])) by (controller, action)

GitLabサポートからのget-rpsスクリプト
その他のモニタリングソリューション。
ロードバランサーの統計。

RPSを特定できない場合は、負荷カテゴリごとの同等のユーザー数に基づく代替サイズ設定方法を提供しています。この数は、手動および自動での使用状況の両方を考慮して、一般的なRPS値にマッピングされます。

初期サイズ設定ガイド

予想される負荷に対してどのアーキテクチャを選択するかを判断するには、次の初期サイズ設定ガイドの表を参照してください:

負荷カテゴリ	1秒あたりのリクエスト数（RPS）				一般的なユーザー数	リファレンスアーキテクチャ
負荷カテゴリ	API	Web	Gitプル	Gitプッシュ	一般的なユーザー数	リファレンスアーキテクチャ
XS	20	2	2	1	1,000	最大20 RPSまたは1,000ユーザー
S	40	4	4	1	2,000	最大40 RPSまたは2,000ユーザー
M	60	6	6	1	3,000	最大60 RPSまたは3,000ユーザー
L	100	10	10	2	5,000	最大100 RPSまたは5,000ユーザー
XL	200	20	20	4	10,000	最大200 RPSまたは10,000ユーザー
2XL	500	50	50	10	25,000	最大500 RPSまたは25,000ユーザー
3XL	1,000	100	100	20	50,000	最大1000 RPSまたは50,000ユーザー

初期アーキテクチャを選択する前に、このセクションをよく確認してください。高可用性（HA）や大規模なモノレポの使用などの他の要因も考慮してください。これらはRPSまたはユーザー数以上に選択に影響を与える可能性があります。

迷った場合は、大きめの設定で開始し、モニタリングしてからスケールダウンする

必要な環境サイズが不明な場合は、大きめの設定で開始し、モニタリングしてから、メトリクスが運用状況をサポートする場合は、それに応じてスケールダウンすることを検討してください。

大きめの設定で開始してからスケールダウンするのが賢明なアプローチであるのは、次のような場合です:

RPSを特定できない
環境負荷が予想よりも異常に高い可能性がある
大規模なモノレポまたはかなりの量の追加のワークロードがある

たとえば、3,000のユーザーがいて、同時負荷を大幅に増加させる自動化が実行されていることもわかっている場合は、100 RPS / 5,000ユーザーのクラス環境で開始してモニタリングし、メトリクスがそれをサポートする場合は、すべてのコンポーネントを一度に、または1つずつスケールダウンします。

スタンドアロン（非HA）

2,000以下のユーザーにサービスを提供する環境では、通常、非HA、単一またはマルチノード環境をデプロイする、スタンドアロンアプローチに従うことをおすすめします。このアプローチでは、リカバリーのための自動バックアップなどの戦略を採用できます。これらの戦略は、HAに伴う複雑さを回避する一方、適切なレベルの目標リカバリー時間（RTO）または目標リカバリー時点（RPO）を提供します。

スタンドアロンセットアップ、特に単一ノード環境では、インストールと管理にさまざまなオプションを利用できます。オプションには、複雑さをさらに軽減する特定のクラウドプロバイダーマーケットプレースを使用して直接デプロイする機能が含まれます。

高可用性（HA）

高可用性により、GitLabセットアップのすべてのコンポーネントが、さまざまなメカニズムを通じて障害を処理できるようになります。ただし、これを実現するのは複雑であり、必要な環境は相当な規模になる可能性があります。

3,000以上のユーザーにサービスを提供する環境では、通常、HA戦略を使用することをおすすめします。このレベルでは、環境が停止するとより多くのユーザーに大きな影響を与えます。この範囲のすべてのアーキテクチャには、この理由から、設計上HAが組み込まれています。

高可用性（HA）の必要性

前述のように、HAの実現にはコストがかかります。各コンポーネントを増やす必要があるため、環境要件は相当な規模になり、実際のコストとメンテナンスコストが追加されます。

ユーザー数が3,000未満のお客様の多くにとっては、バックアップ戦略で十分であり、その方が好ましいことがわかっています。リカバリー時間が長くなりますが、アーキテクチャがはるかに小さくなり、結果としてメンテナンスコストも削減されます。

一般的なガイドラインとして、HAは次のシナリオでのみ採用してください:

ユーザーが3,000以上の場合。
GitLabがダウンすると、ワークフローに重大な影響を与える場合。

スケールダウンした高可用性（HA）アプローチ

ユーザー数が少なくてもHAが必要な場合は、3Kアーキテクチャを調整した形で実現できます。

ゼロダウンタイムアップグレード

ゼロダウンタイムアップグレードは、HAを備えた標準環境で使用できます（クラウドネイティブハイブリッドはサポートされていません）。これにより、アップグレード中も環境を維持できます。ただし、このプロセスは結果としてより複雑になり、ドキュメントで詳しく説明されているように、いくつかの制限があります。

このプロセスを実行する場合、HAメカニズムが有効になるときに、ごく短時間ダウンタイムが発生する可能性があることに注意してください。

ほとんどの場合、アップグレードに必要なダウンタイムはそれほど長くはありません。これが重要な要件である場合にのみ、このアプローチを採用してください。

クラウドネイティブハイブリッド（Kubernetes HA）

HAと復元性をさらに高めるために、クラウドネイティブハイブリッドリファレンスアーキテクチャとして知られるKubernetesにあるいくつかのコンポーネントをデプロイできます。安定性の理由から、GitalyなどのステートフルコンポーネントはKubernetesにデプロイできません。

代わりにクラウドネイティブハイブリッドを使うことができますが、標準のリファレンスアーキテクチャと比較して高度なセットアップです。Kubernetesでのサービスの実行は複雑です。Kubernetesに関する十分な実務知識と経験がある場合にのみ、このセットアップを使用してください。

GitLab Geo（地域間分散/ディザスターリカバリー）

GitLab Geoを使用すると、完全なディザスターリカバリー（DR）セットアップを使って、さまざまな地域で分散環境を実現できます。GitLab Geoでは、少なくとも2つの個別の環境が必要です:

1つのプライマリサイト。
レプリカとして機能する1つ以上のセカンダリサイト。

プライマリサイトが利用できなくなった場合は、いずれかのセカンダリサイトにフェイルオーバーできます。

DRがご自身の環境にとって重要な要件である場合にのみ、この高度で複雑なセットアップを使用してください。また、各サイトの設定方法について、追加の決定を行う必要もあります。たとえば、各セカンダリサイトをプライマリサイトと同じアーキテクチャにするか、各サイトをHA用に設定するかなどです。

大規模なモノレポ/追加ワークロード

大規模なモノレポまたは大量の追加ワークロードは、環境のパフォーマンスに著しい影響を与える可能性があります。状況に応じて、何らかの調整が必要になる場合があります。

これらの要因の包括的な分析については、リファレンスアーキテクチャのサイジングを参照してください。このセクションでは、次の情報を提供します:

インフラストラクチャに対するモノレポの影響に関する詳細な評価開発手法。
さまざまなワークロードパターンに対するコンポーネント固有のスケールに関する推奨事項。
大量のデータ転送シナリオにおけるネットワーク帯域幅分析。

この状況に該当する場合は、GitLabの担当者またはサポートにご連絡いただき、詳細なガイダンスをお求めください。

クラウドプロバイダーサービス

前述のすべての戦略において、PostgreSQLデータベースやRedisなどの同等のクラウドプロバイダーサービスで、いくつかのGitLabコンポーネントを実行できます。

詳細については、推奨されるクラウドプロバイダーとサービスを参照してください。

意思決定ツリー

次の意思決定ツリーを参照する前に、前述のガイダンスをすべてお読みください。

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TD
    accTitle: Decision tree for reference architecture selection
    accDescr: Key considerations for selecting architecture including expected load, HA requirements, and additional workload factors.

   L0A(<b>What Reference Architecture should I use?</b>)
   L1A(<b>What is your <a href=#expected-load-rps--user-count>expected load</a>?</b>)

   L2A("60 RPS / 3,000 users or more?")
   L2B("40 RPS / 2,000 users or less?")

   L3A("<a href=#do-you-need-high-availability-ha>Do you need HA?</a><br>(or zero-downtime upgrades)")
   L3B[Do you have experience with<br/>and want additional resilience<br/>with select components in Kubernetes?]

   L4A><b>Recommendation</b><br><br>60 RPS / 3,000 user architecture with HA<br>and supported reductions]
   L4B><b>Recommendation</b><br><br>Architecture closest to <a href=#expected-load-rps--user-count>expected load</a> with HA]
   L4C><b>Recommendation</b><br><br>Cloud Native Hybrid architecture<br>closest to <a href=#expected-load-rps--user-count>expected load</a>]
   L4D>"<b>Recommendation</b><br><br>Standalone 20 RPS / 1,000 user or 40 RPS / 2,000 user<br/>architecture with Backups"]

   L0A --> L1A
   L1A --> L2A
   L1A --> L2B
   L2A -->|Yes| L3B
   L3B -->|Yes| L4C
   L3B -->|No| L4B

   L2B --> L3A
   L3A -->|Yes| L4A
   L3A -->|No| L4D
   L5A("<a href=#gitlab-geo-cross-regional-distribution--disaster-recovery>Do you need cross regional distribution</br> or disaster recovery?"</a>) --> |Yes| L6A><b>Additional Recommendation</b><br><br> GitLab Geo]
   L4A ~~~ L5A
   L4B ~~~ L5A
   L4C ~~~ L5A
   L4D ~~~ L5A

   L5B("Do you have <a href=#large-monorepos>Large Monorepos</a> or expect</br> to have substantial <a href=#additional-workloads>additional workloads</a>?") --> |Yes| L6B><b>Additional Recommendations</b><br><br><a href=#if-in-doubt---start-large-monitor-and-scale-down>Start large, monitor and scale down</a><br><br> Contact GitLab representative or Support]
   L4A ~~~ L5B
   L4B ~~~ L5B
   L4C ~~~ L5B
   L4D ~~~ L5B

classDef default fill:#FCA326
linkStyle default fill:none,stroke:#7759C2

要件

リファレンスアーキテクチャを実装する前に、次の要件とガイダンスを参照してください。

サポートされているマシンタイプ

これらのアーキテクチャは、一貫したパフォーマンスを確保しながら、柔軟にマシンタイプを選択できるように設計されています。各リファレンスアーキテクチャで特定のマシンタイプの例を示していますが、これらは推奨されるデフォルトを意図したものではありません。

次の例のように、各コンポーネントに指定された要件を満たすか、それ以上の任意のマシンタイプを使用できます:

新世代のマシンタイプ（GCP n2シリーズやAWS m6シリーズなど）
ARMベースのインスタンス（AWS Gravitonなど）のような別のアーキテクチャ
特定のワークロード特性（より高いネットワーク帯域幅など）により適した代替マシンタイプファミリー

このガイダンスは、AWS RDSなどのクラウドプロバイダーサービスにも適用できます。

パフォーマンスが一貫しないため、「バースト可能」なインスタンスタイプは推奨されません。

テストを実施したマシンタイプやその方法の詳細については、検証およびテスト結果を参照してください。

サポートされているディスクタイプ

ほとんどの標準ディスクタイプは、GitLabで動作することが期待されています。ただし、次の点に注意してください:

Gitalyには、Gitalyストレージに関する特定のディスク要件があります。
パフォーマンスが一貫しないため、「バースト可能」なディスクタイプの使用は推奨しません。

その他のディスクタイプは、GitLabで動作することが期待されています。耐久性やコストなどの要件に基づいて選択してください。

サポートされているインフラストラクチャ

GitLabは、信頼できるクラウドプロバイダー（AWS、GCP、Azure）やそれらのサービス、または次の両方を満たすSelf-Managed（ESXi）などのほとんどのインフラストラクチャで実行できます:

各アーキテクチャで詳述されている仕様。
このセクションのすべての要件。

ただし、これにより、考えられるすべての組み合わせとの互換性が保証されるわけではありません。

詳細については、推奨されるクラウドプロバイダーとサービスを参照してください。

ネットワーキング（HA）

以下は、高可用性構成でGitLabを実行するためのネットワーク要件です。

ネットワークレイテンシー

データベースレプリケーションなど、GitLabアプリケーション全体で同期レプリケーションを可能にするには、ネットワークレイテンシーを可能な限り低くする必要があります。一般に、これは5ミリ秒未満である必要があります。

可用性ゾーン（クラウドプロバイダー）

可用性ゾーン全体へのデプロイはサポートされており、復元性を高めるために推奨されています。一部のコンポーネントはクォーラム投票に奇数のノードを使用するため、GitLabアプリケーションの要件に合わせて奇数のゾーンを使用する必要があります。

データセンター（セルフホスト）

複数のセルフホストデータセンターへのデプロイは可能ですが、慎重な検討が必要です。これには、センター間の同期対応レイテンシー、スプリットブレインシナリオを防ぐための堅牢な冗長ネットワークリンク、地理的に同一リージョンにあるすべてのセンター、および適切なクォーラム投票のための奇数のセンター全体へのデプロイ（可用性ゾーンなど）が必要です。

マルチデータセンターのデプロイに起因するインフラストラクチャ関連の問題について、GitLabサポートを利用できない場合があります。センター全体へのデプロイを選択する場合、一般に自己責任となります。

単一のGitLab環境を異なるリージョンにデプロイすることはサポートされていません。データセンターは、同じリージョンにある必要があります。

大規模なモノレポ

アーキテクチャは、ベストプラクティスに従うさまざまなサイズのリポジトリでテストされました。

ただし、大規模なモノレポ（数ギガバイト以上）は、Gitのパフォーマンス、ひいては環境そのものに大きな影響を与える可能性があります。大規模モノレポとその使用方法は、Gitalyから基盤となるインフラストラクチャまで、システム全体に大きな負担をかける可能性があります。

パフォーマンスへの影響は、主にソフトウェアの性質に起因します。ハードウェアリソースを追加しても、あまり効果はありません。

この状況に該当する場合は、リンク先のドキュメントに従い、GitLabの担当者またはサポートチームにご連絡いただき、詳細なガイダンスをお求めになることを強くおすすめします。

大規模なモノレポには、相応のコストがかかります。そのようなリポジトリがある場合は、パフォーマンスを良好に保ち、コストを抑制するために、次のガイダンスに従ってください:

大規模なモノレポを最適化します。バイナリを保存しないようにLFSなどの機能を使用したり、リポジトリのサイズを縮小する別のアプローチを使用したりすると、パフォーマンスが大幅に向上し、コストを削減できる可能性があります。
モノレポによっては、それを補うために環境仕様を引き上げることが必要になる場合があります。Gitalyでは、Praefect、GitLab Rails、およびロードバランサーとともに、追加のリソースが必要になる場合があります。これは、モノレポ自体とその使用状況によって異なります。
モノレポが非常に大きい場合（20ギガバイト以上）、さらに仕様を強化したり、場合によってはモノレポ専用のGitalyバックエンドを別途用意するなど、さらなる対策が必要になることがあります。
ネットワークとディスクの帯域幅は、大規模なモノレポで考慮すべきもう1つの潜在的な要素です。負荷が非常に高い状況では、（CIなどの）同時クローンが多数存在する場合、帯域幅が飽和状態になる可能性があります。このシナリオでは、可能な限りフルクローンを削減してください。それ以外の場合は、帯域幅を増やすために、環境仕様を追加する必要になることがあります。これは、クラウドプロバイダーによって異なります。

追加のワークロード

これらのアーキテクチャは、実際のデータに基づいた標準的なGitLabのセットアップ用に設計およびテストされています。

ただし、追加のワークロードは、フォローアップアクションをトリガーすることにより、操作の影響を増幅させる可能性があります。以下を使用する場合は、処理能力を補うため、推奨される仕様を調整することが必要かもしれません:

ノード上のセキュリティソフトウェア。
大規模リポジトリに対する数百もの同時CIジョブ。
高頻度で実行されるカスタムスクリプト。
多くの大規模プロジェクトにおけるインテグレーション。
サーバーフック。
システムフック。

通常、変更が必要な場合に通知するために、追加のワークロードの影響を測定するための堅牢なモニタリングを導入する必要があります。GitLabの担当者またはサポートチームにご連絡いただき、詳細なガイダンスをお求めください。

ロードバランサー

アーキテクチャでは、クラスに応じて最大2つのロードバランサーを使用します:

外部ロードバランサー - 外部に面したコンポーネント（主にRails）にトラフィックを送信します。
内部ロードバランサー - PraefectやPgBouncerなど、HA構成でデプロイされたいくつかの内部コンポーネントにトラフィックを送信します。

どのロードバランサーを使用するか、またはその正確な設定に関する詳細は、GitLabドキュメントの範囲外です。もっとも一般的なオプションは、マシンノードにロードバランサーを設定するか、クラウドプロバイダーが提供するサービスなどを使用することです。クラウドネイティブハイブリッド環境をデプロイする場合、チャートはKubernetes Ingressを使用して外部ロードバランサーのセットアップを処理できます。

各アーキテクチャクラスには、マシンに直接デプロイするのに推奨されるベースマシンサイズが含まれています。ただし、選択したロードバランサーや予想されるワークロードなどの要因に基づいて調整が必要になる場合があります。マシンはさまざまなネットワーク帯域幅を持つ可能性があり、それも考慮に入れる必要があります。

次のセクションでは、ロードバランサーに関する追加のガイダンスを提供します。

バランシングアルゴリズム

ノードへの呼び出しを均等に分散させ、良好なパフォーマンスを確保するには、可能な限り最小接続ベースのロードバランシングアルゴリズムまたは同等のものを使用します。

ラウンドロビンアルゴリズムは、実際の運用では接続を均等に分散させないことが知られているため、推奨しません。

ネットワーク帯域幅

マシンにデプロイされたときにロードバランサーが利用できる合計ネットワーク帯域幅は、クラウドプロバイダー間で著しく異なる場合があります。AWSなどの一部のクラウドプロバイダーは、クレジットを使用したバーストシステムで動作するため、任意のタイミングで利用できる帯域幅が決まる場合があります。

ロードバランサーに必要なネットワーク帯域幅は、データの形式やワークロードなどの要因によって異なります。各アーキテクチャクラスに推奨されるベースサイズは、実際のデータに基づいて選択されています。ただし、大規模なモノレポの一貫したクローン作成、GitLabコンテナレジストリの大量使用、大規模なCIアーティファクト、または大量のファイルの頻繁な転送を伴うワークロードなど、一部のシナリオでは、それに応じてサイズを調整する必要がある場合があります。

スワップなし

リファレンスアーキテクチャでは、スワップは推奨されていません。スワップは、パフォーマンスに大きな影響を与えるフェイルセーフです。アーキテクチャは、ほとんどの場合、スワップの必要性を回避するのに十分なメモリを持つように設計されています。

Praefect PostgreSQL

Praefectには独自のデータベースサーバーが必要です。完全なHAを実現するには、サードパーティのPostgreSQLデータベースソリューションが必要です。

将来的には、これらの制限に対する組み込みソリューションを提供したいと考えています。それまでの間、仕様に反映されているようにLinuxパッケージを使用して、非HA PostgreSQLサーバーをセットアップできます。詳細については、次のイシューを参照してください:

omnibus-gitlab#7292。
gitaly#3398。

推奨されるクラウドプロバイダーとサービス

次のリストはすべてを網羅したものではありません。ここにリストされていない他のクラウドプロバイダーも同じ仕様で動作する可能性がありますが、検証されていません。ここにリストされていないクラウドプロバイダーサービスについては、各実装が大きく異なる可能性があるため、注意して使用してください。本番環境で使用する前に十分にテストしてください。

次のアーキテクチャは、テストと実際の使用状況に基づいて、次のクラウドプロバイダーに推奨されます:

リファレンスアーキテクチャ	GCP	AWS	Azure	ベアメタル
Linuxパッケージ	🟢	🟢	🟢¹	🟢
クラウドネイティブハイブリッド	🟢	🟢

さらに、次のクラウドプロバイダーサービスをアーキテクチャの一部として使用することをおすすめします:

クラウドサービス	GCP	AWS	Azure	ベアメタル
オブジェクトストレージ	🟢 Cloud Storage	🟢 S3	🟢 Azure Blob Storage	🟢 MinIO
データベース	🟢 Cloud SQL¹	🟢 RDS	🟢 Azure Database for PostgreSQLフレキシブルサーバー
Redis	🟢 Memorystore	🟢 ElastiCache	🟢 Azure Cache for Redis (Premium)

最適なパフォーマンスを得るには、特に大規模環境（500 RPS / 25,000ユーザー以上）では、GCP Cloud SQLにEnterprise Plus Editionを使用してください。ワークロードによっては、サービスのデフォルトよりも大きな最大接続数を指定する必要がある場合があります。
良好なパフォーマンスを確保するには、Azure Cache for RedisのPremiumプランをデプロイします。

データベースサービスのベストプラクティス

LinuxパッケージにバンドルされているPostgreSQL、PgBouncer、およびConsulサービスディスカバリコンポーネントの代わりに、PostgreSQL用のサードパーティの外部サービスを使用できます。

サポートされているPostgreSQLバージョンを実行する信頼できるプロバイダーを使用してください。これらのサービスは正常に動作することが知られています:

Google Cloud SQL。
Amazon RDS。

外部データベースサービスを使用する場合は、以下を考慮してください:

最適なパフォーマンスを得るには、読み取りレプリカでデータベースロードバランシングを有効にします。ノード数を標準のLinuxパッケージのデプロイで使用されている数に合わせます。このアプローチは、大規模環境（1秒あたり200を超えるリクエスト、または10,000を超えるユーザー）において特に重要です。
オプションはサービスごとに異なるため、データベース接続プーラーは必要ありません。環境のサイズに応じて、接続数の設定を調整する必要がある場合があります。プーリングが必要な場合は、サードパーティのオプションを調査するしてください。GitLabにバンドルされているPgBouncerは、バンドルされているPostgreSQLでのみ動作するためです。データベースロードバランシングもそれに応じて負荷を分散できます。クラウドプロバイダーのプーラーが、ボトルネックなしに総負荷を処理できることを確認してください。たとえば、Azure Database for PostgreSQLフレキシブルサーバーはオプションでPgBouncerをデプロイできますが、PgBouncerはシングルスレッドであるため、負荷が高いとボトルネックになる可能性があります。複数のノードにまたがるデータベースロードバランシングを使用して、この問題を軽減します。
高可用性ノードの要件は、サービスによって異なり、Linuxパッケージのインストールとは異なる場合があります。
GitLab Geoの場合、サービスがリージョン間レプリケーションをサポートしていることを確認してください。

サポートされていないデータベースサービス

次のデータベースクラウドプロバイダーサービスは、サポートの欠如または既知の問題があるため推奨されません:

Amazon Auroraは互換性がなく、サポートされていません。詳細については、14.4.0を参照してください。
Azure Database for PostgreSQL単一サーバーは、現在サービスが推奨されておらず、サポートされていないバージョンのPostgreSQLで実行されるため、サポートされていません。また、パフォーマンスと安定性の問題があります。
Google AlloyDBおよびAmazon RDS Multi-AZ DBクラスターはテストされておらず、推奨されていません。どちらのソリューションもGitLab Geoでは動作しないことが予想されます。
- Amazon RDS Multi-AZ DBインスタンスは別の製品であり、サポートされています。

Redisサービスのベストプラクティス

標準的でパフォーマンスが良く、サポートされているバージョンを実行する外部Redisサービスを使用してください。サービスは以下をサポートしている必要があります:

Redisスタンドアロン（Primary x Replica）モード - Redis Clusterモードは特にサポートされていません
レプリケーションによる高可用性
Redisエビクションポリシーを設定する機能

Redisは基本的にシングルスレッドです。200 RPS / 10,000ユーザー以上のクラスをターゲットとする環境では、最適なパフォーマンスを実現するために、インスタンスをキャッシュと永続データに分離します。

現時点では、RedisサービスのServerlessバリアントはサポートされていません。

オブジェクトストレージのベストプラクティス

GitLabは、動作が期待されるさまざまなオブジェクトストレージプロバイダーに対してテストされています。

完全なS3互換性を持つ信頼できるソリューションを使用してください。

推奨されるリファレンスアーキテクチャから逸脱する

リファレンスアーキテクチャから離れるほど、サポートを受けるのが難しくなります。逸脱するたびに複雑さが増し、潜在的な問題のトラブルシューティングが難しくなります。

これらのアーキテクチャは、公式のLinuxパッケージまたはHelm Chartを使用して、さまざまなコンポーネントをインストールおよび設定します。コンポーネントは、個別のマシン（仮想化またはベアメタル）にインストールされます。マシンのハードウェア要件は、設定列に記載されています。同等の仮想マシン標準サイズは、利用可能な各アーキテクチャのGCP/AWS/Azure列にリストされています。

Docker Composeを含むDockerでGitLabコンポーネントを実行できます。Dockerは十分にサポートされており、環境全体で一貫した仕様を提供します。ただし、追加のレイヤーであり、サポートが複雑になる可能性があります。たとえば、コンテナでstraceを実行できないなどです。

サポートされていないデザイン

GitLab環境デザインを幅広くサポートすることを目指していますが、特定のアプローチは効果的に機能しません。次のセクションでは、これらのサポートされていないアプローチについて詳しく説明します。

Kubernetesのステートフルコンポーネント

PostgresやRedisなどのステートフルコンポーネントをKubernetesで実行することはサポートされていません。

特にサポートされていないと明示されていない限り、他のサポートされているクラウドプロバイダーのサービスを使用できます。

個々のGitalyノードは、利用が制限された状態でKubernetesにデプロイできます。これにより、各リポジトリが単一のノードに格納される非HAソリューションが提供されます。Gitalyのデプロイオプションと制限事項のコンテキストについては、Kubernetes上のGitalyを参照してください。

ステートフルノードのオートスケール

一般的なガイダンスとして、GitLabのステートレスコンポーネント（GitLab RailsやSidekiqなど）のみをオートスケールグループで実行できます。Gitalyなど、ステートを持つ他のコンポーネントは、この構成ではサポートされていません。詳細については、イシュー2997を参照してください。

これは、PostgresやRedisなどのステートフルコンポーネントに適用されます。特にサポートされていないと明示されていない限り、他のサポートされているクラウドプロバイダーのサービスを使用できます。

一般にクラウドネイティブハイブリッド構成は、オートスケールグループよりも推奨されます。Kubernetesは、データベースの移行やMailroomなど、1つのノードでのみ実行できるコンポーネントをより適切に処理します。

複数のリージョンに単一の環境をデプロイする

GitLabは、複数のリージョンに単一の環境をデプロイすることをサポートしていません。このような構成では、リージョン間の接続が失敗した場合、過度のネットワークレイテンシーやスプリットブレインシナリオなど、重大な問題を引き起こす可能性があります。

Consul、Redis Sentinel、Praefectなど、一部のGitLabコンポーネントは、同期レプリケーションを実行するか、正しく機能するために奇数のノードが必要です。高いレイテンシーでこれらのコンポーネントを複数のリージョンに分散すると、その機能とシステム全体のパフォーマンスに深刻な影響を与える可能性があります。

この制限は、クラウドネイティブハイブリッドの代替構成を含む、考えられるすべてのGitLab環境構成に適用されます。

複数のデータセンターまたはリージョンにGitLabをデプロイするために、包括的なソリューションとしてGitLab Geoを提供しています。

検証およびテスト結果

GitLabは、これらのアーキテクチャの定期的なスモークテストとパフォーマンステストを実施し、準拠していることを確認しています。

テストの実施方法

テストは、サンプル顧客データから派生した特定のコード化されたワークロードを使用して実施され、TerraformおよびAnsibleを使用した環境デプロイにはGitLab Environment Toolkit（GET）、k6を使用したパフォーマンステストにはGitLab Performance Tool（GPT）の両方を利用します。

テストは主にGCPおよびAWSで、ベースライン設定として標準のコンピューティングサービス（GCPの場合はn1シリーズ、AWSの場合はm5シリーズ）を使用して実行されます。これらのマシンタイプは、幅広い互換性を確保するために、もっとも標準的なターゲットとして選択されました。CPUとメモリの要件を満たす異なるマシンタイプまたは新しいマシンタイプの使用は完全にサポートされています。詳細については、サポートされているマシンタイプを参照してください。これらのアーキテクチャは、他のクラウドプロバイダーまたはオンプレミスであるかどうかにかかわらず、仕様を満たすハードウェア上では同様に機能することが期待されます。

パフォーマンス目標

各リファレンスアーキテクチャは、実際の顧客データに基づいて特定のスループット目標に対してテストされます。1,000ユーザーごとに、以下をテストします:

API: 20 RPS
Web: 2 RPS
Git（プル）: 2 RPS
Git（プッシュ）: 0.4 RPS（もっとも近い整数に四捨五入）

上記のRPS目標は、CIやその他のワークロードを含む、ユーザー数に対応する環境負荷の実際の顧客データに基づいて選択されました。

テスト環境のコンポーネント間のネットワークレイテンシーは5ミリ秒未満で観測されましたが、これは厳密な要件として意図されていないことに注意してください。

テストカバレッジと結果

テストは効果的に設計されており、すべてのリファレンスアーキテクチャの目標に対して十分なカバレッジを提供します。テストの頻度は、アーキテクチャのタイプとサイズによって異なります:

Linuxパッケージ環境: GCPおよびAWS上のすべてのサイズで毎日または毎週。
クラウドネイティブ環境: GCPおよびAWSでの選択された設定の毎週のテスト。

テストには、将来のサービス導入の可能性を探るために考慮されているこれらのアーキテクチャのプロトタイプも含まれています。テスト結果は、リファレンスアーキテクチャWikiで公開されています。

リファレンスアーキテクチャ環境を維持する

リファレンスアーキテクチャ環境の維持は、一般的に他のGitLab環境と同じです。

このセクションでは、関連分野のドキュメントおよび特定アーキテクチャのノートへのリンクを紹介します。

環境をスケールする

リファレンスアーキテクチャは、出発点として設計されており、全体を通して柔軟性とスケーラビリティを備えています。パフォーマンス容量の追加やコスト削減などの理由で、デプロイ後に特定のニーズに合わせて環境を調整できます。この動作は想定されています。コンポーネントが使い果たされていることをメトリクスが示唆している場合は、反復的に、または次のアーキテクチャサイズに一括してスケールできます。

コンポーネントが常に指定されたリソースを使い果たしている場合は、大規模なスケールを実行する前に、サポートチームにお問い合わせください。

ほとんどのコンポーネントでは、通常どおり、垂直スケーリングおよび水平スケーリングを適用できます。ただし、その前に、以下の注意事項を確認してください:

PumaまたはSidekiqを垂直方向にスケールする場合、追加の仕様を使用するようにワーカーの量を調整する必要があります。Pumaは、次回の再設定時に自動的にスケールされます。ただし、事前にSidekiqの設定を変更する必要があるかもしれません。
RedisとPgBouncerは、基本的にシングルスレッドです。これらのコンポーネントでCPUが枯渇している場合は、水平方向にスケールアウトする必要があるかもしれません。
Consul、Redis Sentinel、Praefectコンポーネントは、HA形式でデプロイする場合、投票クォーラムに奇数のノードが必要です。
特定コンポーネントを大幅にスケールすると、環境のパフォーマンスに影響を与える顕著な連鎖的な影響が発生する可能性があります。詳細については、スケーリングの連鎖的な影響を参照してください。

逆に、環境が過剰にプロビジョニングされていることを示す堅牢なメトリクスがある場合は、スケールダウンできます。問題がないことを確認するために、スケールダウンするときは反復的なアプローチを取る必要があります。

スケーリングの連鎖的な影響

場合によっては、コンポーネントを大幅にスケールすると、ダウンストリームコンポーネントに連鎖的な影響が生じ、パフォーマンスに影響を与える可能性があります。アーキテクチャは、相互に依存するコンポーネントの仕様が一致するように、バランスを考慮して設計されています。特に、コンポーネントをスケールすると、依存する他のコンポーネントに追加のスループットが渡される可能性があります。その結果、これらの依存する他のコンポーネントもスケールしなければならない場合があります。これを確認するには、スケールする前に、すべての依存サービスの飽和メトリクスを監視します。相互に依存する複数のコンポーネントが飽和状態を示している場合は、ボトルネックがコンポーネント間で単純に移動するのを防ぐために、順番にではなく、調整された方法でまとめてスケールする必要があります。

アーキテクチャは、アップストリームコンポーネントのスケールに対応できるように、柔軟性を持つように設計されています。ただし、念のため、環境に大幅な変更を加える前に、サポートチームにお問い合わせください。

次のコンポーネントは、大幅にスケールされた場合に他のコンポーネントに影響を与える可能性があります:

PumaとSidekiq - PumaまたはSidekiqワーカーを大幅にスケールアップすると、内部ロードバランサー、PostgreSQL（存在する場合はPgBouncer経由）、Gitaly（存在する場合はPraefect経由）、およびRedisへの同時接続数が増加します。
- Redisは基本的にシングルスレッドです。スループットの増加により、結合されたクラスターでCPUが枯渇する場合は、Redisを個別のインスタンス（たとえば、キャッシュと永続）に分割する必要があるかもしれません。
- PgBouncerもシングルスレッドですが、スケールアウトすると、新しいプールが追加され、Postgresへの合計接続数が増加する可能性があります。Postgres接続の管理経験がある場合にのみこれを行うことを強くおすすめします。自信がない場合はサポートを求めてください。
Gitaly Cluster（Praefect）/ PostgreSQL - ノードを追加するための大幅なスケールアウトは、プライマリノードへのレプリケーション呼び出しが増加するため、HAシステムとパフォーマンスに悪影響を与える可能性があります。

非HAアーキテクチャからHAアーキテクチャへのスケーリング

ほとんどの場合、環境のリソースを増やすには、垂直スケーリングのみが必要です。ただし、HA環境に移行する場合は、次のコンポーネントをHA形式に切り替えるために追加の手順が必要です。

詳細については、次のドキュメントを参照してください:

アップグレード

リファレンスアーキテクチャ環境のアップグレードは、他のGitLab環境と同じです。詳細については、GitLabのアップグレードを参照してください。ゼロダウンタイムアップグレードも利用できます。

リファレンスアーキテクチャは、作成した順序と同じ順序でアップグレードする必要があります。

モニタリング

インフラストラクチャとGitLabは、さまざまなオプションを使用してモニタリングできます。詳細については、いくつかのモニタリングソリューションのドキュメントを参照してください。

GitLabアプリケーションには、ソリューションに接続できるPrometheusおよびさまざまなPrometheus互換エクスポート機能がバンドルされています。

更新履歴

以下は、リファレンスアーキテクチャの大幅な更新の履歴です（2021-01-01以降、昇順）。少なくとも3か月に1回は更新することを目指しています。

変更の完全な履歴は、GitLabプロジェクトで確認できます。

2025:

2025-08: Gitalyロールを使用するようにGitalyの構成を更新しました。
2025-02: サポートされているマシンタイプと、リストされている例が推奨するデフォルトとして意図されていないことについて、さらに明確にしました。

2024:

2024-12: 初期サイズを選択するためのガイダンスとして、_大きめで開始する_セクションを追加しました。
2024-08: RPSの計算方法に関する例をさらにいくつか追加して、予想される負荷セクションを更新しました。
2024-08: 正しいRedis設定になるように、40 RPSまたは2,000ユーザーページのRedis設定を更新しました。
2024-08: 2,000のモニタリングノードでPrometheusのSidekiq設定を更新しました。
2024-08: 追加機能を見つけやすくするために、次のステップのパンくずリストセクションをページに追加しました。
2024-05: Redis SentinelをRedis自体と併置することに関する最新のガイダンスを示すために、60 RPSまたは3,000ユーザーおよび100 RPSまたは5,000ユーザーのページを更新しました。
2024-05: より正確なコスト見積もりを提供するために、計算ツールが開始点にすぎず、特定の用途に合わせて調整する必要があることをより適切に反映するように、Cost to runセクションの名前をCost calculator templatesに変更しました。
2024-04: GCPのクラウドネイティブハイブリッドのWebserviceノードの推奨サイズを更新しました。また、NGINXポッドの推奨をDaemonSetとしてWebserviceノードプールで実行するように調整しました。
2024-04: 16 GBの推奨メモリターゲットに従うように、20 RPS / 1,000ユーザーアーキテクチャ仕様を更新しました。
2024-04: より明確にするため、また適切なサイズ設定に役立てるために、リファレンスアーキテクチャのタイトルを更新してRPSを含めました。
2024-02: VMにデプロイする場合、ロードバランサーノードの推奨サイズを更新しました。また、ネットワーク帯域幅の考慮事項に関するノートを追加しました。
2024-02: Sidekiqの最大同時実行設定は非推奨となり、明示的に設定する必要がなくなったため、例から削除しました。
2024-02: RailsノードでSidekiqを無効にし、アーキテクチャ図を更新するために、2,000のSidekiqの推奨事項を調整しました。
2024-01: すべてのリファレンスアーキテクチャサイズと最新のクラウドサービスについて、Azureの推奨事項を更新しました。

2023:

2022:

2021: