Elasticsearch

{{< details >}}

• Édition : GitLab Premium, GitLab Ultimate
• Offre : GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

Cette page décrit comment activer la recherche avancée. Une fois activée, la recherche avancée offre des temps de réponse plus rapides et des fonctionnalités de recherche améliorées.

Pour activer la recherche avancée, vous devez :

1. Installer un cluster Elasticsearch ou AWS OpenSearch.
2. Activer la recherche avancée.

[!note] La recherche avancée stocke tous les projets dans les mêmes indices Elasticsearch. Cependant, les projets privés n'apparaissent dans les résultats de recherche qu'aux utilisateurs qui y ont accès.

Glossaire Elasticsearch {#elasticsearch-glossary}

Ce glossaire fournit des définitions pour les termes liés à Elasticsearch.

• Lucene : une bibliothèque de recherche en texte intégral écrite en Java.
• Near real time (NRT) : désigne la légère latence entre le moment d'indexation d'un document et le moment où il devient consultable.
• Cluster : un ensemble d'un ou plusieurs nœuds qui travaillent ensemble pour stocker toutes les données, offrant des capacités d'indexation et de recherche.
• Node : un serveur unique fonctionnant dans le cadre d'un cluster.
• Indexer : un ensemble de documents présentant des caractéristiques relativement similaires.
• Document : une unité de base d'informations pouvant être indexée.
• Shards : subdivisions entièrement fonctionnelles et indépendantes des indices. Chaque shard est en réalité un index Lucene.
• Replicas : mécanismes de basculement qui dupliquent les indices.

Installer un cluster Elasticsearch ou AWS OpenSearch {#install-an-elasticsearch-or-aws-opensearch-cluster}

Elasticsearch et AWS OpenSearch ne sont pas inclus dans le paquet Linux. Vous pouvez installer un cluster de recherche vous-même ou utiliser une offre hébergée dans le cloud telle que :

• Elasticsearch Service (disponible sur Amazon Web Services, Google Cloud Platform et Microsoft Azure)
• Amazon OpenSearch Service

Vous devriez installer le cluster de recherche sur un serveur distinct. L'exécution du cluster de recherche sur le même serveur que GitLab peut entraîner des problèmes de performance.

Pour un cluster de recherche avec un seul nœud, le statut du cluster est toujours jaune car le shard primaire est alloué. Le cluster ne peut pas attribuer des shards répliques au même nœud que les shards primaires.

[!note] Avant d'utiliser un nouveau cluster Elasticsearch en production, consultez la configuration Elasticsearch importante.

Compatibilité des versions {#version-compatibility}

Elasticsearch {#elasticsearch}

{{< history >}}

• La prise en charge d'Elasticsearch 6.8 a été supprimée dans GitLab 15.0.

{{< /history >}}

[!warning] La prise en charge d'Elasticsearch 7.x a été dépréciée dans GitLab 18.10 et sa suppression est prévue dans la version 20.0.

La recherche avancée est compatible avec les versions suivantes d'Elasticsearch.

GitLab.com utilise Elasticsearch 9.x. Utilisez Elasticsearch 9.x pour des performances optimales, les dernières fonctionnalités et la compatibilité ascendante.

La recherche avancée suit la politique de fin de vie d'Elasticsearch.

OpenSearch {#opensearch}

La recherche avancée est compatible avec les versions suivantes d'OpenSearch.

La recherche avancée suit la politique de maintenance d'OpenSearch.

Configuration requise {#system-requirements}

Elasticsearch et AWS OpenSearch nécessitent davantage de ressources que les exigences d'installation de GitLab.

Les besoins en mémoire, en CPU et en stockage dépendent de la quantité de données que vous indexez dans le cluster. Les clusters Elasticsearch très sollicités peuvent nécessiter davantage de ressources. La tâche Rake estimate_cluster_size utilise la taille totale du dépôt pour estimer les besoins en stockage de la recherche avancée.

Exigences d'accès {#access-requirements}

GitLab prend en charge les méthodes d'authentification HTTP et basées sur les rôles selon vos besoins et le service backend que vous utilisez.

Contrôle d'accès basé sur les rôles pour Elasticsearch {#role-based-access-control-for-elasticsearch}

Elasticsearch peut offrir un contrôle d'accès basé sur les rôles pour renforcer la sécurité d'un cluster. Pour accéder au cluster Elasticsearch et y effectuer des opérations, le Username configuré dans la zone Admin doit disposer de rôles accordant les privilèges suivants. Le Username envoie des requêtes de GitLab au cluster de recherche.

Pour plus d'informations, consultez Contrôle d'accès basé sur les rôles Elasticsearch et Privilèges de sécurité Elasticsearch.

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

Contrôle d'accès pour AWS OpenSearch Service {#access-control-for-aws-opensearch-service}

Prérequis :

• Vous devez disposer d'un rôle lié au service dans votre compte AWS nommé AWSServiceRoleForAmazonOpenSearchService lors de la création de domaines OpenSearch.
• La politique d'accès au domaine pour AWS OpenSearch doit autoriser les actions es:ESHttp*.

AWSServiceRoleForAmazonOpenSearchService est utilisé par l'ensemble des domaines OpenSearch. Dans la plupart des cas, ce rôle est créé automatiquement lorsque vous utilisez la console de gestion AWS pour créer le premier domaine OpenSearch. Pour créer un rôle lié au service manuellement, consultez la documentation AWS.

AWS OpenSearch Service comporte trois couches de sécurité principales :

• Réseau
• Politique d'accès au domaine
• Contrôle d'accès précis

Réseau {#network}

Avec cette couche de sécurité, vous pouvez sélectionner Accès public lors de la création d'un domaine pour que les requêtes de n'importe quel client puissent atteindre le point de terminaison du domaine. Si vous sélectionnez Accès VPC, les clients doivent se connecter au VPC pour que les requêtes atteignent le point de terminaison.

Pour plus d'informations, consultez la documentation AWS.

Politique d'accès au domaine {#domain-access-policy}

GitLab prend en charge les méthodes suivantes de contrôle d'accès au domaine pour AWS OpenSearch :

• Politiques d'accès basées sur les ressources (domaine) : le domaine AWS OpenSearch est configuré avec une politique IAM
• Politiques basées sur l'identité : les clients utilisent des principaux IAM avec des politiques pour configurer l'accès

Exemples de politiques basées sur les ressources {#resource-based-policy-examples}

Voici un exemple de politique d'accès basée sur les ressources (domaine) où les actions es:ESHttp* sont autorisées :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": [
        "es:ESHttp*"
      ],
      "Resource": "arn:aws:es:us-west-1:987654321098:domain/test-domain/*"
    }
  ]
}

Voici un exemple de politique d'accès basée sur les ressources (domaine) où les actions es:ESHttp* sont autorisées uniquement pour un principal IAM spécifique :

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": [
          "arn:aws:iam::123456789012:user/test-user"
        ]
      },
      "Action": [
        "es:ESHttp*"
      ],
      "Resource": "arn:aws:es:us-west-1:987654321098:domain/test-domain/*"
    }
  ]
}

[!note] Le aws_role_arn doit être fourni si vous utilisez AWS AssumeRole entre différents comptes. L'ARN doit correspondre au rôle disposant des autorisations pour accéder à OpenSearch.

Exemples de politiques basées sur l'identité {#identity-based-policy-examples}

Voici un exemple de politique d'accès basée sur l'identité associée à un principal IAM où les actions es:ESHttp* sont autorisées :

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

Contrôle d'accès précis {#fine-grained-access-control}

Lorsque vous activez le contrôle d'accès précis, vous devez définir un utilisateur principal de l'une des façons suivantes :

• Définir un ARN IAM comme utilisateur principal.
• Créer un utilisateur principal.

Définir un ARN IAM comme utilisateur principal {#set-an-iam-arn-as-a-master-user}

Si vous utilisez un principal IAM comme utilisateur principal, toutes les requêtes vers le cluster doivent être signées avec AWS Signature Version 4. Vous pouvez également spécifier un ARN IAM, qui est le rôle IAM que vous avez attribué à votre instance EC2. Pour plus d'informations, consultez la documentation AWS.

Prérequis :

• Disposer d'un accès administrateur.

Pour définir un ARN IAM comme utilisateur principal, vous devez utiliser AWS OpenSearch Service avec des identifiants IAM sur votre instance GitLab :

1. Dans le coin supérieur droit, sélectionnez Admin.

2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.

3. Développez Recherche avancée.

4. Dans la section Identifiants IAM AWS OpenSearch :

   1. Cochez la case Utiliser le service AWS OpenSearch avec les identifiants IAM.

   2. Dans Région AWS, saisissez la région AWS où se trouve votre domaine OpenSearch (par exemple, us-east-1).

   3. Dans AWS access key et AWS secret access key, saisissez vos clés d'accès pour l'authentification.

      [!note] Les déploiements GitLab s'exécutant directement sur des instances EC2 (pas dans des conteneurs) n'ont pas à saisir de clés d'accès. Votre instance GitLab obtient ces clés automatiquement depuis le service de métadonnées d'instance AWS (IMDS).

5. Sélectionnez Enregistrer les modifications.

Créer un utilisateur principal {#create-a-master-user}

Si vous créez un utilisateur principal dans la base de données d'utilisateurs interne, vous pouvez utiliser l'authentification HTTP de base pour envoyer des requêtes au cluster. Pour plus d'informations, consultez la documentation AWS.

Prérequis :

• Disposer d'un accès administrateur.

Pour créer un utilisateur principal, vous devez configurer l'URL du domaine OpenSearch ainsi que le nom d'utilisateur et le mot de passe du principal sur votre instance GitLab :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Développez Recherche avancée.
4. Dans l'URL du domaine OpenSearch, saisissez l'URL du point de terminaison du domaine OpenSearch.
5. Dans Nom d'utilisateur, saisissez le nom d'utilisateur principal.
6. Dans Mot de passe, saisissez le mot de passe principal.
7. Sélectionnez Enregistrer les modifications.

Mettre à niveau vers une nouvelle version d'Elasticsearch {#upgrade-to-a-new-elasticsearch-version}

{{< history >}}

• La prise en charge d'Elasticsearch 6.8 a été supprimée dans GitLab 15.0.

{{< /history >}}

Prérequis :

• Désactivez la recherche avancée pour que les recherches n'échouent pas avec une erreur HTTP 500.
• Suspendez l'indexation pour que les modifications puissent toujours être suivies.

Lorsque vous mettez à niveau Elasticsearch vers une nouvelle version mineure ou majeure, vous n'avez pas à modifier la configuration GitLab. Lorsque le cluster Elasticsearch est entièrement mis à niveau et actif :

1. Validez la connectivité du cluster, l'indexation et les opérations de recherche :

   shellCopy

   sudo gitlab-rake gitlab:elastic:index_and_search_validation
   

2. Reprenez l'indexation.

3. Facultatif. Vérifiez le statut d'indexation. Pour obtenir des résultats de recherche corrects, assurez-vous que l'indexation est complète, surtout si votre instance Elasticsearch a été hors ligne pendant un certain temps.

4. Activez la recherche avancée.

Indexeur de dépôt Elasticsearch {#elasticsearch-repository-indexer}

Pour indexer les données du dépôt Git, GitLab utilise gitlab-elasticsearch-indexer. Pour les installations auto-compilées, consultez installer l'indexeur.

Installer l'indexeur {#install-the-indexer}

Vous installez d'abord quelques dépendances, puis vous compilez et installez l'indexeur lui-même.

Installer les dépendances {#install-dependencies}

Ce projet repose sur International Components for Unicode (ICU) pour l'encodage du texte. Assurez-vous que les paquets de développement pour votre plateforme sont installés avant d'exécuter make.

Debian / Ubuntu {#debian--ubuntu}

Pour installer sur Debian ou Ubuntu, exécutez :

sudo apt install libicu-dev

CentOS / RHEL {#centos--rhel}

Pour installer sur CentOS ou RHEL, exécutez :

sudo yum install libicu-devel

macOS {#macos}

[!note] Vous devez d'abord installer Homebrew.

Pour installer sur macOS, exécutez :

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

Compiler et installer {#build-and-install}

Pour compiler et installer l'indexeur, exécutez :

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 est installé dans /usr/local/bin.

Vous pouvez modifier le chemin d'installation avec la variable d'environnement PREFIX. N'oubliez pas de passer le feature flag -E à sudo si vous le faites.

Exemple :

PREFIX=/usr sudo -E make install

Après l'installation, assurez-vous d'activer Elasticsearch.

[!note] Si vous voyez une erreur telle que Permission denied - /home/git/gitlab-elasticsearch-indexer/ lors de l'indexation, vous devrez peut-être définir le paramètre production -> elasticsearch -> indexer_path dans votre fichier gitlab.yml sur /usr/local/bin/gitlab-elasticsearch-indexer, qui est l'emplacement où le binaire est installé.

Afficher les erreurs d'indexation {#view-indexing-errors}

Les erreurs de l'indexeur GitLab Elasticsearch sont signalées dans le fichier elasticsearch.log et dans le fichier sidekiq.log avec un json.exception.class de Gitlab::Elastic::Indexer::Error. Ces erreurs peuvent survenir lors de l'indexation des données du dépôt Git.

Activer la recherche avancée {#enable-advanced-search}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.
• Configurez le nombre de shards par index.
• Configurez le nombre de répliques par index.
• Facultatif. Préparez-vous à l'indexation de grandes instances.

Pour activer la recherche avancée :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Configurez les paramètres de recherche avancée pour votre cluster Elasticsearch. Ne cochez pas encore la case Recherche avancée.
4. Indexez l'instance.
5. Facultatif. Vérifiez le statut d'indexation.
6. Une fois l'indexation terminée, cochez la case Recherche avancée, puis sélectionnez Sauvegarder les modifications.

[!note] Lorsque votre cluster Elasticsearch est indisponible alors qu'Elasticsearch est activé, vous pourriez rencontrer des problèmes lors de la mise à jour de documents tels que des tickets, car votre instance met en file d'attente un job pour indexer la modification, mais ne peut pas trouver un cluster Elasticsearch valide.

Pour les instances GitLab contenant plus de 50 Go de données de dépôt, consultez Indexer les grandes instances efficacement.

Indexer l'instance {#index-the-instance}

Depuis l'interface utilisateur {#from-the-user-interface}

{{< history >}}

• Introduction dans GitLab 17.3.

{{< /history >}}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Vous pouvez effectuer une indexation initiale ou recréer un index depuis l'interface utilisateur.

Pour activer la recherche avancée et indexer l'instance depuis l'interface utilisateur :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Cochez la case Activer l'indexation pour la recherche avancée, puis sélectionnez Sauvegarder les modifications.
4. Sélectionnez Indexer l'instance.

Avec une tâche Rake {#with-a-rake-task}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour indexer l'intégralité de l'instance, utilisez les tâches Rake suivantes :

# WARNING: This task deletes all existing indices
# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index

# WARNING: This task deletes all existing indices
# For self-compiled installations
bundle exec rake gitlab:elastic:index RAILS_ENV=production

Pour indexer des données spécifiques, utilisez les tâches Rake suivantes :

# For installations that use the Linux package
sudo gitlab-rake gitlab:elastic:index_work_items
sudo gitlab-rake gitlab:elastic:index_group_wikis
sudo gitlab-rake gitlab:elastic:index_namespaces
sudo gitlab-rake gitlab:elastic:index_projects
sudo gitlab-rake gitlab:elastic:index_snippets
sudo gitlab-rake gitlab:elastic:index_users

# For self-compiled installations
bundle exec rake gitlab:elastic:index_work_items RAILS_ENV=production
bundle exec rake gitlab:elastic:index_group_wikis RAILS_ENV=production
bundle exec rake gitlab:elastic:index_namespaces RAILS_ENV=production
bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production
bundle exec rake gitlab:elastic:index_snippets RAILS_ENV=production
bundle exec rake gitlab:elastic:index_users RAILS_ENV=production

Vérifier le statut d'indexation {#check-indexing-status}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour vérifier le statut d'indexation :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Développez État de l'indexation de la recherche avancée.

Surveiller le statut des jobs en arrière-plan {#monitor-the-status-of-background-jobs}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour surveiller la progression de l'indexation, vous pouvez également vérifier le statut des jobs en arrière-plan :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Surveillance > Jobs en arrière-plan.
3. Sur le tableau de bord Sidekiq, sélectionnez Occupé(e) et observez ces jobs d'indexation :
   • Search::Elastic::CommitIndexerWorker pour le code et les commits.
   • ElasticWikiIndexerWorker pour les données wiki.

Activer la recherche avancée {#enable-search-with-advanced-search}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour activer la recherche avancée dans GitLab :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Cochez la case Recherche avancée.
4. Sélectionnez Enregistrer les modifications.

Activer la recherche de code avec la recherche avancée {#enable-code-search-with-advanced-search}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour activer la recherche de code avec la recherche avancée dans GitLab :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Cochez la case Recherche de code à l'aide de la recherche avancée.
4. Sélectionnez Enregistrer les modifications.

Configuration de la recherche avancée {#advanced-search-configuration}

Les paramètres Elasticsearch suivants sont disponibles :

[!warning] L'augmentation des valeurs de Taille maximale pour les requêtes en bloc (Mio) et de Simultanéité des requêtes en bloc peut nuire aux performances de Sidekiq. Rétablissez leurs valeurs par défaut si vous constatez une augmentation des durées scheduling_latency_s dans vos logs Sidekiq. Pour plus d'informations, consultez l'issue 322147.

Limiter le nombre d'espaces de nommage et la quantité de données de projet à indexer {#limit-the-amount-of-namespace-and-project-data-to-index}

{{< history >}}

• L'indexation de tous les enregistrements de projet a été introduite dans GitLab 16.7 avec un feature flag nommé search_index_all_projects. Désactivé par défaut.
• Généralement disponible dans GitLab 16.11. Feature flag search_index_all_projects supprimé.
• L'indexation des enregistrements de vulnérabilité a été introduite sur GitLab.com et GitLab Dedicated dans GitLab 18.1 avec un feature flag nommé vulnerability_es_ingestion. Désactivé par défaut.
• L'indexation des enregistrements de vulnérabilité est généralement disponible sur GitLab.com et GitLab Dedicated dans GitLab 18.2. Feature flag vulnerability_es_ingestion supprimé.

{{< /history >}}

[!flag] Un feature flag contrôle la disponibilité de cette fonctionnalité. Pour plus d'informations, consultez l'historique.

Lorsque vous cochez la case Limiter le nombre d'espaces de nommage et la quantité de données de projet à indexer, vous pouvez spécifier les espaces de nommage et les projets à indexer. Si l'espace de nommage est un groupe, tous les sous-groupes et projets de ces sous-groupes sont également indexés.

Lorsque vous activez ce paramètre :

• Les espaces de nommage ou les projets doivent être spécifiés pour une indexation complète.
• Les enregistrements de projet (métadonnées telles que les noms et descriptions de projets) sont toujours indexés pour tous les projets.
• Les enregistrements de vulnérabilité sont toujours indexés pour tous les projets et espaces de nommage afin de prendre en charge le filtrage dans les rapports de sécurité.
• Les données associées sont indexées uniquement pour les espaces de nommage et les projets que vous spécifiez.

[!warning] Si vous ne spécifiez aucun espace de nommage ni projet après avoir activé ce paramètre, seuls les enregistrements de projet sont indexés et aucune donnée associée ne peut être recherchée.

Espaces de nommage indexés {#indexed-namespaces}

{{< history >}}

• La recherche globale pour une indexation limitée a été introduite dans GitLab 13.4 avec un feature flag nommé advanced_global_search_for_limited_indexing. Désactivé par défaut.
• Activée sur GitLab.com dans GitLab 14.2.
• La recherche globale pour une indexation limitée est généralement disponible dans GitLab 17.11 en tant qu'option d'interface utilisateur, à la place du feature flag advanced_global_search_for_limited_indexing.

{{< /history >}}

Lorsque vous indexez tous les espaces de nommage, vous pouvez utiliser la recherche avancée pour la recherche globale de code et de commits. Lorsque vous n'indexez que certains espaces de nommage :

• La recherche globale n'inclut pas la portée de recherche de code ou de commits.
• Les recherches de code et de commits sont disponibles uniquement dans un seul espace de nommage indexé.
• Une recherche de code ou de commit unique n'est pas possible sur plusieurs espaces de nommage indexés.
• La recherche inter-projets est disponible dans un espace de nommage indexé.

Par exemple, si vous indexez deux groupes distincts, vous devez effectuer des recherches de code séparées sur chaque groupe individuellement.

Pour activer la recherche globale pour une indexation limitée :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Développez Recherche avancée
4. Sélectionnez Activer la recherche globale pour l'indexation limitée.
5. Sélectionnez Enregistrer les modifications.
6. Si vous avez déjà indexé votre instance, vous devez réindexer l'instance. Cela supprime les données de recherche existantes pour permettre au filtrage de fonctionner correctement.

Activer les analyseurs de langue personnalisés {#enable-custom-language-analyzers}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Vous pouvez améliorer la prise en charge du chinois et du japonais en utilisant les plugins d'analyse smartcn et kuromoji d'Elastic.

Pour activer les analyseurs de langue personnalisés :

1. Installez les plugins souhaités, consultez la documentation Elasticsearch pour obtenir des instructions d'installation des plugins. Les plugins doivent être installés sur chaque nœud du cluster, et chaque nœud doit être redémarré après l'installation. Pour obtenir la liste des plugins, consultez le tableau plus loin dans cette section.
2. Dans le coin supérieur droit, sélectionnez Admin.
3. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
4. Localisez Analyseurs personnalisés : prise en charge des langues.
5. Activez la prise en charge des plugins pour l'indexation.
6. Sélectionnez Sauvegarder les modifications pour que les modifications prennent effet.
7. Déclenchez une réindexation sans temps d'arrêt ou réindexez tout depuis le début pour créer un nouvel index avec des mappings mis à jour.
8. Activez la prise en charge des plugins pour Recherche une fois l'étape précédente terminée.

Pour obtenir des conseils sur ce qu'il faut installer, consultez les options de plugins de langue Elasticsearch suivantes :

Désactiver la recherche avancée {#disable-advanced-search}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour désactiver la recherche avancée dans GitLab :

1. Dans le coin supérieur droit, sélectionnez Admin.

2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.

3. Décochez les cases Activer l'indexation pour la recherche avancée et Recherche avancée.

4. Sélectionnez Enregistrer les modifications.

5. Facultatif. Pour les instances Elasticsearch toujours en ligne, supprimez les indices existants :

   shellCopy

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:delete_index
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:delete_index RAILS_ENV=production
   

Désactiver la recherche avancée {#disable-search-with-advanced-search}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour désactiver la recherche avancée dans GitLab :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Décochez la case Recherche avancée.
4. Sélectionnez Enregistrer les modifications.

Désactiver la recherche de code avec la recherche avancée {#disable-code-search-with-advanced-search}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour désactiver la recherche de code avec la recherche avancée dans GitLab :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Décochez la case Recherche de code à l'aide de la recherche avancée.
4. Sélectionnez Enregistrer les modifications.

Suspendre l'indexation {#pause-indexing}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour suspendre l'indexation :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Développez Recherche avancée.
4. Cochez la case Suspendre l'indexation pour la recherche avancée.
5. Sélectionnez Enregistrer les modifications.

Reprendre l'indexation {#resume-indexing}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour reprendre l'indexation :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Développez Recherche avancée.
4. Décochez la case Suspendre l'indexation pour la recherche avancée.
5. Sélectionnez Enregistrer les modifications.

Réindexation sans temps d'arrêt {#zero-downtime-reindexing}

L'idée derrière cette méthode de réindexation est d'utiliser l'API de réindexation Elasticsearch et la fonctionnalité d'alias d'index Elasticsearch pour effectuer l'opération. Un alias d'index se connecte à un index primary que GitLab utilise pour les lectures et les écritures. Lorsque le processus de réindexation démarre, les écritures dans l'index primary sont temporairement suspendues. Ensuite, un autre index est créé et l'API Reindex est invoquée pour migrer les données de l'index vers le nouvel index. Une fois le job de réindexation terminé, l'alias d'index bascule vers le nouvel index, qui devient le nouvel index primary. Enfin, les écritures reprennent et le fonctionnement normal continue.

Utiliser la réindexation sans temps d'arrêt {#using-zero-downtime-reindexing}

Vous pouvez utiliser la réindexation sans temps d'arrêt pour configurer les paramètres d'index ou les mappings qui ne peuvent pas être modifiés sans créer un nouvel index et copier les données existantes. Vous ne devriez pas utiliser la réindexation sans temps d'arrêt pour corriger les données manquantes. La réindexation sans temps d'arrêt n'ajoute pas de données au cluster de recherche si celles-ci ne sont pas déjà indexées. Vous devez terminer toutes les migrations de recherche avancée avant de démarrer la réindexation.

Déclencher la réindexation {#trigger-reindexing}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour déclencher la réindexation :

1. Connectez-vous à votre instance GitLab en tant qu'administrateur.
2. Dans le coin supérieur droit, sélectionnez Admin.
3. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
4. Développez Réindexation sans temps d'arrêt de la recherche avancée.
5. Sélectionnez Déclencher la réindexation du cluster.

La réindexation peut être un processus long en fonction de la taille de votre cluster Elasticsearch.

Une fois ce processus terminé, l'index d'origine est planifié pour être supprimé après 14 jours. Vous pouvez annuler cette action en appuyant sur le bouton Annuler sur la même page où vous avez déclenché le processus de réindexation.

Pendant l'exécution de la réindexation, vous pouvez suivre sa progression dans cette même section.

Déclencher la réindexation sans temps d'arrêt {#trigger-zero-downtime-reindexing}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour déclencher la réindexation sans temps d'arrêt :

1. Dans le coin supérieur droit, sélectionnez Admin.

2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.

3. Développez Réindexation sans temps d'arrêt de la recherche avancée. Les paramètres suivants sont disponibles :

   • Multiplicateur de tranches
   • Nombre maximal de tranches en cours d'exécution

Multiplicateur de tranches {#slice-multiplier}

Le multiplicateur de tranches calcule le nombre de tranches lors de la réindexation.

GitLab utilise le découpage manuel pour contrôler la réindexation de manière efficace et sécurisée, ce qui permet aux utilisateurs de ne réessayer que les tranches ayant échoué.

Le multiplicateur est par défaut 2 et s'applique au nombre de shards par index. Par exemple, si cette valeur est 2 et que votre index comporte 20 shards, la tâche de réindexation est divisée en 40 tranches.

Nombre maximal de tranches en cours d'exécution {#maximum-running-slices}

Le paramètre de nombre maximal de tranches en cours d'exécution est par défaut 60 et correspond au nombre maximal de tranches autorisées à s'exécuter simultanément lors de la réindexation Elasticsearch.

Définir cette valeur trop haute peut avoir des impacts négatifs sur les performances, car votre cluster peut devenir fortement saturé par les recherches et les écritures. Définir cette valeur trop basse peut conduire le processus de réindexation à prendre très longtemps pour se terminer.

La meilleure valeur pour ce paramètre dépend de la taille de votre cluster, de votre disposition à accepter une dégradation des performances de recherche pendant la réindexation, et de l'importance de terminer rapidement la réindexation et de reprendre l'indexation.

Marquer le job de réindexation le plus récent comme ayant échoué et reprendre l'indexation {#mark-the-most-recent-reindexing-job-as-failed-and-resume-indexing}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

Pour abandonner un job de réindexation inachevé et reprendre l'indexation :

1. Marquez le job de réindexation le plus récent comme ayant échoué :

   shellCopy

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:mark_reindex_failed
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:mark_reindex_failed RAILS_ENV=production
   

2. Dans le coin supérieur droit, sélectionnez Admin.

3. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.

4. Développez Recherche avancée.

5. Décochez la case Suspendre l'indexation pour la recherche avancée.

Intégrité de l'index {#index-integrity}

{{< history >}}

• Introduite dans GitLab 15.10 avec un feature flag nommé search_index_integrity. Désactivé par défaut.
• Généralement disponible dans GitLab 16.4. Feature flag search_index_integrity supprimé.

{{< /history >}}

L'intégrité de l'index détecte et corrige les données de dépôt manquantes. Cette fonctionnalité est utilisée automatiquement lorsque les recherches de code limitées à un groupe ou à un projet ne renvoient aucun résultat.

Migrations de recherche avancée {#advanced-search-migrations}

Les migrations de réindexation s'exécutent en arrière-plan, ce qui signifie que vous n'avez pas à réindexer l'instance manuellement.

Dans GitLab 18.0 et versions ultérieures, vous pouvez utiliser le paramètre d'application elastic_migration_worker_enabled pour activer ou désactiver le worker de migration. Par défaut, le worker de migration est activé.

Fichiers de dictionnaire de migration {#migration-dictionary-files}

{{< history >}}

• Introduite dans GitLab 16.3.

{{< /history >}}

Chaque migration dispose d'un fichier de dictionnaire correspondant dans le dossier ee/elastic/docs/ avec les informations suivantes :

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

Vous pouvez utiliser ces informations, par exemple, pour identifier quand une migration a été introduite ou marquée comme obsolète.

Vérifier les migrations en attente {#check-for-pending-migrations}

Pour vérifier les migrations de recherche avancée en attente, exécutez cette commande :

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

Cela devrait renvoyer quelque chose de similaire à :

{
  "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": "20230209195404",
        "_score": 1,
        "_source": {
          "completed": true
        }
      }
    ]
  }
}

Pour déboguer les problèmes liés aux migrations, consultez le fichier elasticsearch.log.

Réessayer une migration bloquée {#retry-a-halted-migration}

Certaines migrations sont créées avec une limite de tentatives. Si la migration ne peut pas se terminer dans la limite de tentatives, elle est bloquée et une notification s'affiche dans les paramètres d'intégration de recherche avancée.

Il est recommandé de consulter le fichier elasticsearch.log pour déboguer la raison du blocage de la migration et d'apporter les modifications nécessaires avant de réessayer la migration.

Lorsque vous pensez avoir corrigé la cause de l'échec :

1. Dans le coin supérieur droit, sélectionnez Admin.
2. Dans la barre latérale gauche, sélectionnez Paramètres > Rechercher.
3. Développez Recherche avancée.
4. Dans la boîte d'alerte migration d'Elasticsearch en pause, sélectionnez Retenter la migration. La migration est planifiée pour être relancée en arrière-plan.

Si vous ne parvenez pas à faire aboutir la migration, vous pouvez envisager la dernière solution consistant à recréer l'index depuis le début. Cela peut vous permettre de contourner le problème, car un index nouvellement créé ignore toutes les migrations puisque l'index est recréé avec le schéma correct et à jour.

Toutes les migrations doivent être terminées avant d'effectuer une mise à niveau majeure {#all-migrations-must-be-finished-before-doing-a-major-upgrade}

Avant de mettre à niveau vers une version majeure de GitLab, vous devez effectuer toutes les migrations qui existent jusqu'à la dernière version mineure avant cette version majeure. Vous devez également résoudre et réessayer toutes les migrations bloquées avant de procéder à une mise à niveau vers une version majeure. Pour plus d'informations, consultez Migrations pour les mises à niveau.

Les migrations qui ont été supprimées sont marquées comme obsolètes. Si vous mettez à niveau GitLab avant que toutes les migrations de recherche avancée en attente soient terminées, les migrations en attente qui ont été supprimées dans la nouvelle version ne peuvent pas être exécutées ni relancées. Dans ce cas, vous devez recréer votre index depuis le début.

Migrations ignorables {#skippable-migrations}

Les migrations ignorables ne sont exécutées que lorsqu'une condition est remplie. Par exemple, si une migration dépend d'une version spécifique d'Elasticsearch, elle peut être ignorée jusqu'à ce que cette version soit atteinte.

Si une migration ignorable n'est pas exécutée au moment où la migration est marquée comme obsolète, vous devez recréer l'index pour appliquer la modification.

Tâches Rake de recherche avancée GitLab {#gitlab-advanced-search-rake-tasks}

Des tâches Rake sont disponibles pour :

• Compiler et installer l'indexeur.
• Supprimer les indices lors de la désactivation d'Elasticsearch.
• Ajouter des données GitLab à un index.

Voici quelques tâches Rake disponibles :

Variables d'environnement {#environment-variables}

En plus des tâches Rake, certaines variables d'environnement peuvent être utilisées pour modifier le processus :

Indexation d'une plage de projets ou d'un projet spécifique {#indexing-a-range-of-projects-or-a-specific-project}

En utilisant les variables d'environnement ID_FROM et ID_TO, vous pouvez indexer un nombre limité de projets. Cela peut être utile pour l'indexation par étapes.

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

Étant donné que ID_FROM et ID_TO utilisent la comparaison or equal to, vous pouvez les utiliser pour indexer un seul projet en définissant les deux sur le même ID de projet :

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!

Portées de l'index de recherche avancée {#advanced-search-index-scopes}

Lors d'une recherche, l'index GitLab utilise les portées suivantes :

Sur GitLab.com et GitLab Dedicated, les enregistrements de vulnérabilités sont toujours indexés pour tous les projets et espaces de nommage afin de prendre en charge les fonctionnalités en dehors de la recherche. L'indexation des enregistrements de vulnérabilités sur GitLab Self-Managed est proposée dans le ticket 525484.

Optimisation {#tuning}

Conseils pour choisir la configuration optimale du cluster {#guidance-on-choosing-optimal-cluster-configuration}

Pour des conseils de base sur le choix d'une configuration de cluster, consultez également Elastic Cloud Calculator.

• En général, vous devriez utiliser au moins une configuration de cluster à 2 nœuds avec un réplica, ce qui vous permet d'avoir de la résilience. Si votre utilisation du stockage augmente rapidement, vous devriez prévoir une mise à l'échelle horizontale (ajout de nœuds supplémentaires) à l'avance.
• Il n'est pas recommandé d'utiliser le stockage HDD avec le cluster de recherche, car cela nuit aux performances. Il est préférable d'utiliser le stockage SSD (par exemple, des disques SSD NVMe ou SATA).
• Vous ne devriez pas utiliser de nœuds de coordination uniquement avec des instances de grande taille. Les nœuds de coordination uniquement sont plus petits que les nœuds de données, ce qui peut avoir un impact sur les performances et les migrations de recherche avancée.
• Vous pouvez utiliser le GitLab Performance Tool pour comparer les performances de recherche avec différentes tailles et configurations de cluster de recherche.
• Heap size ne doit pas être défini à plus de 50 % de votre RAM physique. De plus, il ne doit pas être défini à une valeur supérieure au seuil des oops compressés à base zéro. Le seuil exact varie, mais 26 Go est sans risque sur la plupart des systèmes, mais peut également atteindre 30 Go sur certains systèmes. Consultez les paramètres Heap size et les options des paramètres JVM pour plus de détails.
• refresh_interval est un paramètre par index. Vous pouvez ajuster cette valeur par défaut 1s vers une valeur plus grande si vous n'avez pas besoin de données en temps réel. Cela modifie la rapidité avec laquelle vous voyez les résultats récents. Si cela est important pour vous, vous devriez le laisser aussi proche que possible de la valeur par défaut.
• Vous pouvez envisager d'augmenter indices.memory.index_buffer_size à 30 % ou 40 % si vous avez de nombreuses opérations d'indexation intensives.

Paramètres de recherche avancée {#advanced-search-settings}

Nombre de shards Elasticsearch {#number-of-elasticsearch-shards}

{{< history >}}

• gitlab:elastic:estimate_shard_sizes introduit dans GitLab 16.11.
• gitlab:elastic:estimate_shard_sizes modifié dans GitLab 18.3 pour inclure le dimensionnement des index contenant des données de dépôt.

{{< /history >}}

Pour les clusters à nœud unique, définissez le nombre de shards Elasticsearch par index sur le nombre de cœurs CPU des nœuds de données Elasticsearch.

Pour les clusters multi-nœuds, exécutez la tâche Rake gitlab:elastic:estimate_shard_sizes pour déterminer le nombre de shards pour chaque index. La tâche renvoie des recommandations concernant la taille des shards et des réplicas ainsi que des estimations du nombre de documents pour les index contenant des données de base de données.

Maintenez la taille moyenne des shards entre quelques Go et 30 Go. Si la taille moyenne des shards dépasse 30 Go, augmentez la taille des shards pour l'index et déclenchez la réindexation sans temps d'arrêt. Pour garantir l'intégrité du cluster, le nombre de shards par nœud ne doit pas dépasser 20 fois la taille de heap configurée. Par exemple, un nœud avec un heap de 30 Go doit avoir un maximum de 600 shards.

Pour mettre à jour le nombre de shards d'un index, modifiez le paramètre et déclenchez la réindexation sans temps d'arrêt.

Nombre de réplicas Elasticsearch {#number-of-elasticsearch-replicas}

Pour les clusters à nœud unique, définissez le nombre de réplicas Elasticsearch par index sur 0.

Pour les clusters multi-nœuds, définissez le nombre de réplicas Elasticsearch par index sur 1 (chaque shard dispose d'un réplica). Le nombre ne doit pas être 0 car la perte d'un nœud corrompt l'index.

Si la prise en compte de l'allocation des shards est activée, le nombre total de copies par shard doit être divisible uniformément par le nombre d'attributs de prise en compte (généralement des nœuds ou des zones). La distribution uniforme des copies de shards sur tous les attributs de prise en compte garantit une tolérance aux pannes et une distribution de charge optimales.

(1 + `number_of_replicas`) / `number_of_awareness_attributes` = whole number

Pour mettre à jour le nombre de réplicas d'un index, modifiez le paramètre et déclenchez la réindexation sans temps d'arrêt.

Indexer efficacement les grandes instances {#index-large-instances-efficiently}

Prérequis :

• Vous devez disposer d'un accès administrateur à l'instance.

[!warning] L'indexation d'une grande instance génère de nombreux jobs Sidekiq. Assurez-vous de vous préparer à cette tâche en disposant d'une configuration évolutive ou en créant des processus Sidekiq supplémentaires.

Les nœuds Geo primaires et secondaires pointent vers le même cluster Elasticsearch. Cependant, les workers d'indexation Elasticsearch s'exécutent uniquement sur les nœuds Sidekiq du site primaire.

Pour cette raison, vous devez configurer tous les processus Sidekiq supplémentaires sur les nœuds Sidekiq du site primaire.

Si l'activation de la recherche avancée pose des problèmes en raison de volumes importants de données à indexer :

1. Configurez votre hôte et port Elasticsearch.

2. Créez des index vides :

   shellCopy

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:create_empty_index
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production
   

3. S'il s'agit d'une réindexation de votre instance GitLab, effacez le statut de l'index :

   shellCopy

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:clear_index_status
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:clear_index_status RAILS_ENV=production
   

4. Cochez la case Activer l'indexation pour la recherche avancée.

5. L'indexation de grands dépôts Git peut prendre du temps. Pour accélérer le processus, vous pouvez optimiser pour la vitesse d'indexation :

   • Vous pouvez temporairement augmenter refresh_interval.

   • Vous pouvez définir le nombre de réplicas sur 0. Ce paramètre contrôle le nombre de copies de chaque shard primaire d'un index. Ainsi, avoir 0 réplica désactive effectivement la réplication des shards entre les nœuds, ce qui devrait améliorer les performances d'indexation. Il s'agit d'un compromis important en termes de fiabilité et de performances des requêtes. Il est important de ne pas oublier de définir les réplicas sur une valeur appropriée une fois l'indexation initiale terminée.

   Vous pouvez vous attendre à une diminution de 20 % du temps d'indexation. Une fois l'indexation terminée, vous pouvez réinitialiser refresh_interval et number_of_replicas à leurs valeurs souhaitées.

   [!note] Cette étape est facultative mais peut contribuer à accélérer considérablement les grandes opérations d'indexation.

   shellCopy

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

6. Indexez les projets et leurs données associées :

   shellCopy

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:index_projects
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production
   

   Cela met en file d'attente un job Sidekiq pour chaque projet qui doit être indexé. Vous pouvez interroger le statut d'indexation avec une tâche Rake :

   shellCopy

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:index_projects_status
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production
   
   Indexing is 65.55% complete (6555/10000 projects). Considers only code, commits, and wikis.
   

   Si vous souhaitez limiter l'index à une plage de projets, vous pouvez fournir les paramètres ID_FROM et ID_TO :

   shellCopy

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production
   

   Où ID_FROM et ID_TO sont des ID de projet. Les deux paramètres sont facultatifs. L'exemple précédent indexe tous les projets depuis l'ID 1001 jusqu'à (et y compris) l'ID 2000.

   [!note] Parfois, les jobs d'indexation de projets mis en file d'attente par gitlab:elastic:index_projects peuvent être interrompus. Cela peut se produire pour de nombreuses raisons, mais il est toujours sans risque de relancer la tâche d'indexation.

   Vous pouvez également utiliser la tâche Rake gitlab:elastic:clear_index_status pour forcer l'indexeur à « oublier » toute progression, afin qu'il recommence le processus d'indexation depuis le début.

7. Les éléments de travail, les wikis de groupe, les extraits de code personnels et les utilisateurs ne sont pas associés à un projet et doivent être indexés séparément :

   shellCopy

   # For installations that use the Linux package
   sudo gitlab-rake gitlab:elastic:index_work_items
   sudo gitlab-rake gitlab:elastic:index_group_wikis
   sudo gitlab-rake gitlab:elastic:index_snippets
   sudo gitlab-rake gitlab:elastic:index_users
   
   # For self-compiled installations
   bundle exec rake gitlab:elastic:index_work_items 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. Réactivez la réplication et l'actualisation après l'indexation (uniquement si vous avez précédemment augmenté refresh_interval) :

   shellCopy

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

   Un force merge doit être effectué après avoir réactivé l'actualisation.

   Pour Elasticsearch 6.x et versions ultérieures, assurez-vous que l'index est en mode lecture seule avant de procéder au force merge :

   shellCopy

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

   Ensuite, initiez le force merge :

   shellCopy

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

   Ensuite, remettez l'index en mode lecture-écriture :

   shellCopy

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

9. Une fois l'indexation terminée, cochez la case Recherche avancée.

Indexer de grandes instances avec des nœuds ou processus Sidekiq dédiés {#index-large-instances-with-dedicated-sidekiq-nodes-or-processes}

[!warning] Pour la plupart des instances, vous n'avez pas à configurer de nœuds ou processus Sidekiq dédiés. Les étapes suivantes utilisent un paramètre avancé de Sidekiq appelé règles de routage. Assurez-vous de bien comprendre les implications de l'utilisation des règles de routage pour éviter de perdre des jobs entièrement.

L'indexation d'une grande instance peut être un processus long et gourmand en ressources, susceptible de surcharger les nœuds et processus Sidekiq. Cela affecte négativement les performances et la disponibilité de GitLab.

Étant donné que GitLab vous permet de démarrer plusieurs processus Sidekiq, vous pouvez créer un processus supplémentaire dédié à l'indexation d'un ensemble de files d'attente (ou groupe de files d'attente). Ainsi, vous pouvez vous assurer que les files d'attente d'indexation disposent toujours d'un worker dédié, tandis que les autres files d'attente disposent d'un autre worker dédié pour éviter les conflits.

À cet effet, utilisez l'option règles de routage qui permet à Sidekiq d'acheminer les jobs vers une file d'attente spécifique en fonction d'une requête de correspondance de worker.

[!note] Les règles de routage (sidekiq['routing_rules']) doivent être identiques sur tous les nœuds GitLab (en particulier les nœuds GitLab Rails et Sidekiq).

Vous pouvez choisir l'une des deux options suivantes pour gérer cela :

• Utiliser deux groupes de files d'attente sur un seul nœud.
• Utiliser deux groupes de files d'attente, un sur chaque nœud.

Pour les étapes suivantes, considérez l'entrée de sidekiq['routing_rules'] :

• ["feature_category=global_search", "global_search"] car tous les jobs d'indexation sont acheminés vers la file d'attente global_search.
• ["*", "default"] car tous les autres jobs non liés à l'indexation sont acheminés vers la file d'attente default.

Au moins un processus dans sidekiq['queue_groups'] doit inclure la file d'attente mailers, sinon les jobs de messagerie ne sont pas traités du tout.

[!warning] Lors du démarrage de plusieurs processus, le nombre de processus ne peut pas dépasser le nombre de cœurs CPU que vous souhaitez dédier à Sidekiq. Chaque processus Sidekiq ne peut utiliser qu'un seul cœur CPU, en fonction de la charge de travail disponible et des paramètres de concurrence. Pour plus de détails, consultez comment exécuter plusieurs processus Sidekiq.

Nœud unique, deux processus {#single-node-two-processes}

Pour créer à la fois un processus Sidekiq d'indexation et un processus Sidekiq non-indexation sur un seul nœud :

1. Sur votre nœud Sidekiq, modifiez le fichier /etc/gitlab/gitlab.rb comme suit :

   rubyCopy

   sidekiq['enable'] = true
   
   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['concurrency'] = 20
   

   Si vous utilisez GitLab 16.11 ou une version antérieure, désactivez explicitement tous les sélecteurs de files d'attente :

   rubyCopy

   sidekiq['queue_selector'] = false
   

2. Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.

3. Sur tous les autres nœuds Rails et Sidekiq, assurez-vous que sidekiq['routing_rules'] est identique à la configuration précédente.

4. Exécutez la tâche Rake pour migrer les jobs existants :

[!note] Il est important d'exécuter la tâche Rake immédiatement après avoir reconfiguré GitLab. Après la reconfiguration de GitLab, les jobs existants ne sont pas traités tant que la tâche Rake n'a pas commencé à migrer les jobs.

Deux nœuds, un processus chacun {#two-nodes-one-process-for-each}

Pour gérer ces groupes de files d'attente sur deux nœuds :

1. Pour configurer le processus Sidekiq d'indexation, sur votre nœud Sidekiq d'indexation, modifiez le fichier /etc/gitlab/gitlab.rb comme suit :

   rubyCopy

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

   Si vous utilisez GitLab 16.11 ou une version antérieure, désactivez explicitement tous les sélecteurs de files d'attente :

   rubyCopy

   sidekiq['queue_selector'] = false
   

2. Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.

3. Pour configurer le processus Sidekiq non-indexation, sur votre nœud Sidekiq non-indexation, modifiez le fichier /etc/gitlab/gitlab.rb comme suit :

   rubyCopy

   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['concurrency'] = 20
   

   Si vous utilisez GitLab 16.11 ou une version antérieure, désactivez explicitement tous les sélecteurs de files d'attente :

   rubyCopy

   sidekiq['queue_selector'] = false
   

4. Sur tous les autres nœuds Rails et Sidekiq, assurez-vous que sidekiq['routing_rules'] est identique à la configuration précédente.

5. Enregistrez le fichier et reconfigurez GitLab pour que les modifications prennent effet.

6. Exécutez la tâche Rake pour migrer les jobs existants :

   shellCopy

   sudo gitlab-rake gitlab:sidekiq:migrate_jobs:retry gitlab:sidekiq:migrate_jobs:schedule gitlab:sidekiq:migrate_jobs:queued
   

[!note] Il est important d'exécuter la tâche Rake immédiatement après avoir reconfiguré GitLab. Après la reconfiguration de GitLab, les jobs existants ne sont pas traités tant que la tâche Rake n'a pas commencé à migrer les jobs.

Documents supprimés {#deleted-documents}

Chaque fois qu'une modification ou une suppression est apportée à un objet GitLab indexé (description d'une merge request modifiée, fichier supprimé de la branche par défaut dans un dépôt, projet supprimé, etc.), un document dans l'index est supprimé. Cependant, comme il s'agit de suppressions « logicielles », le nombre total de « documents supprimés », et donc l'espace gaspillé, augmente.

Elasticsearch effectue une fusion intelligente des segments pour supprimer ces documents supprimés. Cependant, en fonction de la quantité et du type d'activité dans votre installation GitLab, il est possible de constater jusqu'à 50 % d'espace gaspillé dans l'index.

Vous devriez généralement laisser Elasticsearch fusionner et récupérer l'espace automatiquement avec les paramètres par défaut. D'après gestion des documents supprimés de Lucene, « Dans l'ensemble, en dehors peut-être de la réduction de la taille maximale des segments, il est préférable de laisser les paramètres par défaut de Lucene tels quels et de ne pas trop se soucier du moment où les suppressions sont récupérées. »

Cependant, certaines installations plus importantes peuvent souhaiter ajuster les paramètres de politique de fusion :

• Envisagez de réduire la taille de index.merge.policy.max_merged_segment par rapport à la valeur par défaut de 5 Go, à peut-être 2 Go ou 3 Go. La fusion ne se produit que lorsqu'un segment a au moins 50 % de suppressions. Des tailles de segments plus petites permettent à la fusion de se produire plus fréquemment.

  shellCopy

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

• Vous pouvez également ajuster index.merge.policy.reclaim_deletes_weight, qui contrôle l'agressivité avec laquelle les suppressions sont ciblées. Mais cela peut conduire à des décisions de fusion coûteuses, vous ne devriez donc pas modifier ce paramètre à moins de comprendre les compromis impliqués.

  shellCopy

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

• N'effectuez pas de force merge pour supprimer des documents supprimés. Un avertissement dans la documentation indique que cela peut conduire à de très grands segments qui ne seront peut-être jamais récupérés, et peut également causer des problèmes de performances ou de disponibilité significatifs.

Retour à la recherche basique {#reverting-to-basic-search}

Il peut parfois y avoir des problèmes avec les données de votre index Elasticsearch et, de ce fait, GitLab vous permet de revenir à la « recherche basique » lorsqu'il n'y a aucun résultat de recherche et en supposant que la recherche basique est prise en charge dans cette portée. Cette « recherche basique » se comporte comme si vous n'aviez pas du tout activé la recherche avancée pour votre instance et effectue des recherches en utilisant d'autres sources de données (telles que les données PostgreSQL et les données Git).

Reprise après sinistre {#disaster-recovery}

Elasticsearch est une banque de données secondaire pour GitLab. Toutes les données stockées dans Elasticsearch peuvent être à nouveau dérivées d'autres sources de données, notamment PostgreSQL et Gitaly. Si la banque de données Elasticsearch est corrompue, vous pouvez tout réindexer depuis le début.

Si votre index Elasticsearch est trop volumineux, la réindexation complète depuis le début peut entraîner trop de temps d'arrêt. Vous ne pouvez pas automatiquement trouver des écarts et resynchroniser un index Elasticsearch, mais vous pouvez inspecter les journaux pour détecter les mises à jour manquantes. Pour récupérer les données plus rapidement, vous pouvez rejouer :

1. Toutes les mises à jour non-dépôt synchronisées en recherchant dans elasticsearch.log les entrées track_items. Vous devez renvoyer ces éléments via ::Elastic::ProcessBookkeepingService.track!.
2. Toutes les mises à jour du dépôt en recherchant dans elasticsearch.log les entrées indexing_commit_range. Vous devez définir IndexStatus#last_commit/last_wiki_commit sur le from_sha le plus ancien dans les journaux, puis déclencher une autre indexation du projet avec Search::Elastic::CommitIndexerWorker et ElasticWikiIndexerWorker.
3. Toutes les suppressions de projets en recherchant dans sidekiq.log les entrées ElasticDeleteProjectWorker. Vous devez déclencher un autre ElasticDeleteProjectWorker.

Vous pouvez également effectuer des snapshots Elasticsearch réguliers pour réduire le temps nécessaire à la récupération après une perte de données sans tout réindexer depuis le début.