GitLab Self-Managed上のGitLab Orbitを使い始める

GitLab Orbitは、ClickHouse、Kubernetes、NATSという3つのシステムに依存していますが、これらはGitLab Orbitがインストールするものではありません。 残りのセットアップ手順を進めるには、この3つのシステムがすべて存在し、到達可能である必要があります。

前提条件

• GitLab 19.2.2以降。
• GitLabインスタンスおよびそのPostgreSQLサーバーへの管理者アクセス権。
• PostgreSQLの再起動1回分のメンテナンスウィンドウ。
• GitLab用にセットアップされたClickHouse 26.2以降。
• Kubernetes 1.33以降。
• JetStreamを有効にしたNATS。

インストール順序

各ステップは前のステップに依存しています。以下の順序でコンポーネントをインストールしてください。

1. GitLab用にClickHouseをセットアップし、GitLab ClickHouseマイグレーションを実行します。
2. JetStreamを有効にしてNATSをクラスターにインストールします。
3. データレプリケーションをセットアップします: PostgreSQLを準備してからSiphonをインストールします。このステップが完了すると、GitLabの行がClickHouseデータレイクに届くようになります。
4. GitLab Orbitをセットアップします: ClickHouseのIDを作成し、チャートをインストールし、GitLabがGitLab Orbitを参照するよう設定して、トップレベルグループのインデックス作成を有効にします。

ステップ1から3はGitLab Orbitに依存しません。それぞれ個別に検証できます。

ClickHouse

GitLab Orbitには、ClickHouse 26.2以降が必要です。これは、グラフがそのリリースで導入された全文インデックスとマテリアライズド共通テーブル式を使用するためです。GitLabは25.xおよび26.xのリリースをサポートしているため、25.xリリースはGitLabの他の部分には対応しますが、GitLab Orbitには対応しません。ClickHouseに関するその他のGitLab要件は変更ありません。

まずGitLab用にClickHouseをセットアップしてください。詳細については、 ClickHouseを参照してください。 ClickHouseマイグレーションの実行および 分析用ClickHouseの有効化を含む、そのページのすべての手順を完了してください。 これらのマイグレーションにより、レプリケーションが書き込むデータレイクテーブルが作成されます。これらのテーブルがない場合、Siphonには書き込み先がなく、レプリケーションが失敗します。

GitLab Orbitは2つのデータベースを使用します。

2つのデータベースは別々のClickHouseインスタンスに配置できます。その場合、GitLab、Siphon、およびGitLab Orbitに対して、それぞれが使用するデータベースを持つインスタンスの認証情報を付与してください。

gitlab_clickhouse_main_productionデータベースは、ClickHouseのセットアップが完了した後に存在します。orbitデータベースは、GitLab Orbitのセットアップ時に作成します。GitLab Orbitは起動時にこれを作成しません。

サイジングと設定

ClickHouseには少なくとも8 CPUと32 GiBのメモリをプロビジョニングしてください。グラフのビルド中、ClickHouseは8コアをフル活用します。

ClickHouseのストレージは、少なくともGitLab PostgreSQLデータベースのサイズ以上をプロビジョニングしてください。

自分で運用するClickHouseインスタンスでは、max_bytes_before_external_sortとmax_bytes_before_external_group_byが0に設定されており、ディスクへのスピルが無効になっています。ClickHouse Cloudでは、両方が利用可能なメモリの半分に設定されています。スピルが無効の場合、大規模なソートはすべての結果をメモリに保持するため、サーバーがメモリ不足になります。defaultプロファイルで両方を設定してください。以下の値は32 GiBインスタンスに適しており、各しきい値に8 GiB、メモリ上限に20 GiBを割り当てています。

<profiles>
  <default>
    <max_bytes_before_external_sort>8589934592</max_bytes_before_external_sort>
    <max_bytes_before_external_group_by>8589934592</max_bytes_before_external_group_by>
    <max_memory_usage>21474836480</max_memory_usage>
  </default>
</profiles>

Kubernetes

GitLab Orbitには、Kubernetes 1.33以降が必要です。また、ImageVolumeフィーチャーゲートが有効になっており、コンテナランタイムでサポートされている必要があります。

GitLab OrbitはGitLabとは別のクラスターで実行できます。そのクラスターはGitLab、PostgreSQL、ClickHouse、およびNATSに到達できる必要があり、GitLabもそのクラスターに到達できる必要があります。

NATS

Siphonは変更されたすべての行をNATS JetStreamストリームに公開し、SiphonとGitLab Orbitの両方がそのストリームから読み取ります。NATSにはJetStreamの有効化と永続ボリュームが必要です。

NATSサーバーのmax_payloadを64 MBに設定してください。デフォルトの1 MBは一部のGitLabの行より小さいサイズです。Siphonはサーバーの値を読み取り、行が送信するには大きすぎるかどうかを判断します。

オブジェクトストレージ（オプション）

Siphonはスナップショットイベントをオブジェクトストアに保存します。また、max_payloadを引き上げた後もまだ大きすぎる行も同様に保存されます。デフォルトでは、SiphonはNATS JetStreamオブジェクトストアバケットを使用するため、追加のサービスは不要です。JetStreamボリュームへのトラフィックを抑えたい場合や、別の保持ポリシーを適用したい場合は、代わりにS3互換またはGoogle Cloud Storageバケットを設定してください。

GitLab Orbitはオブジェクトストレージを使用しません。グラフはClickHouseに保存されており、再度インデックス作成を行うことで再構築できます。Indexerはリポジトリのチェックアウトにノードローカルディスクを必要とします。チャートは一時的なストレージリクエストによってこのディスクのサイズを設定します。

共有設定値

以下の各値を一度決定し、それを読み取るすべてのコンポーネントで同じ値を使用してください。コンポーネントはこれらの値を他のコンポーネントと照合して検証しません。値が一致しない場合、影響を受けるコンポーネントは起動しますが、データを処理しません。

GitLab Orbitはデフォルトでストリーム名siphon_stream_main_dbを想定しています。別の名前を使用するには、siphon-values.yamlでstream_nameを設定し、orbit-values.yamlでschedule.tasks.siphon.events_stream_nameを設定してください。

次のステップ

• データレプリケーションをセットアップする