Zoekt

Zoektは、コード検索に特化して設計されたオープンソースの検索エンジンです。

このインテグレーションにより、GitLabでコードを検索するために、高度な検索の代わりに完全一致コードの検索を使用できます。完全一致と正規表現モードを使用して、グループまたはリポジトリ内のコードを検索できます。

Zoektのインストール

前提要件:

• インスタンスへの管理者アクセス権が必要です。

GitLabで完全一致コードの検索を有効にするには、少なくとも1つのZoektノードがインスタンスに接続されている必要があります。Zoektでは、以下のインストール方法がサポートされています:

• Zoektチャート
• GitLab Operator（gitlab-zoekt.install=trueを使用）。

以下のインストール方法はテスト用であり、本番環境での使用は想定されていません:

• Docker Compose
• Ansibleプレイブック

完全一致コードの検索を有効にする

前提要件:

• インスタンスへの管理者アクセス権が必要です。
• Zoektをインストールする必要があります。

GitLabで完全一致コードの検索を有効にするには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. インデックス作成を有効にするチェックボックスと検索を有効にするチェックボックスを選択します。
5. 変更を保存を選択します。

インデックス作成状態を確認する

前提要件:

• インスタンスへの管理者アクセス権が必要です。

インデックス作成のパフォーマンスは、ZoektインデクサーノードのCPUとメモリの制限に左右されます。インデックス作成状態を確認するには、次の手順に従います:

gitlab-rake gitlab:zoekt:info

gitlab-rake "gitlab:zoekt:info[10]"

Search::Zoekt::Index.group(:state).count
Search::Zoekt::Repository.group(:state).count
Search::Zoekt::Task.group(:state).count

出力例

gitlab:zoekt:info Rakeタスクは、次のような出力を返します:

Exact Code Search
GitLab version:                           18.4.0
Enable indexing:                          yes
Enable searching:                         yes
Pause indexing:                           no
Index root namespaces automatically:      yes
Cache search results for five minutes:    yes
Indexing CPU to tasks multiplier:         1.0
Number of parallel processes per indexing task: 1
Number of namespaces per indexing rollout: 32
Offline nodes automatically deleted after: 20m
Indexing timeout per project:             30m
Maximum number of files per project to be indexed: 500000
Retry interval for failed namespaces:    1d

Nodes
# Number of Zoekt nodes and their status
Node count:                               2 (online: 2, offline: 0)
Last seen at:                             2025-09-15 22:58:09 UTC (less than a minute ago)
Max schema_version:                       2531
Storage reserved / usable:                71.1 MiB / 124 GiB (0.06%)
Storage indexed / reserved:               42.7 MiB / 71.1 MiB (60.0%)
Storage used / total:                     797 GiB / 921 GiB (86.54%)
Online node watermark levels:            2
  - low: 2

Indexing status
Group count:                              8
# Number of enabled namespaces and their status
EnabledNamespace count:                   8 (without indices: 0, rollout blocked: 0, with search disabled: 0)
Replicas count:                           8
  - ready: 8
Indices count:                            8
  - ready: 8
Indices watermark levels:                 8
  - healthy: 8
Repositories count:                       10
  - ready: 10
Tasks count:                              10
  - done: 10
Tasks pending/processing by type:         (none)

Feature Flags (Non-Default Values)
Feature flags:                            none

Feature Flags (Default Values)
- zoekt_cross_namespace_search:           disabled
- zoekt_debug_delete_repo_logging:        disabled
- zoekt_load_balancer:                    disabled
- zoekt_rollout_worker:                   enabled
- zoekt_search_meta_project_ids:          disabled
- zoekt_traversal_id_queries:             disabled

Node Details
Node 1 - test-zoekt-hostname-1:
  Status:                                 Online
  Last seen at:                           2025-09-15 22:58:09 UTC (less than a minute ago)
  Disk utilization:                       86.54%
  Unclaimed storage:                      62 GiB
  # Zoekt build version on the node. Must match GitLab version.
  Zoekt version:                          2025.09.14-v1.4.4-30-g0e7414a
  Schema version:                         2531
Node 2 - test-zoekt-hostname-2:
  Status:                                 Online
  Last seen at:                           2025-09-15 22:58:09 UTC (less than a minute ago)
  Disk utilization:                       86.54%
  Unclaimed storage:                      62 GiB
  Zoekt version:                          2025.09.14-v1.4.4-30-g0e7414a
  Schema version:                         2531

ヘルスチェックの実行

前提要件:

• インスタンスへの管理者アクセス権が必要です。

ヘルスチェックを実行して、以下を含むZoektインフラストラクチャの状態を把握します:

• オンラインおよびオフラインノード
• インデックス作成と検索の設定
• 検索APIエンドポイント
• JSON Webトークンの生成

ヘルスチェックを実行するには、次のタスクを実行します:

gitlab-rake gitlab:zoekt:health

このタスクは以下を提供します:

• 全体的なステータス: HEALTHY、DEGRADED、またはUNHEALTHY
• 検出された問題を解決するための推奨事項
• 自動化とモニタリングインテグレーションの終了コード: 0=healthy、1=degraded、または2=unhealthy

チェックの自動実行

10秒ごとに自動的にヘルスチェックを実行するには、次のタスクを実行します:

gitlab-rake "gitlab:zoekt:health[10]"

出力には色分けされたステータスインジケーターが含まれており、以下が表示されます:

• オンラインおよびオフラインノード数、ストレージ使用量の警告、および接続の問題
• コア設定の検証、ネームスペースとリポジトリのインデックス作成ステータス
• 組み合わせたヘルスチェック評価を含む全体的なステータス: HEALTHY、DEGRADED、またはUNHEALTHY
• 問題を解決するための推奨事項

インデックス作成の一時停止

前提要件:

• インスタンスへの管理者アクセス権が必要です。

完全一致コード検索のインデックス作成を一時停止するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. インデックス作成を一時停止チェックボックスを選択します。
5. 変更を保存を選択します。

完全一致コード検索のインデックス作成を一時停止すると、リポジトリ内のすべての変更がキューに登録されます。インデックス作成を再開するには、完全一致コード検索のインデックス作成を一時停止チェックボックスをオフにします。

ルートネームスペースを自動的にインデックス作成する

前提要件:

• インスタンスへの管理者アクセス権が必要です。

既存および新規のルートネームスペースの両方を自動的にインデックス作成できます。すべてのルートネームスペースを自動的にインデックス作成するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. ルートネームスペースを自動的にインデックス化するチェックボックスを選択します。
5. 変更を保存を選択します。

この設定を有効にすると、GitLabは次のすべてのプロジェクトのインデックス作成タスクを作成します:

• すべてのグループとサブグループ
• 新しいルートネームスペース

プロジェクトがインデックス作成されると、リポジトリの変更が検出された場合にのみ、GitLabは増分インデックス作成を作成します。

この設定を無効にすると:

• 既存のルートネームスペースはインデックス作成されたままになります。
• 新しいルートネームスペースはインデックス作成されなくなります。

検索結果のキャッシュ

前提要件:

• インスタンスへの管理者アクセス権が必要です。

パフォーマンスを向上させるために、検索結果をキャッシュできます。この機能はデフォルトで有効になっており、結果を5分間キャッシュします。

検索結果をキャッシュするには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. Cache search results for five minutes（検索結果を5分間キャッシュする）チェックボックスを選択します。
5. 変更を保存を選択します。

同時インデックス作成タスクの設定

前提要件:

• インスタンスへの管理者アクセス権が必要です。

Zoektノードの同時インデックス作成タスクの数を、そのCPU容量を基準にして設定できます。

乗算が大きいほど、より多くのタスクを同時に実行でき、CPU使用率の増加と引き換えにインデックス作成のスループットが向上します。デフォルト値は1.0（CPUコアあたり1つのタスク）です。

この値は、ノードのパフォーマンスとワークロードに基づいて調整できます。同時インデックス作成タスクの数を設定するには:

1. 左側のサイドバーの下部で、管理者を選択します。

2. 設定 > 検索を選択します。

3. 完全一致コードの検索の設定を展開します。

4. CPUをタスク乗算にインデックスするテキストボックスに値を入力します。

   たとえば、Zoektノードに4個のCPUコアがあり、乗算が1.5の場合、ノードの同時実行タスク数は6です。

5. 変更を保存を選択します。

インデックス作成タスクあたりの並列プロセス数を設定する

前提要件:

• インスタンスへの管理者アクセス権が必要です。

インデックス作成タスクあたりの並列プロセス数を設定できます。

数値を大きくすると、CPUとメモリの使用量が増加する代わりに、インデックス作成時間が短縮されます。デフォルト値は1（インデックス作成タスクあたり1つのプロセス）です。

この値は、ノードのパフォーマンスとワークロードに基づいて調整できます。インデックス作成タスクあたりの並列プロセス数を設定するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. インデックスタスク毎の並列プロセス数テキストボックスに値を入力します。
5. 変更を保存を選択します。

インデックス作成ロールアウトあたりのネームスペース数を設定する

前提要件:

• インスタンスへの管理者アクセス権が必要です。

最初のインデックス作成のために、RolloutWorkerジョブあたりのネームスペースの数を設定できます。デフォルト値は32です。この値は、ノードのパフォーマンスとワークロードに基づいて調整できます。

インデックス作成ロールアウトあたりのネームスペース数を設定するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. インデックスロールアウト毎のネームスペースの数テキストボックスに、ゼロより大きい数値を入力します。
5. 変更を保存を選択します。

オフラインノードを自動的に削除するタイミングを定義する

前提要件:

• インスタンスへの管理者アクセス権が必要です。

オフラインのZoektノードを、関連するインデックス、リポジトリ、およびタスクとともに、特定の時間が経過した後で自動的に削除できます。デフォルト値は12h（12時間）です。

この設定を使用して、Zoektインフラストラクチャを管理し、孤立したリソースを防止します。オフラインノードを自動的に削除するタイミングを定義するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. オフラインノードを削除するまでの時間テキストボックスに値を入力します（例: 30m（30分）、2h（2時間）、1d（1日））。自動削除を無効にするには、0に設定します。
5. 変更を保存を選択します。

プロジェクトのインデックス作成タイムアウトを定義する

前提要件:

• インスタンスへの管理者アクセス権が必要です。

プロジェクトのインデックス作成タイムアウトを定義できます。デフォルト値は30m（30分）です。

プロジェクトのインデックス作成タイムアウトを定義するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. プロジェクトごとのインデックス作成タイムアウトテキストボックスに値を入力します（例: 30m（30分）、2h（2時間）、1d（1日））。
5. 変更を保存を選択します。

インデックス作成されるプロジェクト内のファイルの最大数を設定する

前提要件:

• インスタンスへの管理者アクセス権が必要です。

インデックス作成できるプロジェクト内のファイルの最大数を設定できます。デフォルトのブランチにこの制限を超えるファイルがあるプロジェクトは、インデックス作成されません。

デフォルト値は500,000です。

この値は、ノードのパフォーマンスとワークロードに基づいて調整できます。インデックス作成されるプロジェクト内のファイルの最大数を設定するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. プロジェクトごとにインデックス化されるファイルの最大数テキストボックスに、ゼロより大きい数値を入力します。
5. 変更を保存を選択します。

失敗したネームスペースの再試行間隔を定義する

前提要件:

• インスタンスへの管理者アクセス権が必要です。

以前に失敗したネームスペースの再試行間隔を定義できます。デフォルト値は1d（1日）です。0の値は、失敗したネームスペースが再試行されないことを意味します。

失敗したネームスペースの再試行間隔を定義するには:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > 検索を選択します。
3. 完全一致コードの検索の設定を展開します。
4. 失敗したネームスペースを再試行する間隔テキストボックスに値を入力します（例: 30m（30分）、2h（2時間）、1d（1日））。
5. 変更を保存を選択します。

別のサーバーでZoektを実行する

前提要件:

• インスタンスへの管理者アクセス権が必要です。

GitLabとは異なるサーバーでZoektを実行するには:

1. Gitalyリスニングインターフェースを変更する。
2. Zoektをインストールします。

サイジングの推奨事項

一部のデプロイでは、以下の推奨事項が過剰にプロビジョニングされている可能性があります。次のことを確認するために、デプロイをモニタリングする必要があります:

• メモリ使用量不足イベントが発生しない。
• CPUスロットリングが過度でない。
• インデックス作成のパフォーマンスが要件を満たしている。

次のような特定のワークロード特性に基づいてリソースを調整します:

• リポジトリのサイズと複雑さ
• アクティブなデベロッパーの数
• コード変更の頻度
• インデックス作成パターン

ノード

最適なパフォーマンスを得るには、Zoektノードの適切なサイジングが不可欠です。リソースの割り当て方法と管理方法が異なるため、サイジングの推奨事項はKubernetesとVMデプロイで異なります。

Kubernetesのデプロイ

次の表に、インデックスストレージ要件に基づくKubernetesデプロイの推奨リソースを示します:

リソースをより細かく管理するには、CPUとメモリを別々のコンテナに割り当てることができます。

Kubernetesデプロイの場合:

• ZoektコンテナのCPU制限を設定しないでください。CPU制限により、インデックス作成の急増時に不要なスロットリングが発生し、パフォーマンスに大きな影響を与える可能性があります。代わりに、リソースリクエストに依存して、最小CPU可用性を保証し、利用可能で必要な場合に追加のCPUをコンテナが使用できるようにします。
• 適切なメモリ制限を設定して、リソースの競合とメモリ使用量不足状態を防ぎます。
• より優れたインデックス作成パフォーマンスを得るには、高性能ストレージクラスを使用します。GitLab.comはGCPでpd-balancedを使用しており、パフォーマンスとコストのバランスが取れています。同等のオプションには、AWSのgp3、AzureのPremium_LRSなどがあります。

VMとベアメタルデプロイ

次の表に、インデックスストレージ要件に基づくVMとベアメタルデプロイの推奨リソースを示します:

これらのリソースは、ノード全体にのみ割り当てることができます。

VMおよびベアメタルデプロイの場合:

• CPU、メモリ、およびディスクの使用量をモニタリングして、ボトルネックを特定します。ウェブサーバーとインデクサーのプロセスの両方が、同じCPUとメモリのリソースを共有します。
• より優れたインデックス作成パフォーマンスを得るには、SSDストレージの使用を検討してください。
• GitLabとZoektノード間のデータ転送に十分なネットワーク帯域幅を確保します。

ストレージ

Zoektのストレージ要件は、大規模なバイナリファイル数を含む、リポジトリの特性によって大きく異なります。

開始点として、ZoektストレージがGitalyストレージの半分になると見積もることができます。たとえば、Gitalyストレージが1 TBの場合、Zoektストレージは約500 GB必要になる場合があります。

Zoektノードの使用状況をモニタリングするには、インデックス作成ステータスの確認を参照してください。ディスク容量の不足によりネームスペースがインデックス作成されない場合は、ノードの追加またはスケールアップを検討してください。

セキュリティと認証

Zoektは、GitLab、Zoekt Indexer、Zoekt Webサーバーコンポーネント間の通信を保護するために、多層認証システムを実装しています。認証は、すべての通信チャンネルにわたって適用されます。

すべての認証方式は、GitLab Shellシークレットを使用します。失敗した認証試行は、401 Unauthorizedレスポンスを返します。

Zoekt IndexerからGitLabへ

Zoekt Indexerは、JSON Webトークン（JWT）でGitLabに認証し、インデックス作成タスクを取得し、完了コールバックを送信します。

このメソッドは、署名と検証に.gitlab_shell_secretを使用します。トークンは、Gitlab-Shell-Api-Requestヘッダーで送信されます。エンドポイントは次のとおりです:

• タスクの取得にはGET /internal/search/zoekt/:uuid/heartbeat
• ステータスの更新にはPOST /internal/search/zoekt/:uuid/callback

このメソッドは、Zoekt IndexerノードとGitLab間のタスク配信とステータスレポートの安全なポーリングを保証します。

GitLabからZoekt Webサーバーへ

JWT認証

GitLabは、検索クエリを実行するために、JSON Webトークン（JWT）を使用してZoekt Webサーバーに認証します。JWTトークンは、他のGitLabの認証パターンと一致する、時間制限付きの暗号署名付き認証を提供します。

このメソッドは、Gitlab::Shell.secret_tokenとHS256アルゴリズム（SHA-256を使用したHMAC）を使用します。トークンは、Authorization: Bearer <jwt_token>ヘッダーで送信され、公開を制限するために5分で期限切れになります。

エンドポイントには、/webserver/api/searchと/webserver/api/v2/searchが含まれます。JWTクレームは、発行者（gitlab）と対象者（gitlab-zoekt）です。

基本認証

GitLabは、検索クエリを実行するために、NGINXを介したHTTP基本認証を使用してZoekt Webサーバーに認証します。基本認証は、主にGitLab HelmチャートおよびKubernetesデプロイで使用されます。

この方法では、Kubernetes Secretsで構成されたユーザー名とパスワードを使用します。エンドポイントには、Zoekt Webサーバーの/webserver/api/searchと/webserver/api/v2/searchが含まれます。