doc-locale/fr-fr/administration/gitaly/praefect/troubleshooting.md
{{< details >}}
{{< /details >}}
Reportez-vous aux informations ci-dessous pour résoudre les problèmes du cluster Gitaly (Praefect). Pour plus d'informations sur le dépannage de Gitaly, consultez Dépannage de Gitaly.
Vous devez disposer d'un accès administrateur.
La sous-commande Praefect check exécute une série de vérifications pour déterminer l'intégrité du cluster Gitaly (Praefect).
gitlab-ctl praefect check
Si Praefect est déployé à l'aide du chart Praefect, exécutez directement le binaire.
/usr/local/bin/praefect check
Les sections suivantes décrivent les vérifications effectuées.
Étant donné que les migrations de base de données doivent être à jour pour que Praefect fonctionne correctement, vérifie si les migrations Praefect sont à jour.
Si cette vérification échoue :
schema_migrations dans la base de données pour voir quelles migrations ont été exécutées.praefect sql-migrate pour mettre les migrations à jour.Vérifie si Praefect peut atteindre tous ses nœuds Gitaly, et si chaque nœud Gitaly dispose d'un accès en lecture et en écriture à tous ses stockages.
Si cette vérification échoue :
gitaly est exécuté en tant que git. Il peut y avoir un problème de permissions empêchant Gitaly d'accéder à ses répertoires de stockage.Vérifie si Praefect peut lire et écrire dans la base de données.
Si cette vérification échoue :
Vérifiez si la base de données Praefect est en mode de récupération. En mode de récupération, les tables peuvent être en lecture seule. Pour vérifier, exécutez :
select pg_is_in_recovery()
Confirmez que l'utilisateur que Praefect utilise pour se connecter à PostgreSQL dispose d'un accès en lecture et en écriture à la base de données.
Vérifiez si la base de données a été placée en mode lecture seule. Pour vérifier, exécutez :
show default_transaction_read_only
Vérifie combien de dépôts sont inaccessibles parce qu'il leur manque une affectation primaire, ou parce que leur nœud primaire est indisponible.
Si cette vérification échoue :
praefect ping-nodes pour vérifier.Si vous recevez une erreur, consultez /var/log/gitlab/gitlab-rails/production.log.
Voici les erreurs courantes et leurs causes potentielles :
ActionView::Template::Error (7:permission denied)
praefect['configuration'][:auth][:token] et gitlab_rails['gitaly_token'] ne correspondent pas sur le serveur GitLab.gitlab_rails['repositories_storages'] est manquante sur le serveur Sidekiq.Unable to save project. Error: 7:permission denied
praefect['configuration'][:virtual_storage] sur le serveur GitLab ne correspond pas à la valeur dans gitaly['auth_token'] sur un ou plusieurs serveurs Gitaly.GRPC::Unavailable (14:failed to connect to all addresses)
GRPC::Unavailable (14:all SubCons are in TransientFailure...)
Voici quelques raisons courantes pour lesquelles la base de données Praefect peut subir une utilisation élevée du CPU :
praefect['configuration'][:prometheus_exclude_database_from_default_metrics] = true dans gitlab.rb.Pour déterminer le nœud primaire d'un dépôt, utilisez la sous-commande praefect metadata.
Gitaly Cluster (Praefect) gère une base de données de métadonnées contenant des informations sur les dépôts stockés dans le cluster. Utilisez la sous-commande praefect metadata pour inspecter les métadonnées à des fins de dépannage.
Vous pouvez récupérer les métadonnées d'un dépôt de l'une des manières suivantes :
{{< tabs >}}
{{< tab title="Stockage virtuel et chemin relatif" >}}
Pour récupérer les métadonnées d'un dépôt à partir de son stockage virtuel et de son chemin relatif :
Dans le coin supérieur droit, sélectionnez Admin.
Dans la barre latérale gauche, sélectionnez Vue d'ensemble > Projets et sélectionnez le projet.
Notez les valeurs de Nom de stockage et Chemin relatif pour le projet.
Avec ces valeurs, exécutez la commande suivante :
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -virtual-storage <virtual-storage> -relative-path <relative-path>
{{< /tab >}}
{{< tab title="ID de dépôt attribué par Praefect" >}}
[!note] Un ID de dépôt n'est pas identique à un ID de projet.
Pour récupérer les métadonnées d'un dépôt à partir de son ID de dépôt attribué par Praefect :
Notez le dernier composant du chemin de réplique du dépôt. Par exemple, pour @cluster/repositories/6f/96/54771, l'ID du dépôt est 54771.
Avec cette valeur, exécutez la commande suivante :
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -repository-id <repository-id>
{{< /tab >}}
{{< /tabs >}}
Pour récupérer les métadonnées d'un dépôt avec le stockage virtuel default et le chemin relatif @hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git :
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -virtual-storage default -relative-path @hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git
Pour récupérer les métadonnées d'un dépôt avec un ID de dépôt attribué par Praefect égal à 1 :
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml metadata -repository-id 1
L'un ou l'autre de ces exemples récupère les métadonnées suivantes pour un exemple de dépôt :
Repository ID: 54771
Virtual Storage: "default"
Relative Path: "@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git"
Replica Path: "@hashed/b1/7e/b17ef6d19c7a5b1ee83b907c595526dcb1eb06db8227d650d5dda0a9f4ce8cd9.git"
Primary: "gitaly-1"
Generation: 1
Replicas:
- Storage: "gitaly-1"
Assigned: true
Generation: 1, fully up to date
Healthy: true
Valid Primary: true
Verified At: 2021-04-01 10:04:20 +0000 UTC
- Storage: "gitaly-2"
Assigned: true
Generation: 0, behind by 1 changes
Healthy: true
Valid Primary: false
Verified At: unverified
- Storage: "gitaly-3"
Assigned: true
Generation: replica not yet created
Healthy: false
Valid Primary: false
Verified At: unverified
Les métadonnées récupérées par praefect metadata incluent les champs des tableaux suivants.
| Champ | Description |
|---|---|
Repository ID | ID unique permanent attribué au dépôt par Praefect. Différent de l'ID que GitLab utilise pour les dépôts. |
Virtual Storage | Nom du stockage virtuel dans lequel le dépôt est stocké. |
Relative Path | Chemin du dépôt dans le stockage virtuel. |
Replica Path | Emplacement sur le disque du nœud Gitaly où sont stockées les répliques du dépôt. |
Primary | Nœud primaire actuel du dépôt. |
Generation | Utilisé par Praefect pour suivre les modifications du dépôt. Chaque écriture dans le dépôt incrémente la génération du dépôt. |
Replicas | Liste des répliques qui existent ou dont l'existence est prévue. |
Pour chaque réplique, les métadonnées suivantes sont disponibles :
Champ Replicas | Description |
|---|---|
Storage | Nom du stockage Gitaly contenant la réplique. |
Assigned | Indique si la réplique est supposée exister dans le stockage. Peut être false si un nœud Gitaly est supprimé du cluster ou si le stockage contient une copie supplémentaire après que le facteur de réplication du dépôt a été diminué. |
Generation | Dernière génération confirmée de la réplique. Elle indique : |
- La réplique est entièrement à jour si la génération correspond à celle du dépôt. - La réplique est obsolète si la génération de la réplique est inférieure à celle du dépôt.
replica not yet created si la réplique n'existe pas encore du tout dans le stockage. |
| Healthy | Indique si le nœud Gitaly hébergeant cette réplique est considéré comme sain par le consensus des nœuds Praefect. |
| Valid Primary | Indique si la réplique est apte à servir de nœud primaire. Si le nœud primaire du dépôt n'est pas un nœud primaire valide, un basculement se produit lors de la prochaine écriture dans le dépôt s'il existe une autre réplique qui est un nœud primaire valide. Une réplique est un nœud primaire valide si :- Elle est stockée sur un nœud Gitaly sain.
- Elle est entièrement à jour.
- Elle n'est pas ciblée par un job de suppression en attente résultant d'une diminution du facteur de réplication.
- Elle est assignée. |
| Verified At | Indique la dernière vérification réussie de la réplique par le worker de vérification. Si la réplique n'a pas encore été vérifiée, unverified est affiché à la place de l'heure de la dernière vérification réussie. |
Si la valeur fournie pour -virtual-storage est incorrecte, la commande renvoie l'erreur suivante :
get metadata: rpc error: code = NotFound desc = repository not found
Les exemples documentés spécifient -virtual-storage default. Vérifiez le paramètre serveur Praefect praefect['configuration'][:virtual_storage] dans /etc/gitlab/gitlab.rb.
Dans certains cas, la base de données Praefect peut se désynchroniser avec les nœuds Gitaly sous-jacents. Pour vérifier qu'un dépôt donné est entièrement synchronisé sur tous les nœuds, exécutez la tâche Rake gitlab:praefect:replicas sur votre nœud Rails. Cette tâche Rake calcule la somme de contrôle du dépôt sur tous les nœuds Gitaly.
La commande Praefect dataloss vérifie uniquement l'état du dépôt dans la base de données Praefect et ne peut pas être utilisée pour détecter les problèmes de synchronisation dans ce scénario.
dataloss affiche les dépôts @failed-geo-sync comme non synchronisés {#dataloss-command-shows-failed-geo-sync-repositories-as-out-of-sync}@failed-geo-sync est un chemin hérité utilisé sur GitLab 16.1 et versions antérieures par Geo lorsque la synchronisation du projet échouait et a été déprécié.
Sur GitLab 16.2 et versions ultérieures, vous pouvez supprimer ce chemin en toute sécurité. Les répertoires @failed-geo-sync se trouvent sous le chemin du dépôt sur les nœuds Gitaly.
Par défaut, les tables de la base de données Praefect sont créées automatiquement par la tâche gitlab-ctl reconfigure.
Cependant, les tables de la base de données Praefect ne sont pas créées lors de la reconfiguration initiale et peuvent générer des erreurs indiquant que des relations n'existent pas, si l'une des conditions suivantes s'applique :
gitlab-ctl reconfigure n'est pas exécutée.Par exemple :
ERROR: relation "node_status" does not exist at character 13
ERROR: relation "replication_queue_lock" does not exist at character 40
Cette erreur :
{"level":"error","msg":"Error updating node: pq: relation \"node_status\" does not exist","pid":210882,"praefectName":"gitlab1x4m:0.0.0.0:2305","time":"2021-04-01T19:26:19.473Z","virtual_storage":"praefect-cluster-1"}
Pour résoudre ce problème, la migration du schéma de base de données peut être effectuée à l'aide de la sous-commande sql-migrate de la commande praefect :
$ sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-migrate
praefect sql-migrate: OK (applied 21 migrations)
Cela indique que le nom de stockage virtuel utilisé dans la configuration Praefect ne correspond pas au nom de stockage utilisé dans le paramètre gitaly['configuration'][:storage][<index>][:name] pour GitLab.
Résolvez ce problème en faisant correspondre les noms de stockage virtuel utilisés dans les configurations Praefect et GitLab.
Praefect ne nécessite pas beaucoup de CPU ni de mémoire, et peut s'exécuter sur de petites machines virtuelles. Les services cloud peuvent imposer d'autres limites sur les ressources que les petites machines virtuelles peuvent utiliser, comme les entrées/sorties disque et le trafic réseau.
Les nœuds Praefect génèrent beaucoup de trafic réseau. Les symptômes suivants peuvent être observés si leur bande passante réseau a été limitée par le service cloud :
Solutions possibles :
gitlab-ctl reconfigure échoue avec une erreur de configuration Praefect {#gitlab-ctl-reconfigure-fails-with-a-praefect-configuration-error}Si gitlab-ctl reconfigure échoue, vous pourriez voir cette erreur :
STDOUT: praefect: configuration error: error reading config file: toml: cannot store TOML string into a Go int
Cette erreur se produit lorsque praefect['database_port'] ou praefect['database_direct_port'] sont configurés sous forme de chaîne de caractères au lieu d'un entier.
Voici quelques erreurs de réplication courantes avec des solutions possibles.
Les fichiers de verrouillage sont utilisés pour empêcher plusieurs mises à jour de la même référence. Parfois, les fichiers de verrouillage deviennent obsolètes et la réplication échoue avec l'erreur error: cannot lock ref.
Pour effacer les fichiers *.lock obsolètes, vous pouvez déclencher OptimizeRepositoryRequest sur la console Rails :
p = Project.find <Project ID>
client = Gitlab::GitalyClient::RepositoryService.new(p.repository)
client.optimize_repository
Si le déclenchement de OptimizeRepositoryRequest ne fonctionne pas, inspectez les fichiers manuellement pour confirmer la date de création et décider si le fichier *.lock peut être supprimé manuellement. Tout fichier de verrouillage créé il y a plus de 24 heures peut être supprimé en toute sécurité.
fsck {#git-fsck-errors}Les dépôts Gitaly contenant des objets invalides peuvent entraîner des échecs de réplication avec des erreurs dans les journaux Gitaly tels que :
exit status 128, stderr: "fatal: git upload-pack: not our ref"."fatal: bad object 58....e0f... ssh://gitaly/internal.git did not send all necessary objects.Tant qu'un des nœuds Gitaly dispose encore d'une copie saine du dépôt, ces problèmes peuvent être résolus en :
track-repository pour le retracer.La copie du dépôt du nœud Gitaly faisant autorité sera utilisée pour écraser les copies sur tous les autres nœuds Gitaly. Assurez-vous qu'une sauvegarde récente du dépôt a été effectuée avant d'exécuter ces commandes.
Déplacez le mauvais dépôt hors de son emplacement :
run `mv <REPOSITORY_PATH> <REPOSITORY_PATH>.backup`
Par exemple :
mv /var/opt/gitlab/git-data/repositories/@cluster/repositories/de/74/2335 /var/opt/gitlab/git-data/repositories/@cluster/repositories/de/74/2335.backup
Exécutez les commandes Praefect pour déclencher la réplication :
# Validate you have the correct repository.
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml remove-repository -virtual-storage gitaly -relative-path '<relative_path>' -db-only
# Run again with '--apply' flag to remove repository from the Praefect tracking database
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml remove-repository -virtual-storage gitaly -relative-path '<relative_path>' -db-only --apply
# Re-track the repository, overwriting the secondary nodes
sudo -u git -- /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml track-repository -virtual-storage gitaly -authoritative-storage '<healthy_gitaly>' -relative-path '<relative_path>' -replica-path '<replica_path>'-replicate-immediately
Si le Praefect dataloss affiche des dépôts partiellement indisponibles, et que la commande accept-dataloss ne parvient pas à synchroniser le dépôt sans qu'aucune erreur ne soit présente dans les journaux, cela peut être dû à une incohérence dans la base de données Praefect dans le champ repository_id de la table storage_repositories. Pour vérifier l'existence d'une incohérence :
Connectez-vous à la base de données Praefect.
Exécutez la requête suivante :
select * from storage_repositories where relative_path = '<relative-path>';
Remplacez <relative-path> par le chemin du dépôt commençant par @hashed.
GitLab utilise le mécanisme d'alternates Git pour la déduplication. alternates est un fichier texte qui pointe vers le répertoire objects d'un dépôt @pool pour récupérer les objets. Si ce fichier pointe vers un chemin invalide, la réplication peut échouer avec l'une des erreurs suivantes :
"error":"no alternates directory exists", "warning","msg":"alternates file does not point to valid git repository""error":"unexpected alternates content:remote: error: unable to normalize alternate object pathPour analyser la cause de cette erreur :
Vérifiez si le projet fait partie d'un pool en utilisant la console Rails :
project = Project.find_by_id(<project id>)
project.pool_repository
Vérifiez si le chemin du dépôt pool existe sur le disque et qu'il correspond au contenu du fichier alternates.
Vérifiez si le chemin dans le fichier alternates est accessible depuis le répertoire objects dans le projet.
Après avoir effectué ces vérifications, contactez le support GitLab avec les informations collectées.
Lors de l'utilisation de l'Horizontal Pod Autoscaler (HPA) avec des pods Sidekiq, les déplacements de stockage de dépôt peuvent échouer silencieusement en raison de la mise à l'échelle des pods pendant l'exécution du job. Si un déplacement de stockage de dépôt a échoué en raison de ce problème, les projets en échec peuvent rester bloqués dans un état lecture seule.
Pour récupérer les dépôts affectés :