• バージョン要件
  • Elasticsearchのバージョン要件
  • OpenSearch のバージョン要件
• システム要件
• Elasticsearch のインストール
• 新しいElasticsearchメジャーバージョンへのアップグレード
• Elasticsearch リポジトリインデクサー
  • ソースからインデクサをインストールします。
    • 依存関係のインストール
      • Debian / Ubuntu
      • CentOS / RHEL
      • macOS
    • ビルドとインストール
  • インデックス作成エラーの表示
• 高度な検索を有効に
  • すべてのプロジェクトをインデックスする設定で有効にします。
  • 高度な検索設定
  • アクセス要件
    • ロール権限を持つElasticsearch
    • きめ細かいアクセス制御が可能な AWS OpenSearch サービス
      • 内部データベースのマスターユーザーとの接続
      • IAM ユーザーでの接続
      • きめ細かいアクセス制御の権限
  • インデックスを作成できるネームスペースとプロジェクトの数を制限します。
• カスタム言語アナライザの有効化
• 詳細検索を無効にします。
• インデックスの一時停止を解除
• ゼロダウンタイム再インデックス
  • ゼロダウンタイム再インデックスの使用
  • 高度な検索の管理画面から再インデックスを開始します。
    • Elasticsearch ゼロダウンタイムリインデックス作成
      • スライス倍率
      • 最大実行スライス数
  • 直近のインデックス再作成ジョブを失敗としてマークし、インデックス作成を再開します。
• インデックスのインテグレーション
• 高度な検索マイグレーション
  • マイグレーション辞書ファイル
  • 保留中のマイグレーションをチェック
  • 停止したマイグレーションを再試行
  • メジャーアップグレードを行う前に、すべてのマイグレーションを完了しておく必要があります。
• GitLab高度な検索のRakeタスク
  • 環境変数
  • プロジェクトの範囲または特定のプロジェクトのインデックスを作成します。
• 高度な検索インデックスのスコープ
• チューニング
  • 最適なクラスター設定の選択に関するガイダンス
  • 高度な検索インテグレーション設定のガイダンス
  • 大規模インスタンスの効率的なインデックス作成方法
  • 削除されたドキュメント
• 専用Sidekiqノードまたはプロセスによる大規模インスタンスのインデックス作成
  • 単一ノード、2プロセス
  • 2つのノード、それぞれに1つのプロセス
• 基本検索に戻す
• データ復旧：Elasticsearch はセカンダリデータストアのみです。

Elasticsearch

この Pages では、高度な検索を有効にする方法を説明します。アドバンストサーチを有効にすると、検索レスポンスが速くなり、検索機能が向上します。

バージョン要件

Elasticsearchのバージョン要件

Elasticsearch 6.8のサポートはGitLab 15.0で削除されました。

高度な検索は以下のバージョンの Elasticsearch で動作します。

Advanced search はElasticsearch のサポート終了ポリシーに従っています。GitLabでElasticsearchのサポートバージョンを変更する場合、削除する前に毎月のリリース投稿のdeprecation noteでアナウンスしています。

OpenSearch のバージョン要件

Elasticsearch や OpenSearch のバージョンに互換性がない場合、データの損失を防ぐためにインデックスの作成が一時停止され、elasticsearch.log ファイルにメッセージが記録されます。

互換性のあるバージョンを使用していて、OpenSearch に接続した後にElasticsearch version not compatibleというメッセージが表示された場合は、インデックスの作成を一時停止します。

システム要件

Elasticsearch には、GitLab のシステム要件に記載されているリソースに加えて、追加のリソースが必要です。

メモリ、CPU、ストレージリソースの量は、Elasticsearchクラスターにインデックスするデータ量によって異なります。Elasticsearchクラスタの使用量が多い場合は、より多くのリソースが必要になる可能性があります。estimate_cluster_size Rakeタスク（GitLab 13.10で導入）は、リポジトリの合計サイズを使用して高度な検索のストレージ要件を見積もります。

Elasticsearch のインストール

Elasticsearch は Linux パッケージやセルフコンパイルによるインストールには含まれていません。別途インストール 、バージョンを選択してください。Elasticsearch のインストール方法の詳細については、このページでは説明しません。

Elasticsearch はご自身でインストールすることもできますし、Elasticsearch Service（AWS、GCP、Azure で利用可能）やAmazon OpenSearchサービスのようなクラウドホスティングを利用することもできます。

Elasticsearch は別のサーバにインストールしてください。GitLabと同じサーバーでElasticsearchを実行することは推奨されておらず、GitLabインスタンスのパフォーマンスを低下させる可能性があります。

シングルノードのElasticsearchクラスタでは、プライマリシャードの割り当てのため、機能的なクラスタのヘルスステータスは常に黄色です。Elasticsearchはレプリカシャードをプライマリシャードと同じノードに割り当てることはできません。

検索インデックスが更新されます：

• データベースまたはリポジトリにデータを追加します。
• 管理エリアでElasticsearch を有効にします。

新しいElasticsearchメジャーバージョンへのアップグレード

• Elasticsearch 6.8 のサポートは GitLab 15.0 で終了しました。
• GitLab 14.10から15.0にアップグレードするには、Elasticsearch 7.xのいずれかのバージョンを使用している必要があります。

Elasticsearchをアップグレードする際にGitLabの設定を変更する必要はありません。

Elasticsearch リポジトリインデクサー

Git リポジトリのデータをインデックスするために、GitLab ではGo で書かれたインデクサを使用しています。

GitLab のバージョンによって、Go インデクサーのインストール手順は異なります：

• Linux パッケージのインストールの場合、Go インデクサーは含まれています。
• セルフコンパイルによるインストールの場合は、ソースからのインデクサのインストールを参照してください。
• GitLab Development Kit を使用している場合は、GDK の Elasticsearch を参照してください。
• GitLab 11.10以降のHelmデプロイを実行している場合、インデクサはすでに含まれています。

ソースからインデクサをインストールします。

まずいくつかの依存関係をインストールし、それからインデクサ自体をビルドしてインストールします。

依存関係のインストール

こ のプ ロ ジ ェ ク ト はテ キ ス ト エン コ ーデ ィ ン グのためにInternational Components for Unicode (ICU) に依存 し てい ますので、make を実行す る 前に、 お使いのプ ラ ッ ト フ ォーム用の開発パ ッ ケージがインス トール さ れてい る こ と を確認す る 必要があ り ます。

Debian / Ubuntu

Debian または Ubuntu にインストールするには、以下を実行してください：

sudo apt install libicu-dev

CentOS / RHEL

CentOS または RHEL にインストールするには、次のコマンドを実行します：

sudo yum install libicu-devel

macOS

MacOSにインストールするには、以下を実行してください：

brew install icu4c
export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig:$PKG_CONFIG_PATH"

ビルドとインストール

インデクサをビルドしてインストールするには、以下を実行します：

indexer_path=/home/git/gitlab-elasticsearch-indexer

# Run the installation task for gitlab-elasticsearch-indexer:
sudo -u git -H bundle exec rake gitlab:indexer:install[$indexer_path] RAILS_ENV=production
cd $indexer_path && sudo make install

gitlab-elasticsearch-indexer は/usr/local/bin にインストールされます。

PREFIX 環境変数でインストールパスを変更できます。その際はsudo に-E フラグを渡すことを忘れないでください。

使用例：

PREFIX=/usr sudo -E make install

インストール後、必ずElasticsearchを有効にしてください。

インデックス作成エラーの表示

GitLab Elasticsearch Indexerからのエラーは、elasticsearch.log ファイルとsidekiq.log ファイルのjson.exception.class がGitlab::Elastic::Indexer::Errorで報告されます。これらのエラーは Git リポジトリデータのインデックス作成時に発生する可能性があります。

高度な検索を有効に

前提条件

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

高度な検索を有効にするには

1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
2. Admin Areaを選択します。

3. 左サイドバーで「設定」>「高度な検索」を選択します。

   Advanced Searchセクションを表示するには、有効なGitLab Premiumライセンスが必要です。
4. Elasticsearchクラスターの高度な検索設定を行います。Search with Elasticsearch enabledチェックボックスはまだ選択しないでください。

5. Rake タスクで全データのインデックスを作成します。このタスクは、インデックスがまだ存在しない場合は空のインデックスを作成し、インデックスがまだ有効になっていない場合は Elasticsearch のインデックスを有効にします：

   # WARNING: THIS WILL DELETE ALL EXISTING INDICES
   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:index
      
   # WARNING: THIS WILL DELETE ALL EXISTING INDICES
   # Installations from source
   bundle exec rake gitlab:elastic:index RAILS_ENV=production
   

6. オプション。バックグラウンドジョブのステータスを監視します。
   1. 左サイドバーで、[監視] > [バックグラウンドジョブ]を選択します。
   2. Sidekiqダッシュボードで、[Queues]を選択し、elastic_commit_indexer およびelastic_wiki_indexer キューが0 に下がるのを待ちます。これらのキューには、グループおよびプロジェクトのコードおよびWikiデータのインデックスを作成するジョブが含まれています。
7. インデックス作成が完了したら、Elasticsearchを有効にして検索するチェックボックスを選択し、変更を保存を選択します。

リポジトリデータが 50 GB を超える GitLab インスタンスについては、大規模インスタンスに効率的にインデックスを作成する方法を参照してください。

すべてのプロジェクトをインデックスする設定で有効にします。

すべてのプ ロ ジ ェ ク ト を イ ンデ ッ ク ス」 設定を使用で き る のは、 イ ンデ ッ ク ス を初期作成す る と き のみであ り 、 イ ンデ ッ ク ス を ま っ た く 再作成す る と き には使用で き ません。すべてのプロジェクトをインデックス] を使用して高度な検索を有効にするには、次の手順に従います：

1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
2. Admin Areaを選択します。
3. 左サイドバーで「設定」>「高度な検索」を選択します。
4. Elasticsearch indexingチェックボックスを選択し、Save changesを選択します。
5. Index all projectsを選択します。
6. オプション。バックグラウンドジョブのステータスを確認するには、[進行状況を確認する] を選択します。

エピック、グループ Wiki、個人スニペット、ユーザーのインデックスを作成するには、Rake タスクを使用する必要があります：

# Omnibus installations
sudo gitlab-rake gitlab:elastic:index_epics
sudo gitlab-rake gitlab:elastic:index_group_wikis
sudo gitlab-rake gitlab:elastic:index_snippets
sudo gitlab-rake gitlab:elastic:index_users

# Installations from source
bundle exec rake gitlab:elastic:index_epics RAILS_ENV=production
bundle exec rake gitlab:elastic:index_group_wikis RAILS_ENV=production
bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production
bundle exec rake gitlab:elastic:index_users RAILS_ENV=production

高度な検索設定

以下のElasticsearchの設定が可能です：

アクセス要件

ロール権限を持つElasticsearch

GitLabがElasticsearchにアクセスしてオペレーションを実行するには、以下の権限を持つロールが必要です：

{
  "cluster": ["monitor"],
  "indices": [
    {
      "names": ["gitlab-*"],
      "privileges": [
        "create_index",
        "delete_index",
        "view_index_metadata",
        "read",
        "manage",
        "write"
      ]
    }
  ]
}

詳細はElasticsearch のセキュリティ権限をご覧ください。

きめ細かいアクセス制御が可能な AWS OpenSearch サービス

GitLab できめ細かいアクセス制御を使ってセルフマネージドな AWS OpenSearch Service を使うには、推奨される設定の一つを試してみてください。

インスタンスのドメイン・アクセス・ポリシーを設定して、es:ESHttp* アクションを許可します。以下の設定例をカスタマイズして、プリンシパルまたはリソースを制限できます：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "*"
        ]
      },
      "Action": [
        "es:ESHttp*"
      ],
      "Resource": "domain-arn/*"
    }
  ]
}

詳細については、Amazon OpenSearch Service の Identity and Access Management を参照してください。

内部データベースのマスターユーザーとの接続

内部データベースのユーザを使ってきめ細かいアクセス制御を行う場合、OpenSearch への接続には HTTP 基本認証を使用する必要があります。マスターユーザ名とパスワードは、OpenSearch の URL の一部として、あるいは詳細検索設定のユーザ名と パスワードのテキストボックスで指定できます。チュートリアルを参照してください：詳しくは、チュートリアル:内部ユーザーデータベースと HTTP 基本認証をご覧ください。

IAM ユーザーでの接続

IAM 認証情報によるきめ細かなアクセス制御を使用する場合、詳細検索設定のAWS OpenSearch IAM 認証情報セクションで認証情報を提供できます。

きめ細かいアクセス制御の権限

詳細検索には以下の権限が必要です。詳細はロールの作成を参照してください。

{
  "cluster_permissions": [
    "cluster_composite_ops",
    "cluster_monitor"
  ],
  "index_permissions": [
    {
      "index_patterns": [
        "gitlab*"
      ],
      "allowed_actions": [
        "data_access",
        "manage_aliases",
        "search",
        "create_index",
        "delete",
        "manage"
      ]
    },
    {
      "index_patterns": [
        "*"
      ],
      "allowed_actions": [
        "indices:admin/aliases/get",
        "indices:monitor/stats"
      ]
    }
  ]
}

インデックスパターン* 、高度な検索を行うにはいくつかの権限が必要です。

インデックスを作成できるネームスペースとプロジェクトの数を制限します。

インデックスを作成できるネームスペースとプロジェクトの数を制限する] チェックボックスをオンにすると、 インデックスに作成するネームスペースとプロジェクトを指定できます。ネームスペースがグループの場合は、サブグループとそのサブグループに属するプロジェクトもインデックス化されま す。

高度な検索では、すべてのネームスペースがインデックス化されている場合にのみ、グループ横断のコード/コミット検索（グローバル検索）が行われます。名前空間のサブセットのみがインデックス化されているこの特殊なシナリオでは、グローバル検索ではコードやコミットのスコープは提供されません。これは、インデックス付けされたネームスペースのスコープでのみ可能です。インデックスが作成された複数のネームスペースで (ネームスペースのサブセットのみがインデックス化されている場合) 検索をコード化/コミットする方法はありません。例えば、2 つのグループがインデックス化されている場合、両方のグループに対して 1 つのコード検索を実行する方法はありません。最初のグループでコード検索を実行し、次に 2 番目のグループで実行することしかできません。

選択ドロップダウン・リストをフィルタリングするには、関心のあるネームスペースまたはプロジェクト名の一部を記述します。

カスタム言語アナライザの有効化

Elasticのsmartcn および/またはkuromoji 分析プラグインを利用することで、中国語と日本語の言語サポートを向上させることができます。

言語サポートを有効にするには

1. プラグインのインストール手順についてはElasticsearch のドキュメントを参照してください。プラグインはクラスター内のすべてのノードにインストールする必要があり、インストール後に各ノードを再起動する必要があります。プラグインのリストについては、このセクションの後の表を参照してください。
2. 左のサイドバーで、Search を選択するか、次のページに進んでください。
3. Admin Areaを選択します。
4. 左サイドバーで「設定」>「高度な検索」を選択します。
5. カスタムアナライザー：言語サポート]を選択します。
6. プラグインによるインデックスのサポートを有効にします。
7. 変更を有効にするには、[Save changes]を選択します。
8. ゼロ・ダウンタイム再インデックス作成をトリガするか、すべてをゼロから再インデックス作成して、更新されたマッピングで新しいインデックスを作成します。
9. 前のステップが完了した後に、検索用のプラグインのサポートを有効にします。

何をインストールするかについては、以下のElasticsearch言語プラグインオプションを参照してください：

詳細検索を無効にします。

Elasticsearchインテグレーションを無効にします：

1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
2. Admin Areaを選択します。
3. 左サイドバーで「設定」>「高度な検索」を選択します。
4. Elasticsearch indexingと Search with Elasticsearch enabledのチェックボックスをオフにします。
5. 変更を保存を選択します。

6. オプションです。オンライン状態の Elasticsearch インスタンスについては、既存のインデックスを削除します：

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:delete_index
      
   # Installations from source
   bundle exec rake gitlab:elastic:delete_index RAILS_ENV=production
   

インデックスの一時停止を解除

1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
2. Admin Areaを選択します。
3. 左サイドバーで「設定」>「高度な検索」を選択します。
4. 詳細検索を展開します。
5. Elasticsearch インデックス作成を一時停止する] チェックボックスをオフにします。

ゼロダウンタイム再インデックス

このインデックスの再作成方法の背後にあるアイデアは、Elasticsearch reindex APIと Elasticsearch index alias 機能を活用してオペレーションを実行することです。primary GitLabが読み書きするインデックスに primary接続するインデックスエイリアスを設定します。primary インデックスの再作成が始まったら primary、primary インデックスへの書き込みを一時停止 primaryします。それから別のインデックスを作成し、インデックスデータを新しいインデックスにマイグレーションする Reindex API を呼び出します。インデックス再作成ジョブが完了したら、インデックスエイリアスを新しいprimary インデックスに接続することで、新しいインデックスに切り替えます。最後に、書き込みを再開し、通常のオペレーションを再開します。

ゼロダウンタイム再インデックスの使用

新しいインデックスを作成し、既存のデータをコピーしなければ変更できないインデックス設定やマッピングを構成するために、ゼロダウンタイム再インデックスを使用することができます。ゼロ-ダウンタイム再インデックスは、欠落したデータを修正するために使用すべきではありません。データがまだインデックス化されていない場合、To-Doime reindexing はデータを検索クラスターに追加しません。インデックス再作成を開始する前に、すべての高度な検索マイグレーションを完了する必要があります。

高度な検索の管理画面から再インデックスを開始します。

• GitLab 13.2 で導入されました。
• GitLab 13.3でインデックスのスケジュール削除とキャンセル機能が導入されました。
• GitLab 13.12でインデックス再作成時のリトライがサポートされました。

インデックス再作成プロセスを起動するには

1. GitLab インスタンスに管理者としてサインインしてください。
2. 左のサイドバーで、Search を選択するか、次のページに進んでください。
3. Admin Areaを選択します。
4. 左サイドバーで「設定」>「高度な検索」を選択します。
5. Elasticsearch zero-downtime reindexingを展開します。
6. Trigger cluster reindexing を選択します。

Elasticsearch クラスタの規模によっては、インデックス再作成に時間がかかることがあります。

この処理が完了すると、元のインデックスは14日後に削除されるようにスケジュールされます。このアクションをキャンセルするには、再インデックス作成プロセスをトリガーしたページでキャンセルボタンを押します。

インデックスの再作成が実行されている間は、同じセクションで進行状況を確認することができます。

Elasticsearch ゼロダウンタイムリインデックス作成

GitLab 13.12 で導入されました。

1. 左のサイドバーで、Search を選択するか、次のページに進んでください。
2. Admin Areaを選択します。
3. 左サイドバーで「設定」>「高度な検索」を選択します。
4. Elasticsearch zero-downtime reindexingを展開すると、以下のオプションがあります：

• スライス倍率
• 最大実行スライス数

スライス倍率

スライス倍率は、再インデックス作成時のスライス数を計算します。

GitLabは効率的かつ安全に再インデックスを制御するために手動スライスを使用しており、ユーザーは失敗したスライスのみを再試行することができます。

乗数はデフォルトで2 インデックスあたりのシャード数に適用さ 2れます。例えば、2 この 2値がインデックスのシャード数が20の場合、再インデックスタスクは40のスライスに分割されます。

最大実行スライス数

maximum running slices パラメータのデフォルトは60 で、Elasticsearch の再インデックス時に同時に実行できるスライスの最大数に対応します。

この値を高く設定しすぎると、クラスターが検索と書き込みで激しく飽和するため、パフォーマンスに悪影響を及ぼす可能性があります。この値を低く設定しすぎると、再インデックス処理が完了するまでに非常に長い時間を要することになります。

この値の最適値は、クラスター・サイズ、再インデックス時の検索性能の低下を許容できるかどうか、再インデックスを迅速に終了してインデックス作成を再開することがどの程度重要であるかによって決まります。

直近のインデックス再作成ジョブを失敗としてマークし、インデックス作成を再開します。

未完了のインデックス再作成ジョブを破棄してインデックス作成を再開したい場合があります。これは以下の手順で実現できます：

1. 直近のインデックス再作成ジョブを失敗とマークします：

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:mark_reindex_failed
      
   # Installations from source
   bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production
   

2. 左のサイドバーで、Search を選択するか、次のページに進んでください。
3. Admin Areaを選択します。
4. 左サイドバーで「設定」>「高度な検索」を選択します。
5. 詳細検索を展開します。
6. Elasticsearch インデックス作成を一時停止する] チェックボックスをオフにします。

インデックスのインテグレーション

• GitLab 15.10からsearch_index_integrity というフラグで導入されました。デフォルトでは無効です。
• GitLab 16.0でGitLab.comで有効に。
• GitLab 16.3でセルフマネージドで有効化。

フラグ: セルフマネジメントのGitLabでは、デフォルトでこの機能が利用可能です。この機能を隠すには、管理者がsearch_index_integrity という機能フラグを無効にします。GitLab.comでは、この機能は利用可能です。

インデックスの整合性は、リポジトリデータの欠落を検出して修正します。この機能は、グループやプロジェクトをスコープとしたコード検索が結果を返さない場合に自動的に使用されます。

高度な検索マイグレーション

GitLab 13.6で導入されました。

再インデックスマイグレーションはバックグラウンドで実行されるため、手動で操作する必要はありません。これは通常、高度な検索に新しい機能が追加された場合に起こります。

マイグレーション辞書ファイル

GitLab 16.3 で導入されました。

すべてのマイグレーションは、ee/elastic/docs/ フォルダに以下の情報を持つ対応する辞書ファイルを持ちます：

name:
version:
description:
group:
milestone:
introduced_by_url:
obsolete:
marked_obsolete_by_url:
marked_obsolete_in_milestone:

この情報は、例えば、マイグレーションがいつ導入されたのか、またはいつ廃止されたのかを特定するために使用することができます。

保留中のマイグレーションをチェック

保留中の高度な検索マイグレーションをチェックするには、次のコマンドを実行します：

curl "$CLUSTER_URL/gitlab-production-migrations/_search?q=*" | jq .

このコマンドは次のようなものを返すはずです：

{
  "took": 14,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "gitlab-production-migrations",
        "_type": "_doc",
        "_id": "20201105181100",
        "_score": 1,
        "_source": {
          "completed": true
        }
      }
    ]
  }
}

マイグレーションに関するイシューをデバッグするには、elasticsearch.log ファイルをチェックしてください。

停止したマイグレーションを再試行

マイグレーションには再試行回数が設定されているものがあります。マイグレーションがリトライ制限内に終了できない場合、マイグレーションは停止され、詳細検索インテグレーション設定に通知が表示されます。elasticsearch.log ファイル をチェックしてマイグレーションが停止した原因をデバッグし、マイグレーションを再試行する前に変更を加えることをお勧めします。失敗の原因が修正されたと確信したら、”マイグレーションを再試行 “を選択します。

マイグレーションを成功させることができない場合、インデックスをゼロから再作成するという最後の手段を検討することができます。新しく作成されたインデックスは、正しい最新のスキーマで再作成されるため、すべてのマイグレーションをスキップすることができます。

メジャーアップグレードを行う前に、すべてのマイグレーションを完了しておく必要があります。

GitLabのメジャーバージョンにアップグレードする前に、そのメジャーバージョンの前の最新のマイナーバージョンまでに存在するマイグレーションをすべて完了させる必要があります。また、メジャーバージョンへのアップグレードを進める前に、停止しているマイグレーションを解決して再試行する必要があります。詳しくは、新しいメジャーバージョンへのアップグレードをご覧ください。

削除されたマイグレーションは廃止されたものとしてマークされます。保留中の高度な検索マイグレーションがすべて完了する前に GitLab をアップグレードした場合、新しいバージョンで削除された保留中のマイグレーションは実行も再試行もできません。この場合、インデックスを一から作成し直す必要があります。

GitLab高度な検索のRakeタスク

Rakeタスクは以下の用途で利用できます：

• インデクサのビルドとインストール。
• Elasticsearch を無効にする際にインデックスを削除します。
• GitLab データをインデックスに追加します。

以下は利用可能なRakeタスクです：

環境変数

Rakeタスクに加えて、プロセスを変更するために使用できる環境変数がいくつかあります：

プロジェクトの範囲または特定のプロジェクトのインデックスを作成します。

ID_FROM とID_TO 環境変数を使えば、 限定数のプ ロ ジ ェ ク ト を イ ンデ ッ ク スす る こ と がで き ます。これはインデックスのステージングに便利です。

root@git:~# sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1 ID_TO=100

ID_FROM とID_TO はor equal to 比較を使用するので、両方を同じプロジェクトIDに設定することで、1つのプロジェクトだけをインデックス化するために使用することができます：

root@git:~# sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=5 ID_TO=5
Indexing project repositories...I, [2019-03-04T21:27:03.083410 #3384]  INFO -- : Indexing GitLab User / test (ID=33)...
I, [2019-03-04T21:27:05.215266 #3384]  INFO -- : Indexing GitLab User / test (ID=33) is done!

高度な検索インデックスのスコープ

検索を行う際、GitLabインデックスは以下のスコープを使用します：

チューニング

最適なクラスター設定の選択に関するガイダンス

クラスター設定の選択に関する基本的なガイダンスについては、Elastic Cloud Calculatorをご参照ください。詳細は以下をご覧ください。

• 一般的には、少なくとも2ノードクラスタ構成でレプリカを1台用意し、耐障害性を確保することをお勧めします。ストレージの使用量が急増している場合は、事前に水平スケーリング（ノードの追加）を計画するとよいでしょう。
• 検索クラスターでHDDストレージを使用することは推奨されません。SSDストレージ（NVMeまたはSATA SSDドライブなど）を使用する方がよいでしょう。
• 大規模インスタンスで調整専用ノードを使用すべきではありません。調整専用ノードはデータノードよりも小さいため、パフォーマンスや高度な検索マイグレーションに影響を与える可能性があります。
• GitLab Performance Toolを使って、異なる検索クラスターのサイズと設定で検索パフォーマンスをベンチマークすることができます。
• Heap size を物理RAMの50%以下に設定する必要があります。さらに、ゼロベースで圧縮された oops のしきい値以上には設定しないでください。正確な閾値はさまざまですが、ほとんどのシステムでは26 GBが安全ですが、システムによっては30 GBにもなることがあります。詳細については、「ヒープ・サイズの設定」と「JVMオプションの設定」を参照してください。
• ノードあたりのCPU数（CPUコア数）は、通常、後述のNumber of Elasticsearch shards の設定に対応します。
• 良いガイドラインは、ノードあたりのシャード数を、設定したGBヒープあたり20以下に保つようにすることです。したがって、30GBのヒープを持つノードは最大600シャードを持つべきですが、この制限を下回れば下回るほど良くなります。これは一般的にクラスターを健全に保つのに役立ちます。
• Elasticsearch シャードの数
  • シャードが小さいとセグメントが小さくなり、オーバーヘッドが増加します。平均シャードサイズは少なくとも数GBから数十GBの間を保つようにしましょう。
  • もう一つの考慮点は、ドキュメントの数です。使用するシャードの数を決めるには、管理エリアの「ダッシュボード」>「統計」にある数値（インデックスを作成する文書の数）を合計し、500万で割って5を足します：
    • 文書数が約200万未満の場合は、デフォルトの5シャードを使用します。
    • 10,000,000 ドキュメント:10000000/5000000 + 5 = 7 シャード
    • 100,000,000 ドキュメント：100000000/5000000 + 5 = 25 シャード
• refresh_interval はインデックスごとの設定です。リアルタイムでデータを必要としない場合は、デフォルトの1s から大きな値に調整するとよいでしょう。これによって、新鮮な結果がどのくらい早く表示されるかが変わります。それが重要な場合は、できるだけデフォルトに近い値にしておくとよいでしょう。
• インデックス作成オペレーションが多い場合は、indices.memory.index_buffer_size を 30% や 40% に上げるとよいでしょう。

高度な検索インテグレーション設定のガイダンス

• Number of Elasticsearch shards の設定は通常、クラスターで利用可能なCPU数に対応します。たとえば、3 ノードのクラスタでそれぞれ 4 コアを使用している場合、クラスタ内に少なくとも 3*4=12 個のシャードがあると便利です。シャード数を変更するには、Split index API を使用するか、シャード数を変更した別のインデックスに再インデックスする必要があります。
• ほとんどの場合、Number of Elasticsearch replicas の設定は1 (各シャードには1つのレプリカがあります) と同じにする必要があります。ノードを1つ失うとインデックスが壊れてしまうので、0 の使用は推奨されません。

大規模インスタンスの効率的なインデックス作成方法

このセクションは、インデックスを作成するデータの量が多いために、他の基本的な手順で問題が発生した場合に役立ちます。

1. Elasticsearchのホストとポートを設定します。

2. 空のインデックスを作成します：

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:create_empty_index
      
   # Installations from source
   bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production
   

3. GitLabインスタンスの再インデックスであれば、インデックスのステータスをクリアします：

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:clear_index_status
      
   # Installations from source
   bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production
   

4. Elasticsearch indexingチェックボックスを選択します。

5. 大きな Git リポジトリのインデックス作成には時間がかかることがあります。処理を高速化するには、インデックス作成速度をチューニングします：

   • refresh を一時的に無効にすることができます。これは、インデックスへの変更を検索できるようにするオペレーションです。

   • この設定は、インデックスの各プライマリシャードが持つコピーの数を制御します。したがって、レプリカ数を0にすると、ノード間でのシャードの複製が事実上無効になります。これは信頼性とクエリ・パフォーマンスの点で重要なトレードオフです。最初のインデックス作成が完了したら、レプリカを考慮した値に設定することを忘れないようにすることが重要です。

   私たちの経験では、インデックス作成時間が20%減少することが期待できます。後のステップでインデックス作成を完了した後、refresh とnumber_of_replicas を希望する設定に戻すことができます。

   こ の ス テ ッ プはオプシ ョ ンですが、 大規模な イ ンデ ッ ク ス作 成オペレーシ ョ ン を大幅に速めるのに役立つ可能性があ り ます。

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "index" : {
              "refresh_interval" : "-1",
              "number_of_replicas" : 0
          } }'
   

6. プロジェクトとその関連データをインデックス化します：

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:index_projects
      
   # Installations from source
   bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production
   

   インデックスを作成する必要があるプロジェクトごとに、Sidekiqジョブをキューに入れます。管理エリアのMonitoring > Background Jobs > Queues Tabでジョブを表示し、elastic_commit_indexer を選択するか、Rakeタスクを使用してインデックス作成ステータスを照会できます：

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:index_projects_status
      
   # Installations from source
   bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production
      
   Indexing is 65.55% complete (6555/10000 projects)
   

   インデックスをプロジェクトの範囲に制限したい場合は、ID_FROM とID_TO パラメータを指定できます：

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000
      
   # Installations from source
   bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production
   

   ID_FROM とID_TO はプロジェクトIDです。両パラメータとも省略可能です。上記の例では、ID1001 から ID2000までの（およびそれを含む）すべてのプロジェクトにインデックスを作成します。

   gitlab:elastic:index_projects によってキューに入れられたプロジェクトのインデックス作成ジョブが中断されることがあります。これはさまざまな理由で起こりますが、インデックス作成タスクを再度実行することは常に安全です。

   また、gitlab:elastic:clear_index_status Rake タスクを使用して、インデクサにすべての進捗を「忘れさせる」ことができます。

7. エピック、グループWiki、個人スニペット、ユーザーはプロジェクトと関連付けられていないため、個別にインデックスを作成する必要があります：

   # Omnibus installations
   sudo gitlab-rake gitlab:elastic:index_epics
   sudo gitlab-rake gitlab:elastic:index_group_wikis
   sudo gitlab-rake gitlab:elastic:index_snippets
   sudo gitlab-rake gitlab:elastic:index_users
      
   # Installations from source
   bundle exec rake gitlab:elastic:index_epics RAILS_ENV=production
   bundle exec rake gitlab:elastic:index_group_wikis RAILS_ENV=production
   bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production
   bundle exec rake gitlab:elastic:index_users RAILS_ENV=production
   

8. インデックス作成後、レプリケーションとリフレッシュを再度有効にしてください（以前に無効にしていた場合のみ）：

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "index" : {
              "number_of_replicas" : 1,
              "refresh_interval" : "1s"
          } }'
   

   上記のリフレッシュを有効にした後、強制マージが呼び出されなければなりません。

   Elasticsearch 6.x の場合、強制マージを行う前にインデックスを読み取り専用モードにする必要があります：

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "settings": {
            "index.blocks.write": true
          } }'
   

   その後、強制マージを開始します：

   curl --request POST 'localhost:9200/gitlab-production/_forcemerge?max_num_segments=5'
   

   この後、インデックスが読み取り専用モードになっている場合は、読み取り/書き込みモードに戻してください：

   curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' \
        --data '{
          "settings": {
            "index.blocks.write": false
          } }'
   

9. インデックスの作成が完了したら、Elasticsearchを有効にして検索するチェックボックスを選択します。

削除されたドキュメント

インデックス化された GitLab オブジェクトに変更や削除が行われるたびに (マージリクエストの記述が変更されたり、リポジトリ内のデフォルトブランチからファイルが削除されたり、プロジェクトが削除されたりなど)、インデックス内のドキュメントが削除されます。しかし、これらは「ソフト」な削除であるため、「削除されたドキュメント」の全体数、つまり無駄なスペースが増えてしまいます。Elasticsearch は、このような削除されたドキュメントを削除するために、セグメントをインテリジェントにマージします。しかし、GitLabインストールにおけるアクティビティの量や種類によっては、インデックスに50%もの無駄な領域が発生する可能性があります。

一般的には、デフォルトの設定で Elasticsearch にマージと再利用を自動的に行わせることをお勧めします。Lucene’s Handling of Deleted DocumentsLucene より、“内部的には、おそらく最大セグメントサイズを小さくする以外に、Luceneのデフォルトのままにしておくのが最善であり、削除がいつ取り戻されるかについてはあまり気にしない方がよいでしょう。”

しかし、大規模なインストールではマージポリシーの設定を調整したほうがよい場合もあります：

• index.merge.policy.max_merged_segment のサイズをデフォルトの 5 GB から 2 GB または 3 GB に減らすことを検討してください。マージは、セグメントに少なくとも 50% の削除がある場合にのみ行われます。セグメントサイズを小さくすると、マージがより頻繁に行われるようになります。

   curl --request PUT localhost:9200/gitlab-production/_settings ---header 'Content-Type: application/json' \
        --data '{
          "index" : {
            "merge.policy.max_merged_segment": "2gb"
          }
        }'
  

• また、index.merge.policy.reclaim_deletes_weight を調整することで、どの程度積極的に削除を行うかを制御できます。しかし、これはコストのかかるマージ決定につながる可能性があるため、トレードオフを理解しない限りは変更しないことをお勧めします。

   curl --request PUT localhost:9200/gitlab-production/_settings ---header 'Content-Type: application/json' \
        --data '{
          "index" : {
            "merge.policy.reclaim_deletes_weight": "3.0"
          }
        }'
  

• 強制マージ によると、これは非常に大きなセグメントを作成することになり、そのセグメントは再利用されない可能性があります。

専用Sidekiqノードまたはプロセスによる大規模インスタンスのインデックス作成

大規模なインスタンスのインデックス作成は、Sidekiqノードとプロセスを圧倒する可能性を持つ、長くてリソース集約的なプロセスになる可能性があります。これはGitLabのパフォーマンスと可用性に悪影響を及ぼします。

GitLabでは複数のSidekiqプロセスを起動することができるので、キューセット（またはキューグループ）のインデックス作成専用の追加プロセスを作成することができます。こうすることで、インデックスを作成するキューには常に専用のワーカーを配置し、残りのキューには別の専用のワーカーを配置して競合を避けることができます。

この目的のためには、Sidekiqがワーカーと一致するクエリに基づいて特定のキューにジョブをルーティングするルーティングルールオプションを使用します。

これを処理するには、一般的に以下の2つのオプションのいずれかをお勧めします。どちらかです：

• 一つのノード上で二つのキューグループを使用します。
• 各ノードに1つずつ、2つのキューグループを使用します。

以下のステップでは、sidekiq['routing_rules'] のエントリを考えてみます：

• ["feature_category=global_search", "global_search"] のエントリを考えてください。すべてのインデックス作成ジョブはglobal_search キューにルーティングされます。
• ["*", "default"] 他のすべてのインデックス作成以外のジョブはdefault キューにルーティングされます。

sidekiq['queue_groups'] の少なくとも一つのプロセスはmailers キューを含んでいなければなりません。そうでなければ、メーラのジョブはまったく処理されません。

単一ノード、2プロセス

インデックスを作成するSidekiqプロセスとインデックスを作成しないSidekiqプロセスを1つのノードに作成します：

1. Sidekiqノードで、/etc/gitlab/gitlab.rb ：

   sidekiq['enable'] = true
   sidekiq['queue_selector'] = false
      
   sidekiq['routing_rules'] = [
      ["feature_category=global_search", "global_search"],
      ["*", "default"],
   ]
      
   sidekiq['queue_groups'] = [
      "global_search", # process that listens to global_search queue
      "default,mailers" # process that listens to default and mailers queue
   ]
      
   sidekiq['min_concurrency'] = 20
   sidekiq['max_concurrency'] = 20
   

2. ファイルを保存し、変更を有効にするためにGitLab を再設定してください。

2つのノード、それぞれに1つのプロセス

これらのキューグループを2つのノードで処理する場合：

1. インデックス作成Sidekiqプロセスをセットアップするには、インデックス作成Sidekiqノードで、/etc/gitlab/gitlab.rb ファイルを次のように変更します：

   sidekiq['enable'] = true
   sidekiq['queue_selector'] = false
      
   sidekiq['routing_rules'] = [
      ["feature_category=global_search", "global_search"],
      ["*", "default"],
   ]
      
   sidekiq['queue_groups'] = [
     "global_search", # process that listens to global_search queue
   ]
      
   sidekiq['min_concurrency'] = 20
   sidekiq['max_concurrency'] = 20
   

2. ファイルを保存し、変更を有効にするためにGitLab を再設定してください。

3. 非インデックス化Sidekiqプロセスを設定するには、非インデックス化Sidekiqノードで/etc/gitlab/gitlab.rb ：

   sidekiq['enable'] = true
   sidekiq['routing_rules'] = [
      ["feature_category=global_search", "global_search"],
      ["*", "default"],
   ]
      
   sidekiq['queue_groups'] = [
      "default,mailers" # process that listens to default and mailers queue
   ]
      
   sidekiq['min_concurrency'] = 20
   sidekiq['max_concurrency'] = 20
   

   に変更して、非インデックス化Sidekiqプロセスを設定します。

4. ファイルを保存し、変更を有効にするためにGitLab を再設定してください。

基本検索に戻す

Elasticsearchのインデックスデータにイシューが発生することがあります。そのため、GitLabでは検索結果がない場合に、そのスコープで基本検索がサポートされていると仮定して、”基本検索 “に戻すことができます。この “基本検索 “は、インスタンスで高度な検索を全く有効にしておらず、他のデータソース（PostgreSQLデータやGitデータなど）を使って検索しているかのように振る舞います。

データ復旧：Elasticsearch はセカンダリデータストアのみです。

GitLabにおけるElasticsearchの使用はセカンダリデータストアとしてのみです。つまり、Elasticsearchに保存されたデータはすべて、他のデータソース、具体的にはPostgreSQLやGitalyから常に再導出することができます。そのため、何らかの理由でElasticsearchのデータストアが破損した場合でも、ゼロからインデックスを作成し直すことができます。