GitLab Orbitをセットアップする

GitLab Orbitは、インスタンスの隣にHelmリリースとして動作します。IndexerはClickHouseデータレイクを読み取り、GitLab内部APIを通じてソースコードをフェッチします。Webサーバーはグラフへのクエリに応答します。

GitLab OrbitはHTTP経由でGitLabを呼び出し、GitLabはポート50054のgRPC経由でGitLab Orbitを呼び出します。両方向が開いている必要があります。GitLab OrbitはGitalyに直接接続しません。

前提条件:

• データレプリケーションが実行中で、データレイクに行が届いていること。
• インデックス作成するグループのオーナーロール。
• GitLabへの管理者アクセス。

GitLab Orbitを次の順序でセットアップします:

1. ClickHouseデータベースとIDを作成する。
2. GitLabでGitLab Orbitを有効にする。
3. 認証情報をGitLab Orbitで利用可能にする。
4. GitLab Orbitをインストールする。
5. グループのインデックス作成を有効にする。

ClickHouseデータベースとIDを作成する

GitLab Orbitには専用のグラフデータベースと3つのユーザーが必要です:

データベースとユーザーを作成するステートメントはGitLab Orbitイメージ内に含まれているため、実行するバージョンと常に一致します。ステートメントはべき等です。GitLab Orbitは起動時にグラフデータベースを作成せず、ディスパッチャーは既存のデータベースに対してのみスキーママイグレーションを実行します。

データベースとIDを作成するには:

1. ステートメントを読み取ります:

   docker run --rm --entrypoint cat \
     registry.gitlab.com/gitlab-org/orbit/knowledge-graph/gkg:0.96.0 \
     /usr/share/gkg/clickhouse-setup.sql

2. グラフデータベース名、データレイクデータベース名、および各ユーザーのパスワードを置き換えます。グラフデータベース名にはorbitを使用します。

3. 管理者としてClickHouseに対して結果を実行します。ステートメントはグラフデータベースを作成し、gkg_appロールにそのデータベースで必要な権限を付与します。

4. 同梱ファイルに含まれていない3つのGRANTを追加します:

   GRANT SELECT ON system.parts TO gkg_app;
   GRANT SELECT ON system.tables TO gkg_app;
   GRANT SELECT ON system.dictionaries TO gkg_reader_app;

自分で運用するClickHouseインスタンスでは、すべてのユーザーがsystemデータベースを読み取れるため、これらのGRANTは何も変更しません。マネージドClickHouseは通常systemデータベースへのアクセスを制限します。GRANTがない場合、新しいバージョンがプロモートされるとスキーママイグレーションが停止し、クエリパスの解決が失敗します。どちらの場合もGRANTを追加してください。マネージドサービスに移行しても、設定はそのまま機能します。

GitLab OrbitはHTTPインターフェース（ポート8123）またはTLS使用時はポート8443でClickHouseに接続します。Siphonはポート9000のネイティブプロトコルを使用するため、HTTPポートとポート9000の両方がクラスターから到達可能である必要があります。

GitLabでGitLab Orbitを有効にする

GitLabとGitLab Orbitは1つの対称キーで相互に認証し、GitLabがそのキーを所有します。後のステップでクラスターにキーをコピーする前にキーが存在するよう、まずGitLabでGitLab Orbitを有効にします。

開始前にgRPCエンドポイントを決定します。GitLabはポート50054のTLS経由でエンドポイントに接続します。設定のスキームが接続の暗号化を制御するため、値はtls://で始まる必要があります。

GitLab Orbitチャートをインストールするまで、GitLabはGitLab Orbitに接続できません。それ以前の接続エラーは想定内です。

認証情報をGitLab Orbitで利用可能にする

GitLab OrbitはKubernetes Secretの各キーから認証情報を読み取ります。Secretを作成する前にネームスペースが存在している必要があります。次のセクションのvaluesファイルは、GitLab Orbitネームスペース内にgkg-secretsという名前のSecretが1つあり、以下のキーを持つことを想定しています:

両方のキーエントリは同じ値を保持します。各キーを異なるSecretから取得するには、secrets.perKeyを使用します。

値は既存のシークレットマネージャーで管理することをお勧めします。External Secrets Operatorなどのツールを使用してクラスターに同期します。平文を他の場所に保存しないでください。

gRPCエンドポイント用のTLS証明書も提供する必要があります。詳細については、TLSとネットワーク要件を参照してください。

GitLab Orbitをインストールする

1. 以下をorbit-values.yamlとして保存し、プレースホルダーを置き換えます:

   image:
     tag: "0.96.0"
   
   secrets:
     perKey:
       gitlabJwtVerifyingKey: {secretName: gkg-secrets}
       gitlabJwtSigningKey: {secretName: gkg-secrets}
       datalakePassword: {secretName: gkg-secrets}
       graphPassword: {secretName: gkg-secrets}
       graphReadPassword: {secretName: gkg-secrets}
   
   # Off by default. Creates the graph schema on first run and schedules indexing.
   dispatcher:
     enabled: true
   
   # HTTP interface. For a TLS endpoint such as ClickHouse Cloud,
   # add httpPort: 8443 and ssl: true to both blocks.
   clickhouse:
     datalake:
       host: <clickhouse_host>
       database: gitlab_clickhouse_main_production
       user: gkg_siphon_reader
     graph:
       host: <clickhouse_host>
       database: orbit
       user: gkg_writer
       readUser: gkg_reader
   
   # The same NATS cluster Siphon publishes to.
   nats:
     url: "nats://nats.nats.svc.cluster.local:4222"
   
   # The GitLab URL the cluster can reach. If GitLab is exposed under a host name
   # that does not match its certificate, keep baseUrl on the certificate name and
   # add resolveHost with the host to route to.
   gitlab:
     baseUrl: "https://gitlab.example.com"
   
   webserver:
     service:
       type: ClusterIP
   
   # Only when the webserver terminates TLS itself. Omit both keys if a load
   # balancer terminates in front of it.
   tls:
     enabled: true
     existingSecret: gkg-webserver-tls

2. チャートをインストールします:

   helm upgrade --install gkg \
     oci://registry.gitlab.com/gitlab-org/orbit/orbit-helm-charts/gkg \
     --version 1.5.0 \
     --namespace gitlab-orbit \
     --create-namespace \
     --values orbit-values.yaml

   このコマンドは直接Helmインストールのリファレンスです。ネームスペース名とデプロイ方法は、使用するツールに合わせて調整してください。

3. 3つのコンポーネントがすべて実行中であることを確認します:

   kubectl -n gitlab-orbit get pods

出力には、Running状態のWebサーバー、Indexer、ディスパッチャーのポッドが一覧表示されます。チャートはメトリクス、オートスケール、アナリティクス、課金を含む他のすべてをデフォルトで無効にしています。GitLab Self-Managedではそれらを無効のままにしてください。

TLSとネットワーク要件

GitLabはポート50054のTLS経由でgRPCエンドポイントに接続します。RailsとWorkhorse両方が独自の接続を開くため、両方ともエンドポイントへのルートが必要です。

TLSは2か所のいずれかで終端できます: gkg-webserverサービスの前にあるロードバランサー、またはWebサーバー自体（tls.enabledとtls.existingSecretを使用）。証明書がクラスター内に必要なのはWebサーバーの場合のみです。

公的に信頼された認証局（CA）が発行した証明書は、GitLabで追加設定は不要です。独自のCAからの証明書の場合は、CA証明書をGitLabトラストストアに追加します。詳細については、カスタム公開証明書のインストールを参照してください。

GitLabが同じクラスター内で動作している場合、ClusterIPで十分で、エンドポイントはtls://gkg-webserver.gitlab-orbit.svc.cluster.local:50054です。証明書はGitLabが接続するホスト名に対して有効である必要があります。それ以外の場合は、クラスターがサポートする方法でサービスを公開し、アドレスをプライベートネットワーク上に保持します。

リソース要件

チャートのデフォルト値はほとんどのインストールに適しています。3つのWebサーバーレプリカはそれぞれ500m CPUと4 GiBをリクエストします。3つのIndexerレプリカはそれぞれ2 CPU、4 GiB、および5 GiBの一時的なストレージをリクエストします。これらのリクエストの合計は、SiphonとNATSを除いて約8 CPUと24 GiBになります。

Indexerには少なくとも8 CPUと16 GiBのメモリを確保してください。多数の同時インデックス作成タスクがそのすべてを使用する可能性があります。チャートの制限はデフォルトでそのヘッドルームを許容します。

Indexerはコードアーカイブをダウンロードするために、各ノードに十分な一時的なストレージも必要です。チャートはそのスクラッチスペースをindexer.tmpSizeLimit（デフォルトは10 GiB）とIndexerの一時的なストレージのリクエストおよび制限でサイズ設定します。

グループのインデックス作成を有効にする

GitLab Orbitはトップレベルグループをインデックス作成します。サブグループとプロジェクトは自動的にインデックス作成を継承します。

1. 右上隅で管理者を選択します。
2. /admin/orbitのGitLab Orbit設定ページに移動します。
3. 利用可能なグループでトップレベルグループを見つけます。
4. インデックス作成を有効にするを選択し、確認します。

グループがインデックス済みグループに移動します。

代わりにAPIでインデックス作成を有効にするには、管理者アクセス権を持つトークンを使用します:

curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/admin/knowledge_graph/namespaces/<group_id>"

インデックス作成を有効にしても、既存のデータはすぐにインデックス作成されません。新しい変更は数分でレプリケーションを通じて反映されます。既存のデータは最大1時間後にスイープによって取り込まれます。

インストールを確認する

インストールを確認するには、インデックス作成を有効にしたグループ内のプロジェクトのグラフをクエリします。

リクエストボディをrequest.jsonに格納します:

{
  "query": {
    "query_type": "traversal",
    "nodes": [{
      "id": "p",
      "entity": "Project",
      "columns": ["name", "full_path"],
      "filters": {
        "full_path": {"starts_with": "your-group/"}
      }
    }],
    "limit": 10
  },
  "response_format": "raw"
}

curl --request POST \
  --header "Authorization: Bearer <your_access_token>" \
  --header "Content-Type: application/json" \
  --data @request.json \
  --url "https://gitlab.example.com/api/v4/orbit/query"

グループのインデックス作成が完了すると、クエリは行を返します。ポッドのステータスとヘルスエンドポイントはインデックス作成を確認しません。最初のインデックス作成が完了するずっと前に両方がパスするためです。

関連トピック

• GitLab Orbitがインデックス作成する内容
• スキーマリファレンス
• Cookbook
• クエリ言語