doc-locale/fr-fr/administration/backup_restore/restore_gitlab.md
{{< details >}}
{{< /details >}}
Les opérations de restauration GitLab récupèrent les données des sauvegardes pour maintenir la continuité du système et se remettre d'une perte de données. Opérations de restauration :
Le processus de restauration nécessite une installation GitLab existante de la même version que la sauvegarde. Suivez les prérequis et testez le processus de restauration complet avant de l'utiliser en production.
Vous devez disposer d'une installation GitLab fonctionnelle avant de pouvoir effectuer une restauration. En effet, l'utilisateur système qui effectue les actions de restauration (git) n'est généralement pas autorisé à créer ou supprimer la base de données SQL nécessaire pour importer les données (gitlabhq_production).
Le processus de restauration gère les données existantes différemment selon le type de données :
Pour un processus de restauration fiable, par exemple lors de l'automatisation des restaurations de production vers la pré-production, utilisez une nouvelle installation GitLab à la même version que la sauvegarde.
La restauration des données SQL ignore les vues appartenant aux extensions PostgreSQL.
Vous pouvez uniquement restaurer une sauvegarde vers exactement la même version et le même type (CE ou EE) de GitLab sur lesquels elle a été créée. Par exemple, CE 15.1.4.
Si votre sauvegarde est d'une version différente de l'installation actuelle, vous devez rétrograder ou mettre à niveau votre installation GitLab avant de restaurer la sauvegarde.
Pour restaurer une sauvegarde, vous devez également restaurer les secrets GitLab. Si vous migrez vers une nouvelle instance GitLab, vous devez copier le fichier des secrets GitLab depuis l'ancien serveur. Ceux-ci comprennent la clé de chiffrement de la base de données, les variables CI/CD et les variables utilisées pour l'authentification à deux facteurs. Sans les clés, plusieurs problèmes surviennent, notamment la perte d'accès des utilisateurs ayant activé l'authentification à deux facteurs, et les GitLab Runners ne peuvent pas se connecter.
[!warning] WebAuthn devices are disabled when restoring to a different FQDN: Les enregistrements WebAuthn (tels que les YubiKeys) sont cryptographiquement liés à l'origine (domaine/nom d'hôte) où ils ont été créés. Si vous restaurez une sauvegarde vers une instance GitLab avec un FQDN différent de l'instance d'origine, tous les appareils WebAuthn seront désactivés. Les utilisateurs devront réenregistrer leurs appareils WebAuthn une fois la restauration terminée.
Pour plus d'informations sur WebAuthn et les exigences relatives aux noms d'hôte, voir Authentification à deux facteurs.
Selon votre méthode d'installation, restaurez les éléments suivants :
{{< tabs >}}
{{< tab title="Paquet Linux" >}}
/etc/gitlab/gitlab-secrets.json
{{< /tab >}}
{{< tab title="Helm chart (Kubernetes)" >}}
Les secrets du Helm chart GitLab peuvent être convertis au format de paquet Linux, si nécessaire.
{{< /tab >}}
{{< tab title="Docker" >}}
Si vous avez monté /etc/gitlab sous /srv/gitlab/config :
/srv/gitlab/config/gitlab-secrets.json
{{< /tab >}}
{{< tab title="Compilé manuellement (source)" >}}
/home/git/gitlab/.secret
{{< /tab >}}
{{< /tabs >}}
Voir aussi :
Vous souhaiterez probablement restaurer séparément votre précédent /etc/gitlab/gitlab.rb (pour les installations avec paquet Linux) ou /home/git/gitlab/config/gitlab.yml (pour les installations compilées manuellement) ainsi que tous les certificats et clés TLS ou SSH.
Certaines configurations sont couplées aux données dans PostgreSQL. Par exemple :
default, my-storage-1 et my-storage-2), l'environnement cible doit également avoir au moins ces noms de stockage définis dans la configuration.Pour plus d'informations, voir Données non incluses dans la sauvegarde.
Si vous restaurez dans des répertoires qui sont des points de montage, vous devez vous assurer que ces répertoires sont vides avant de tenter une restauration. Sinon, GitLab tente de déplacer ces répertoires avant de restaurer les nouvelles données, ce qui provoque une erreur.
En savoir plus sur la configuration des montages NFS.
Cette procédure suppose que :
sudo gitlab-ctl reconfigure au moins une fois.sudo gitlab-ctl start.Assurez-vous d'abord que votre fichier tar de sauvegarde se trouve dans le répertoire de sauvegarde décrit dans la configuration gitlab.rb gitlab_rails['backup_path']. La valeur par défaut est /var/opt/gitlab/backups. Le fichier de sauvegarde doit appartenir à l'utilisateur git.
sudo cp 11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar /var/opt/gitlab/backups/
sudo chown git:git /var/opt/gitlab/backups/11493107454_2018_04_25_10.6.4-ce_gitlab_backup.tar
Arrêtez les processus connectés à la base de données. Laissez le reste de GitLab en cours d'exécution :
sudo gitlab-ctl stop puma
sudo gitlab-ctl stop sidekiq
# Verify
sudo gitlab-ctl status
Ensuite, assurez-vous d'avoir effectué les étapes des prérequis de restauration et d'avoir exécuté gitlab-ctl reconfigure après avoir copié le fichier des secrets GitLab de l'installation d'origine.
Ensuite, restaurez la sauvegarde en spécifiant l'ID de la sauvegarde que vous souhaitez restaurer :
[!warning] La commande suivante écrase le contenu de votre base de données GitLab !
# NOTE: "_gitlab_backup.tar" is omitted from the name
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
Si la version de GitLab ne correspond pas entre votre fichier tar de sauvegarde et la version installée de GitLab, la commande de restauration s'interrompt avec un message d'erreur :
GitLab version mismatch:
Your current GitLab version (16.5.0-ee) differs from the GitLab version in the backup!
Please switch to the following version and try again:
version: 16.4.3-ee
Installez la version correcte de GitLab, puis réessayez.
[!warning] La commande de restauration nécessite des paramètres supplémentaires lorsque votre installation utilise PgBouncer, que ce soit pour des raisons de performances ou lors de son utilisation avec un cluster Patroni.
Exécutez reconfigure sur le nœud PostgreSQL :
sudo gitlab-ctl reconfigure
Ensuite, démarrez et vérifiez GitLab :
sudo gitlab-ctl start
sudo gitlab-rake gitlab:check SANITIZE=true
Vérifiez que les valeurs de la base de données peuvent être déchiffrées, surtout si /etc/gitlab/gitlab-secrets.json a été restauré, ou si un serveur différent est la cible de la restauration.
sudo gitlab-rake gitlab:doctor:secrets
Pour plus de sécurité, vous pouvez effectuer une vérification d'intégrité sur les fichiers téléversés :
sudo gitlab-rake gitlab:artifacts:check
sudo gitlab-rake gitlab:lfs:check
sudo gitlab-rake gitlab:uploads:check
Une fois la restauration terminée, il est recommandé de générer des statistiques de base de données pour améliorer les performances de la base de données et éviter les incohérences dans l'interface utilisateur :
Accédez à la console de base de données.
Exécutez ce qui suit :
SET STATEMENT_TIMEOUT=0 ; ANALYZE VERBOSE;
Des discussions sont en cours concernant l'intégration de la commande dans la commande de restauration, voir le ticket 276184 pour plus de détails.
Guides de vérification post-restauration :
Pour les installations GitLab utilisant l'image Docker ou le Helm chart GitLab sur un cluster Kubernetes, la tâche de restauration s'attend à ce que les répertoires de restauration soient vides. Cependant, avec les montages de volumes Docker et Kubernetes, certains répertoires système peuvent être créés à la racine des volumes, comme le répertoire lost+found présent dans les systèmes d'exploitation Linux. Ces répertoires appartiennent généralement à root, ce qui peut entraîner des erreurs de permission d'accès car la tâche Rake de restauration s'exécute en tant qu'utilisateur git. Pour restaurer une installation GitLab, les utilisateurs doivent confirmer que les répertoires cibles de restauration sont vides.
Pour ces deux types d'installation, l'archive tar de sauvegarde doit être disponible dans l'emplacement de sauvegarde (l'emplacement par défaut est /var/opt/gitlab/backups).
Le Helm chart GitLab utilise le processus documenté dans la restauration d'une installation GitLab avec Helm chart
Si vous utilisez Docker Swarm, le conteneur peut redémarrer pendant le processus de restauration car Puma est arrêté, et par conséquent la vérification de l'état du conteneur échoue. Pour contourner ce problème, désactivez temporairement le mécanisme de vérification de l'état.
Modifiez docker-compose.yml :
healthcheck:
disable: true
Déployez la pile :
docker stack deploy --compose-file docker-compose.yml mystack
Pour plus d'informations, voir ticket 6846.
La tâche de restauration peut être exécutée depuis l'hôte :
# Stop the processes that are connected to the database
docker exec -it <name of container> gitlab-ctl stop puma
docker exec -it <name of container> gitlab-ctl stop sidekiq
# Verify that the processes are all down before continuing
docker exec -it <name of container> gitlab-ctl status
# Run the restore. NOTE: "_gitlab_backup.tar" is omitted from the name
docker exec -it <name of container> gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
# Restart the GitLab container
docker restart <name of container>
# Check GitLab
docker exec -it <name of container> gitlab-rake gitlab:check SANITIZE=true
Assurez-vous d'abord que votre fichier tar de sauvegarde se trouve dans le répertoire de sauvegarde décrit dans la configuration gitlab.yml :
## Backup settings
backup:
path: "tmp/backups" # Relative paths are relative to Rails.root (default: tmp/backups/)
La valeur par défaut est /home/git/gitlab/tmp/backups, et elle doit appartenir à l'utilisateur git.
Commencez la procédure de sauvegarde :
# Stop processes that are connected to the database
sudo service gitlab stop
sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production
Exemple de sortie :
Unpacking backup... [DONE]
Restoring database tables:
-- create_table("events", {:force=>true})
-> 0.2231s
[...]
- Loading fixture events...[DONE]
- Loading fixture issues...[DONE]
- Loading fixture keys...[SKIPPING]
- Loading fixture merge_requests...[DONE]
- Loading fixture milestones...[DONE]
- Loading fixture namespaces...[DONE]
- Loading fixture notes...[DONE]
- Loading fixture projects...[DONE]
- Loading fixture protected_branches...[SKIPPING]
- Loading fixture schema_migrations...[DONE]
- Loading fixture services...[SKIPPING]
- Loading fixture snippets...[SKIPPING]
- Loading fixture taggings...[SKIPPING]
- Loading fixture tags...[SKIPPING]
- Loading fixture users...[DONE]
- Loading fixture users_projects...[DONE]
- Loading fixture web_hooks...[SKIPPING]
- Loading fixture wikis...[SKIPPING]
Restoring repositories:
- Restoring repository abcd... [DONE]
- Object pool 1 ...
Deleting tmp directories...[DONE]
Restaurez /home/git/gitlab/.secret si nécessaire.
Redémarrez GitLab :
sudo service gitlab restart
Bien que la tâche Rake utilisée pour restaurer une instance GitLab ne prenne pas en charge la restauration d'un seul projet ou groupe, vous pouvez utiliser une solution de contournement en restaurant votre sauvegarde vers une instance GitLab temporaire distincte, puis en exportant votre projet ou groupe depuis celle-ci :
Une demande de fonctionnalité pour fournir une restauration directe de projets ou de groupes individuels est en cours de discussion dans le ticket #17517.
Lorsque vous créez une sauvegarde incrémentielle de dépôt à l'aide de gitlab-backup, l'archive de sauvegarde résultante contient toutes les données de dépôt nécessaires pour une restauration complète. Pour restaurer, utilisez les mêmes instructions que pour la restauration de toute autre archive de sauvegarde ordinaire.
En interne, les sauvegardes incrémentielles de dépôt ne stockent que les modifications apportées depuis la sauvegarde précédente. Lorsque vous créez une sauvegarde incrémentielle, gitlab-backup regroupe toutes les étapes depuis la sauvegarde complète d'origine dans l'archive de sauvegarde. Cela signifie que l'archive est autonome, même si les bundles de sauvegarde de dépôt individuels dépendent les uns des autres.
Avec les sauvegardes de dépôt côté serveur, l'archive de sauvegarde ne contient pas de données de dépôt. Au lieu de cela, les données de dépôt sont stockées dans le stockage objet par chaque nœud Gitaly, et chaque incrément est stocké en tant qu'objet distinct. Lors d'une restauration côté serveur, Gitaly lit le manifeste de sauvegarde et applique chaque incrément dans l'ordre.
[!warning] Ne supprimez pas les fichiers de sauvegarde incrémentielle du stockage objet. Si un fichier intermédiaire est supprimé (par exemple, via une politique de cycle de vie du stockage objet), la chaîne de sauvegarde est rompue et la sauvegarde ne peut pas être restaurée.
L'outil en ligne de commande fourni par GitLab pour restaurer depuis une sauvegarde peut accepter plus d'options.
Les fichiers de sauvegarde utilisent un schéma de nommage commençant par un ID de sauvegarde. Lorsqu'il existe plusieurs sauvegardes, vous devez spécifier quel fichier <backup-id>_gitlab_backup.tar restaurer en définissant la variable d'environnement BACKUP=<backup-id>.
Lors d'une restauration depuis une sauvegarde, le script de restauration demande une confirmation :
<!-- vale gitlab_base.Spelling = NO -->authorized_keys.Pour désactiver ces invites, définissez la variable d'environnement GITLAB_ASSUME_YES à 1.
Installations avec paquet Linux :
sudo GITLAB_ASSUME_YES=1 gitlab-backup restore
Installations compilées manuellement :
sudo -u git -H GITLAB_ASSUME_YES=1 bundle exec rake gitlab:backup:restore RAILS_ENV=production
La variable d'environnement force=yes désactive également ces invites.
Vous pouvez exclure des tâches spécifiques lors de la restauration en ajoutant la variable d'environnement SKIP, dont les valeurs sont une liste séparée par des virgules des options suivantes :
db (base de données)uploads (pièces jointes)builds (journaux de sortie des jobs CI)artifacts (artefacts de job CI)lfs (objets LFS)terraform_state (états Terraform)registry (images du registre de conteneurs)pages (contenu Pages)repositories (données des dépôts Git)packages (Packages)Pour exclure des tâches spécifiques :
Installations avec paquet Linux :
sudo gitlab-backup restore BACKUP=<backup-id> SKIP=db,uploads
Installations compilées manuellement :
sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> SKIP=db,uploads RAILS_ENV=production
{{< history >}}
{{< /history >}}
[!warning] GitLab 17.1 et antérieur sont affectés par une condition de course pouvant entraîner une perte de données. Le problème affecte les dépôts qui ont été dupliqués et utilisent les pools d'objets GitLab. Pour éviter toute perte de données, restaurez uniquement les sauvegardes en utilisant GitLab 17.2 ou une version ultérieure.
Lors de l'utilisation de plusieurs stockages de dépôts, les dépôts de stockages de dépôts spécifiques peuvent être restaurés séparément à l'aide de l'option REPOSITORIES_STORAGES. L'option accepte une liste de noms de stockage séparés par des virgules.
Par exemple :
Installations avec paquet Linux :
sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2
Installations compilées manuellement :
sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_STORAGES=storage1,storage2
{{< history >}}
{{< /history >}}
[!warning] GitLab 17.1 et antérieur sont affectés par une condition de course pouvant entraîner une perte de données. Le problème affecte les dépôts qui ont été dupliqués et utilisent les pools d'objets GitLab. Pour éviter toute perte de données, restaurez uniquement les sauvegardes en utilisant GitLab 17.2 ou une version ultérieure.
Vous pouvez restaurer des dépôts spécifiques à l'aide des options REPOSITORIES_PATHS et SKIP_REPOSITORIES_PATHS. Les deux options acceptent une liste de chemins de projet et de groupe séparés par des virgules. Si vous spécifiez un chemin de groupe, tous les dépôts de tous les projets du groupe et des groupes descendants sont inclus ou ignorés, selon l'option utilisée. Les groupes et les projets doivent exister dans la sauvegarde spécifiée ou sur l'instance cible.
[!note] Les options
REPOSITORIES_PATHSetSKIP_REPOSITORIES_PATHSs'appliquent uniquement aux dépôts Git. Elles ne s'appliquent pas aux entrées de base de données de projet ou de groupe. Si vous avez créé une sauvegarde de dépôts avecSKIP=db, elle ne peut pas être utilisée seule pour restaurer des dépôts spécifiques vers une nouvelle instance.
Par exemple, pour restaurer tous les dépôts de tous les projets du Groupe A (group-a), le dépôt du Projet C dans le Groupe B (group-b/project-c), et ignorer le Projet D dans le Groupe A (group-a/project-d) :
Installations avec paquet Linux :
sudo gitlab-backup restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
Installations compilées manuellement :
sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=<backup-id> REPOSITORIES_PATHS=group-a,group-b/project-c SKIP_REPOSITORIES_PATHS=group-a/project-d
Si une sauvegarde non archivée (créée avec SKIP=tar) est trouvée et qu'aucune sauvegarde n'est choisie avec BACKUP=<backup-id>, la sauvegarde non archivée est utilisée.
Par exemple :
Installations avec paquet Linux :
sudo gitlab-backup restore
Installations compilées manuellement :
sudo -u git -H bundle exec rake gitlab:backup:restore
{{< history >}}
gitlab-backup dans GitLab 16.3.gitlab-backup pour la restauration d'une sauvegarde spécifiée plutôt que la dernière sauvegarde introduite dans GitLab 16.6.gitlab-backup pour la création de sauvegardes incrémentielles introduite dans GitLab 16.6.backup-utility introduite dans GitLab 17.0.{{< /history >}}
Lorsqu'une sauvegarde côté serveur est collectée, le processus de restauration utilise par défaut le mécanisme de restauration côté serveur présenté dans Créer des sauvegardes de dépôts côté serveur. Vous pouvez configurer la restauration des sauvegardes de sorte que le nœud Gitaly qui héberge chaque dépôt soit responsable d'extraire les données de sauvegarde nécessaires directement depuis le stockage objet.
{{< tabs >}}
{{< tab title="Paquet Linux (Omnibus)" >}}
sudo gitlab-backup restore BACKUP=11493107454_2018_04_25_10.6.4-ce
{{< /tab >}}
{{< tab title="Compilé manuellement" >}}
sudo -u git -H bundle exec rake gitlab:backup:restore BACKUP=11493107454_2018_04_25_10.6.4-ce
{{< /tab >}}
{{< tab title="Helm chart (Kubernetes)" >}}
kubectl exec <Toolbox pod name> -it -- backup-utility --restore -t <backup_ID> --repositories-server-side
Lors de l'utilisation des sauvegardes basées sur cron, ajoutez le drapeau --repositories-server-side aux arguments supplémentaires.
{{< /tab >}}
{{< /tabs >}}
Voici les problèmes possibles que vous pourriez rencontrer, ainsi que les solutions potentielles.
Si vous utilisez des procédures de restauration de sauvegarde, vous pouvez rencontrer les messages d'avertissement suivants :
ERROR: must be owner of extension pg_trgm
ERROR: must be owner of extension btree_gist
ERROR: must be owner of extension plpgsql
WARNING: no privileges could be revoked for "public" (two occurrences)
WARNING: no privileges were granted for "public" (two occurrences)
Sachez que la sauvegarde est restaurée avec succès malgré ces messages d'avertissement.
La tâche Rake s'exécute en tant qu'utilisateur gitlab, qui ne dispose pas d'un accès superutilisateur à la base de données. Lorsque la restauration est initiée, elle s'exécute également en tant qu'utilisateur gitlab, mais elle tente également de modifier les objets auxquels elle n'a pas accès. Ces objets n'ont aucune influence sur la sauvegarde ou la restauration de la base de données, mais affichent un message d'avertissement.
Pour plus d'informations, voir :
Lors de la restauration depuis une sauvegarde, vous pouvez rencontrer une erreur lorsque les conditions suivantes sont vraies :
custom_hook) est configuré à l'aide de la méthode pour GitLab version 15.10 et antérieureL'erreur ressemble à :
{"level":"fatal","msg":"restore: pipeline: 1 failures encountered:\n - @hashed/path/to/hashed_repository.git (path/to_project): manager: restore custom hooks, \"@hashed/path/to/hashed_repository/<BackupID>_<GitLabVersion>-ee/001.custom_hooks.tar\": rpc error: code = Internal desc = setting custom hooks: generating prepared vote: walking directory: copying file to hash: read /mnt/gitlab-app/git-data/repositories/+gitaly/tmp/default-repositories.old.<timestamp>.<temporaryfolder>/custom_hooks/compliance-triggers.d: is a directory\n","pid":3256017,"time":"2023-08-10T20:09:44.395Z"}
Pour résoudre ce problème, vous pouvez mettre à jour les hooks de serveur Git pour GitLab version 15.11 et ultérieure, et créer une nouvelle sauvegarde.
fapolicyd {#successful-restore-with-repositories-showing-as-empty-when-using-fapolicyd}Lors de l'utilisation de fapolicyd pour une sécurité accrue, GitLab peut indiquer que la restauration a réussi, mais les dépôts s'affichent comme vides. Pour plus d'aide sur la résolution des problèmes, consultez la documentation de dépannage de Gitaly.