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

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

はじめに

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

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

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

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

• どのアーキテクチャで始めるかを決定する
• 大規模なモノレポ
• 追加のワークロード
• 環境のモニタリングと調整

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

リファレンスアーキテクチャは、パフォーマンス、復元性、コストという3つの重要な要素のバランスを取るように設計されています。これらは、一般的なワークロードパターンに基づいて、GitLabを大規模にデプロイするための、検証済みの開始点を提供します。初期デプロイが容易になる一方で、ほとんどの環境は、モニタリングを通じて明らかになる実際の使用パターンに基づいて調整することでメリットが得られます。適切な開始点を選択することは重要ですが、特定のワークロード特性に基づいて調整することを想定するようにしてください。

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

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

予想される負荷

適切なアーキテクチャのサイズは、主に環境で予想されるピーク負荷によって決まります。1秒あたりのリクエスト数（RPS）は、GitLabインフラストラクチャのサイズを決定するための主要なメトリクスですが、他の要素も適用できます。

包括的なRPS分析とデータ主導のサイジングの決定については、リファレンスアーキテクチャのサイジングを参照してください。以下が提供されています:

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

RPSの迅速な見積もりには、潜在的なオプションがいくつかあります:

• 次のようなPrometheusクエリ:

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

• GitLab RPS Analyzer。

• その他のモニタリングソリューション。

• ロードバランサーの統計。

RPSを判断できない場合は、代替のサイズ設定開発手法として、Linuxパッケージおよびクラウドネイティブハイブリッドアーキテクチャに対して、ユーザー数相当量が提供されます。この数は、手動および自動での使用状況の両方を考慮して、一般的なRPS値にマッピングされます。

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

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

Linuxパッケージ（Omnibus）

Linuxパッケージベースのリファレンスアーキテクチャは、すべてのGitLabコンポーネントをパッケージとともに仮想マシンにデプロイします。一部のコンポーネント（PostgreSQL、Redis、オブジェクトストレージ）は、オプションでクラウドプロバイダーサービスを使用できます。

次のRPSターゲットは、典型的なワークロード構成を反映しています。非定型的なワークロード構成の場合は、RPSの内訳を理解するを参照してください。

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

クラウドネイティブハイブリッドリファレンスアーキテクチャは、一部のステートレスコンポーネント（Webservice、Sidekiq）をKubernetesのHelm Chartを使用してデプロイし、一部のコンポーネントは仮想マシン上に残るか、クラウドプロバイダーサービス（PostgreSQL、Redis、オブジェクトストレージ）を使用します。

クラウドネイティブファースト（ベータ）

クラウドネイティブファーストアーキテクチャは、ワークロード特性に基づいて4つの標準化されたサイズ（S/M/L/XL）で最新のデプロイ手法をターゲットとする、次世代のアーキテクチャです。これらのアーキテクチャは、すべてのGitLabコンポーネントをKubernetesにデプロイし、PostgreSQL、Redis、およびオブジェクトストレージには、マネージドサービスやオンプレミスオプションを含む外部のサードパーティソリューションを使用します。

また、これらのアーキテクチャにより、運用オーバーヘッドの削減、デプロイの簡素化、およびKubernetesオーケストレーションによるレジリエンスの強化を実現できます。

詳しくは、Cloud Native Firstリファレンスアーキテクチャをご覧ください。

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

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

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

• 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メカニズムが有効になるときに、ごく短時間ダウンタイムが発生する可能性があることに注意してください。

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

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

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

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

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

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

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

これらの要因の包括的な分析については、リファレンスアーキテクチャのサイジングを参照してください。以下について説明されています:

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

この状況に該当する場合は、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 expected load?</b>)

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

   L3A("Do you need HA?<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 expected load with HA]
   L4C><b>Recommendation</b><br><br>Cloud Native Hybrid architecture<br>closest to expected load]
   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("Do you need cross regional distribution</br> or disaster recovery?") --> |Yes| L6A><b>Additional Recommendation</b><br><br> GitLab Geo]
   L4A ~~~ L5A
   L4B ~~~ L5A
   L4C ~~~ L5A
   L4D ~~~ L5A

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

要件

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

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

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

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

• 新世代のマシンタイプ（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アプリケーションの要件に合わせて奇数のゾーンを使用する必要があります。

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

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

大規模なモノレポ

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

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

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

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

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

追加のワークロード

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

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

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

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

ロードバランサー

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

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

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

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

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

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

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

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

ネットワーク帯域幅

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

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

スワップなし

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

Praefect PostgreSQL

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

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

• omnibus-gitlab#7292。
• gitaly#3398。

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

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

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

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

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

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

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

• Google Cloud SQL。
• Amazon RDS。

構成に関する考慮事項

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

• 最適なパフォーマンスを得るには、読み取りレプリカでデータベースロードバランシングを有効にします。ノード数を標準のLinuxパッケージのデプロイで使用されている数に合わせます。このアプローチは、大規模環境（1秒あたり200を超えるリクエスト、または10,000を超えるユーザー）において特に重要です。
• 高可用性ノードの要件は、サービスによって異なり、Linuxパッケージのインストールとは異なる場合があります。
• GitLab Geoの場合、サービスがクロスリージョンレプリケーションをサポートしていることを確認してください。

接続管理

外部データベースサービスとの最適な接続処理を行うには、以下を行います:

• データベースロードバランシングを使用して、接続を読み取りレプリカ全体に分散します。
• 環境のサイズとワークロードに合わせてPostgreSQL接続数を構成します。パフォーマンスに基づいてモニタリングおよび調整します。
• 追加の接続プールが必要な場合は、独自のPgBouncerをデプロイします。他のサードパーティのプールソリューションも機能する可能性はありますが、未検証です。

クラウドプロバイダーのプールサービスには、次の制限があり、互換性がないか、推奨されていません:

• AWS RDS Proxy: GitLabでの使用は検証されていません。
• Azure Database for PostgreSQL PgBouncer: 制限された可観測性を備えたシングルスレッドアーキテクチャ。高負荷時にボトルネックが発生する可能性があります。

データベースサービスの互換性

次のデータベースクラウドプロバイダーサービスは、互換性がないか、推奨されていません:

• Amazon Auroraは互換性がなく、サポートされていません。詳細については、14.4.0を参照してください。
• 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ユーザー以上のクラスをターゲットとする環境では、最適なパフォーマンスを実現するために、インスタンスをキャッシュと永続データに分離します。

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

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を参照してください。

Gitalyを完全にクラウドネイティブなセットアップの一部としてKubernetesにデプロイするリファレンスアーキテクチャについては、Cloud Native Firstリファレンスアーキテクチャ（ベータ）を参照してください。

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

一般的なガイダンスとして、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やその他のワークロードを含む、ユーザー数に対応する環境負荷の実際の顧客データに基づいて選択されました。

テストカバレッジと結果

テストは、リファレンスアーキテクチャのターゲットに対して効果的で良好なカバレッジを提供するように設計されており、Linuxパッケージ環境とCloud Native環境の両方をカバーしています。テストされた特定の環境と設定は、最高のカバレッジと費用対効果のバランスを確保するために定期的にレビューされ、時間とともに変更される場合があります。

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

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

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

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

環境をスケールする

リファレンスアーキテクチャは、一般的なワークロードパターンに基づく検証済みの開始点として設計されており、最終的な構成ではありません。ほとんどの本番環境デプロイは、モニタリングを通じて明らかになる実際の使用パターンに基づいて調整することでメリットが得られます。アーキテクチャは全体的にスケーラブルであり、ワークロードの特性が明確になるにつれて、反復的に調整できます。スケーリングは、メトリクスが持続的なリソース圧力を示す場合に、コンポーネントごと、または次のアーキテクチャサイズにまとめて行うことができます。

スケーリングのタイミング

ほとんどのデプロイは、実際のワークロードパターンを観察した後で調整するとメリットが得られます。スケーリングをトリガーする一般的なシナリオには、次のようなものがあります:

リソースサイズの調整:

• APIトラフィックが全体のRPSの90%を超えるようなAPI中心のワークロードにおいて、Webサービス/Railsの処理能力を向上させる（RPS構成を理解するを参照）
• モノレポ中心の環境、またはリポジトリサイズが2GBを超える場合におけるGitalyのスケーリング（コンポーネント調整を特定するを参照）
• 高いCI/CDスループットまたは重いバックグラウンドジョブ処理のためにSidekiqワーカーを調整する

設定のチューニング:

• 同時アクセスパターンに基づいてGitalyリポジトリのcgroupカウントを設定する（Gitaly cgroupを参照）
• ジョブ処理の最適化のためにSidekiqキューの優先度を構成する（特定のジョブクラスの処理を参照）

アーキテクチャの最適化:

• 読み取り負荷の高いワークロードのためにPostgreSQL読み取りレプリカを追加する
• さまざまなジョブタイプのためにSidekiqを特殊化されたプールに分割する
• トラフィックが急増する環境の最小インスタンス数を調整する

これらの調整は一般的なものであり、想定内の対応です。リファレンスアーキテクチャはあくまで基盤を示すものに過ぎず、最適な構成は実際のワークロードの監視結果によって判断されます。お使いの環境を体系的に評価する方法については、リファレンスアーキテクチャのサイジングを参照してください。

GitLab Duo Agent Platformのスケーリング

GitLab Duo Agent Platformでは、標準的なGitLabワークロードに加えて、追加のインフラストラクチャ要件が発生します。エージェントプラットフォームのワークフローは、GitLab Rails APIを介して実行され、Sidekiqを通じて非同期的にジョブを処理し、コンテキストと分析のためにリポジトリデータにアクセスします。

主要なコンポーネントへの影響:

• Rails（Webservice/Puma）- Agent Platform APIのリクエストは全体のリクエスト負荷を増加させます。また、AI応答をストリーミングするためのWebSocket接続はWorkhorseによって管理されます
• Sidekiq- AI完了ジョブとワークフロー状態の更新は、バックグラウンドジョブとして処理されます
• PostgreSQL- エージェントのワークフローセッションと状態データは、データベースに格納されます
• Gitaly- コードコンテキスト取得のためのリポジトリファイルアクセス、およびエージェントが生成した変更に対するコミット操作

エージェントプラットフォームの採用を計画している環境の場合は次のとおりです:

• 標準のワークロードRPSに基づいて、推奨されるアーキテクチャサイズをデプロイします
• 最初のロールアウト中にRails CPU使用率をモニタリングします
• Sidekiq CPU使用率とジョブキューの深さをモニタリングします
• ワークフロー状態管理によるトランザクションレートの増加について、PostgreSQLをモニタリングします
• コード解析機能からのファイルアクセスパターンの増加について、Gitalyを監視します

これらのコンポーネントの監視に関するPrometheusのクエリの例については、Prometheusのクエリ例を参照してください。

リソースプレッシャーが継続的に観察される場合は、影響を受けているコンポーネントをスケールして、キャパシティを増やしてください。Kubernetesのデプロイでは、ポッドのレプリカとノードプールのキャパシティを増やしてください。Linuxパッケージのデプロイでは、ノードを追加して水平にスケールするか、ノードの仕様を増やして垂直にスケールしてください。

エージェントプラットフォームの使用強度と有効になっている特定の機能に基づいて、リソース要件は異なります。リファレンスアーキテクチャは、標準的なGitLabのワークロードに加えて、一般的なエージェントプラットフォームの使用パターンに対して十分なベースラインキャパシティを提供します。

スケール方法

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

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

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

スケーリングの波及効果

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

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

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

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

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

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

• RedisからRedis Sentinelを使用したマルチノードRedisへ
• PostgresからConsul + PgBouncerを使用したマルチノードPostgresへ
• GitalyからGitaly Cluster（Praefect）へ

アップグレード

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

モニタリング

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

更新履歴

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