• ユースケース
  • Gitalyクラスター
• どのように動作するか
  • アーキテクチャ
• Geo を実行するための要件
  • ファイアウォールのルール
    • 内部URL
  • Geoトラッキングデータベース
  • Geo ログカーソル
• 制限事項
  • レプリケーション/検証の制限
• セットアップ手順
• インストール後のドキュメント
  • Geo の設定
  • Geo のアップグレード
  • レプリケーションの一時停止と再開
  • 複数ノードの Geo 設定
  • オブジェクトストレージを使った Geo の設定
  • ディザスタリカバリ
  • コンテナ レジストリの複製
  • Geo セカンダリプロキシ
  • シングルサインオン(SSO)
    • LDAP
  • セキュリティレビュー
  • Geoのチューニング
  • 場所を意識した Git URL の設定
  • バックフィル
• Geoサイトの削除
• Geoの無効化
• よくある質問
• ログファイル
• トラブルシューティング

Geo

Geo は、広範囲に分散した開発者や、ディザスタリカバリ戦略の一環としてウォームスタンバイを提供するためのソリューションです。

一つの GitLab インスタンスから離れた場所にいるチームにとって、大きなリポジトリのフェッチには長い時間がかかることがあります。

Geoは、GitLabインスタンスの読み込み専用のローカルサイトを提供します。これにより、大規模なリポジトリのクローンやフェッチにかかる時間を短縮し、開発者をスピードアップすることができます。

Geoの紹介ビデオについては、Introduction to GitLab Geo - GitLab Featuresをご覧ください。

ドキュメントの正しいバージョンを使っていることを確認するには、GitLab.com の Geo ページに行き、Switch branch/tagドロップダウンリストから適切なリリースを選択してください。例えば、v13.7.6-ee.

Geo は、Geo Glossary に記載されている定義された用語のセットを使用します。これらの用語に慣れておいてください。

ユースケース

Geoを導入すると、次のようなメリットがあります：

• ディストリビューション開発者が大規模なリポジトリやプロジェクトのクローン作成および取得にかかる時間を数分から数秒に短縮します。
• 開発者全員が、どこにいてもアイデアに貢献し、並行して作業できるようにします。
• プライマリサイトと セカンダリサイトの間で読み取り専用の負荷をバランスさせます。

さらに

• GitLabウェブインタフェースで利用可能なあらゆるデータの読み込みに加え、プロジェクトのクローンやフェッチに使用できます（制限を参照）。
• 離れたオフィス間の遅い接続を克服し、ディストリビューションチームのスピードを改善することで時間を節約します。
• 自動化されたタスク、カスタムインテグレーション、内部ワークフローのロード時間を短縮します。
• ディザスタリカバリシナリオで セカンダリサイトに迅速にフェイルオーバーできます。
• セカンダリサイトへの 計画的なフェイルオーバーが可能。

Geoが提供：

• 読み取り専用のセカンダリサイト：プライマリGitLab サイトを 1 つ維持しながら、ディストリビューションチームごとに読み取り専用のセカンダリサイトを使用できます。
• 認証システムフック：セカンダリサイトは、プライマリインスタンスからすべての認証データ（ユーザーアカウントやログインなど）を受け取ります。
• 直感的なUI：セカンダリサイトでは、チームが慣れ親しんだ同じウェブインターフェースを使用します。さらに、書き込みオペレーションをブロックし、ユーザーがセカンダリサイトにいることを明確にするビジュアル通知があります。

Gitalyクラスター

GeoはGitaly Clusterと混同しないでください。GeoとGitaly Clusterの違いについては、Geoとの比較をご覧ください。

どのように動作するか

Geo インスタンスは、あらゆるデータの読み取りだけでなく、プロジェクトのクローン作成やフェッチにも使用できます。これによって、長距離の大規模なリポジトリでの作業がより高速になります。

Geo を有効にすると、：

• 元のインスタンスはプライマリサイトとして知られています。
• 複製された読み取り専用サイトはセカンダリサイトと呼ばれます。

次のことに注意してください：

• セカンダリー・サイトは、プライマリー・サイトと次のように話します：
  • ログイン用ユーザーデータの取得(API).
  • リポジトリ、LFS オブジェクト、および添付ファイルの複製 (HTTPS + JWT)。
• プライマリサイトは、セカンダリサイトと通信して変更を通知しません(API)。
• セカンダリサイトに直接プッシュすることができます (Git LFS を含む HTTP と SSH の両方)。
• Geoを使う場合は制限があります。

アーキテクチャ

以下の図は、Geo の基本的なアーキテクチャを示しています。

この図では

• プライマリ・サイトと1つのセカンダリ・サイトの詳細があります。
• データベースへの書き込みはプライマリサイトでのみ実行できます。セカンダリサイトはPostgreSQLのストリーミングレプリケーションによってデータベースの更新を受け取ります。
• LDAPサーバが存在する場合は、ディザスタリカバリシナリオ用にレプリケーションを設定する必要があります。
• セカンダリサイトは、JWTで保護された特別な作成者を使用して、プライマリサイトに対して異なるタイプの同期を実行します：
  • リポジトリは Git over HTTPS でクローン/更新されます。
  • 添付ファイル、LFS オブジェクト、その他のファイルは、非公開 API エンドポイントを使って HTTPS 経由でダウンロードされます。

Git オペレーションを行うユーザーの立場から：

• プライマリサイトは完全に読み書き可能な GitLab インスタンスとして振る舞います。
• セカンダリサイトは読み込み専用ですが、Gitのプッシュオペレーションをプライマリサイトにプロキシします。これにより、セカンダリサイトはプッシュオペレーションをサポートしているように見えます。

図をシンプルにするために、必要なコンポーネントの一部を省略しています。

• Git over SSHには、gitlab-shell とOpenSSHが必要です。
• Git over HTTPS にはgitlab-workhorse が必要です。

セカンダリサイトには、2つの異なる PostgreSQL データベースが必要です：

• メインのGitLabデータベースからデータをストリームする読み取り専用のデータベースインスタンス。
• セカンダリサイトが内部で使用する、レプリケートされたデータを記録するもう一つのデータベースインスタンス。

セカンダリサイトでは、追加のデーモンがあります：Geo Log Cursor。

Geo を実行するための要件

Geo の実行には以下のものが必要です：

• OpenSSH 6.9 以降をサポートするオペレーションシステム (データベース内の作成者の SSH キーを高速に検索するために必要です) 以下のオペレーティングシステムは、OpenSSH の最新バージョンと共に出荷されていることが確認されています：
  • CentOS7.4 以降
  • Ubuntu16.04以降
• PostgreSQL 12または13とストリーミングレプリケーション
  • PostgreSQL 12は非推奨であり、GitLab 16.0で削除されます。
• Git 2.9以降
• ユーザー側でLFSを使う場合はGit-lfs 2.4.2以降
• すべてのサイトが同じGitLabバージョンを実行している必要があります。
• 全てのサイトが同じバージョンのPostgreSQLを実行する必要があります。
  • Geo サイト間で異なるバージョンのオペレーションシステムを使用している場合は、データベースインデックスの無言の破損を避けるため、Geo サイト間でOS ロケールデータの互換性を確認してください。
• すべてのサイトで同じリポジトリ ストレージを定義する必要があります。

さらに、GitLabの最小要件を確認し、より良い体験のためにGitLabの最新バージョンを使用してください。

ファイアウォールのルール

次の表は、Geo のプライマリサイトと セカンダリサイトの間で開く必要のある基本的なポートの一覧です。フェイルオーバーを簡素化するため、双方向でポートを開く必要があります。

GitLab が使用するポートの一覧はPackage defaultsをご覧ください。

内部URL

Geo セカンダリサイトからプライマリ Geo サイトへの HTTP リクエストは、プライマリ Geo サイトの内部 URL を使用します。これが管理エリアのプライマリ Geo サイト設定で明示的に定義されていない場合、プライマリサイトの公開 URL が使用されます。

プライマリ Geo サイトの内部 URL を更新するには：

1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
2. Admin Areaを選択します。
3. 左サイドバーでGeo > Sites を選択します。
4. プライマリ・サイトの「編集」を選択します。
5. 内部URLを変更し、変更を保存を選択します。

Geoトラッキングデータベース

トラッキングデータベースインスタンスは、ローカルインスタンスのディスク上で更新が必要なものをコントロールするためのメタデータとして使用されます。例えば

• 新しいアセットをダウンロード
• 新しい LFS オブジェクトを取得します。
• 最近更新されたリポジトリから変更を取得します。

複製されたデータベースインスタンスは読み取り専用なので、セカンダリサイトごとにこの追加のデータベースインスタンスが必要です。

Geo ログカーソル

このデーモンは

• プライマリサイトから セカンダリデータベースインスタンスにレプリケートされたイベントのログを読み取ります。
• Geo Tracking Database インスタンスを、実行が必要な変更で更新します。

トラッキングデータベースインスタンスで何かが更新されるようマークされると、セカンダリサイトで実行されている非同期ジョブが必要なオペレーションを実行し、状態を更新します。

この新しいアーキテクチャによって、GitLabはサイト間の接続性のイシューに強くなりました。セカンダリサイトがどれだけ長くプライマリサイトから切断されていても、全てのイベントを正しい順序で再生し、再びプライマリサイトと同期することができるからです。

制限事項

• セカンダリサイトに直接プッシュすると、リクエストを直接処理する代わりにプライマリサイトにリダイレクト（HTTPの場合）またはプロキシ（SSHの場合）します。制限としては、URI にクレデンシャルを埋め込んだ Git over HTTP は使えないということです。たとえば、https://user:personal-access-token@secondary.tld。詳しくはGeoサイトの使い方をご覧ください。
• OAuthログインを行うには、プライマリサイトがオンラインである必要があります。既存のセッションや Git は影響を受けません。セカンダリサイトがプライマリとは独立した OAuth プロバイダを使用するためのサポートは計画中です。
• インストールには複数の手動ステップが必要で、状況によっては合わせて1時間ほどかかることもあります。GitLab Environment ToolkitTerraform と Ansible スクリプトを使用して、一般的な日常タスクの自動化を含め、リファレンスアーキテクチャに基づく本番 GitLab インスタンスのデプロイとオペレーションを行うことを検討してください。エピック1465は、Geoインストールをさらに改善することを提案しています。
• セカンダリサイトでは、イシュー/マージリクエストのリアルタイム更新（ロングポーリングなど）が機能しません。
• Geo セカンダリサイトを使った Runner の高速化は公式にはサポートされていません。この機能のサポートは計画されており、エピック 9779 で追跡できます。プライマリサイトとセカンダリサイトの間でレプリケーションラグが発生し、ジョブの実行時にセカンダリサイトでパイプライン参照が利用できない場合、ジョブは失敗します。
• GitLab Runnerはセカンダリサイトに登録できません。これに対するサポートは今後予定されています。
• 選択的同期では、複製されるリポジトリとファイルが制限されます。PostgreSQL のデータ全体が複製されます。選択的同期はコンプライアンス/エクスポート制御の使用例に対応するようには構築されていません。
• Pages アクセス制御はセカンダリでは動作しません。詳細はGitLab issue #9336を参照してください。
• 複数のセカンダリサイトのディザスタリカバリで、昇格させない全てのセカンダリの完全な再同期と再設定によりダウンタイムが発生します。
• Git over SSH の場合、プロジェクトクローンの URL をどのサイトを閲覧していても正しく表示させるために、セカンダリサイトはプライマリと同じポートを使わなければなりません。GitLab issue #339262では、この制限を取り除くことを提案しています。
• セカンダリサイトに対して SSH 経由で Git をプッシュすると、1.86 GB を超えるプッシュでは動作しません。GitLab issue #413109がこのバグを追跡しています。
• セカンダリでバックアップを実行できません。

レプリケーション/検証の制限

全てのGitLabデータ型と レプリケーションと検証の既存のサポートの完全なリストがあります。

セットアップ手順

セットアップ手順については、Geo のセットアップを参照してください。

インストール後のドキュメント

セカンダリサイトにGitLabをインストールし、初期設定を行った後、インストール後の情報については以下のドキュメントを参照してください。

Geo の設定

Geo の設定については、Geo の設定を参照してください。

Geo のアップグレード

Geoサイトを最新のGitLabバージョンにアップデートする方法については、Geoサイトのアップグレードをご覧ください。

レプリケーションの一時停止と再開

GitLab 13.2 で導入されました。

アップグレード時や計画的なフェイルオーバー時など、状況によってはプライマリとセカンダリ間のレプリケーションを一時停止することが望ましい場合があります。

レプリケーションの一時停止と再開は、postgresql サービスが有効になっているセカンダリ サイトのノードからコマンド ライン ツールを使用して行います。

postgresql がスタンドアロンのデータベース・ノード上にある場合は、そのノード上のgitlab.rb に設定行gitlab_rails['geo_node_name'] = 'node_name'が含まれていることを確認します。node_name は、アプリケーション・ノード上のgeo_node_name と同じです。

一時停止：（セカンダリから）

gitlab-ctl geo-replication-pause

再開：（セカンダリから）

gitlab-ctl geo-replication-resume

複数ノードの Geo 設定

複数ノード用の Geo の設定については、複数サーバー用の Geo を参照してください。

オブジェクトストレージを使った Geo の設定

Geo with Object ストレージの設定については、Geo with Object ストレージを参照してください。

ディザスタリカバリ

ディザスタリカバリの状況で Geo を使用してデータ損失を軽減し、サービスを復元する方法については、ディザスタリカバリを参照してください。

コンテナ レジストリの複製

コンテナレジストリを複製する方法の詳細については、セカンダリサイトのコンテナレジストリを参照してください。

Geo セカンダリプロキシ

セカンダリサイトでの Geo プロキシの使用については、セカンダリサイトの Geo プロキシを参照してください。

シングルサインオン(SSO)

シングルサインオン(SSO) の設定の詳細については、シングルサインオン(SSO) を参照してください。

LDAP

LDAP の設定については、「シングルサインオンで Geo(SSO) > LDAP」を参照してください。

セキュリティレビュー

Geoセキュリティの詳細については、Geoセキュリティレビューをご覧ください。

Geoのチューニング

Geo のチューニングの詳細については、Geo のチューニングを参照してください。

場所を意識した Git URL の設定

AWS Route53 で場所を認識した Git リモート URL を設定する例については、AWS Route53 で場所を認識した Git リモート URL を参照してください。

バックフィル

セカンダリサイトがセットアップされると、セカンダリサイトは バックフィルと呼ばれるプロセスでプライマリサイトから欠落したデータの複製を開始します。ブラウザでプライマリサイトの Geo ノードダッシュボードから各 Geo サイトの同期プロセスを監視できます。

バックフィル中に発生した障害は、バックフィル終了時に再試行されるようスケジュールされます。

Geoサイトの削除

Geo サイトの削除の詳細については、セカンダリGeo サイトの削除を参照してください。

Geoの無効化

Geo を無効にする方法については、「Geo を無効にする」を参照してください。

よくある質問

よくある質問については、Geo FAQをご覧ください。

ログファイル

Geo は構造化されたログメッセージをgeo.log ファイルに保存します。Linux パッケージインストールの場合、このファイルは/var/log/gitlab/gitlab-rails/geo.logにあります。

このファイルには、Geo がリポジトリとファイルの同期を試みたときの情報がコンテナで格納されています。ファイルの各行は、取り込むことができる個別の JSON エントリを含んでいます。例えば、Elasticsearch や Splunk などです。

使用例：

{"severity":"INFO","time":"2017-08-06T05:40:16.104Z","message":"Repository update","project_id":1,"source":"repository","resync_repository":true,"resync_wiki":true,"class":"Gitlab::Geo::LogCursor::Daemon","cursor_delay_s":0.038}

このメッセージは、Geo がプロジェクト1 に対してリポジトリの更新が必要であることを検知したことを示しています。

トラブルシューティング

トラブルシューティングの手順については、Geoトラブルシューティングをご覧ください。