doc-locale/fr-fr/administration/packages/container_registry_metadata_database.md
{{< details >}}
{{< /details >}}
{{< history >}}
{{< /history >}}
La base de données de métadonnées offre plusieurs améliorations au registre de conteneurs qui améliorent les performances et ajoutent de nouvelles fonctionnalités. Le travail sur la release GitLab Self-Managed de la fonctionnalité de base de données de métadonnées du registre est suivi dans l'epic 5521.
Par défaut, le registre de conteneurs utilise le stockage d'objets ou un système de fichiers local pour conserver les métadonnées relatives aux images de conteneurs. Cette méthode de stockage des métadonnées limite l'efficacité de l'accès aux données, en particulier les données couvrant plusieurs images, comme lors de l'affichage des tags. En utilisant une base de données pour stocker ces données, de nombreuses nouvelles fonctionnalités deviennent possibles, notamment la collecte des déchets en ligne qui supprime automatiquement les anciennes données sans temps d'arrêt.
Cette base de données fonctionne conjointement avec le stockage déjà utilisé par le registre, mais ne remplace pas le stockage d'objets ou un système de fichiers. Vous devez continuer à maintenir une solution de stockage même après avoir effectué une importation de métadonnées vers la base de données de métadonnées.
Pour les installations Helm Charts, consultez Gérer la base de données de métadonnées du registre de conteneurs dans la documentation Helm Charts.
L'architecture de la base de données de métadonnées prend en charge les améliorations de performances, les corrections de bugs et les nouvelles fonctionnalités qui ne sont pas disponibles avec le stockage de métadonnées hérité. Ces améliorations comprennent :
En raison des contraintes techniques du stockage de métadonnées hérité, les nouvelles fonctionnalités sont uniquement implémentées pour la version de la base de données de métadonnées. Les corrections de bugs non liées à la sécurité peuvent être limitées à la version de la base de données de métadonnées.
createdAt et publishedAt pour les tags d'image sont définies à la date d'importation. Cela est intentionnel pour garantir la cohérence, car le registre hérité ne collecte pas les dates de publication des tags pour toutes les images. Certaines images ont des dates de build dans leurs métadonnées, mais beaucoup n'en ont pas. Pour plus d'informations, consultez l'issue 1384.Vous pouvez importer des métadonnées des registres existants vers la base de données de métadonnées et utiliser la collecte des déchets en ligne.
Certaines fonctionnalités activées par la base de données ne sont disponibles que pour GitLab.com et le provisionnement automatique de la base de données pour la base de données du registre n'est pas disponible. Consultez le tableau de prise en charge des fonctionnalités dans l'issue de retour pour connaître l'état des fonctionnalités liées à la base de données du registre de conteneurs.
Prérequis :
Pour les installations qui n'ont jamais écrit de données dans le registre de conteneurs, aucune importation n'est requise. Vous devez uniquement activer la base de données avant d'écrire des données dans le registre.
Pour plus d'informations, consultez les instructions pour les nouvelles installations.
Vous pouvez importer vos métadonnées de registre de conteneurs existant en utilisant soit une méthode d'importation en une étape, soit une méthode d'importation en trois étapes. Plusieurs facteurs affectent la durée de l'importation :
Vous n'avez pas besoin d'effectuer les opérations suivantes en préparation avant l'importation :
[!note] L'importation de métadonnées cible uniquement les images taguées. Les manifestes non taguées et non référencés, ainsi que les couches exclusivement référencées par eux, sont laissés derrière et deviennent inaccessibles. Les images non taguées n'ont jamais été visibles via l'interface utilisateur ou l'API GitLab, mais elles peuvent devenir « orphelines » et être laissées derrière dans le backend. Après l'importation vers le nouveau registre, toutes les images sont soumises à la collecte des déchets en ligne continue, qui supprime par défaut tous les manifestes et couches non taguées et non référencés qui restent pendant plus de 24 heures.
Si vous exécutez régulièrement la collecte des déchets hors ligne, utilisez la méthode d'importation en une étape. Cette méthode devrait prendre un temps similaire et est une opération plus simple par rapport à la méthode d'importation en trois étapes.
Si votre registre est trop volumineux pour exécuter régulièrement la collecte des déchets hors ligne, utilisez la méthode d'importation en trois étapes pour minimiser significativement la durée du mode lecture seule.
Si vous utilisez une base de données externe, assurez-vous de configurer la connexion à la base de données externe avant de procéder avec un chemin de migration.
Pour plus d'informations, consultez Utilisation d'une base de données externe.
{{< history >}}
{{< /history >}}
Ignorez les dépôts que vous avez pré-importés au cours des 72 dernières heures pour reprendre les importations interrompues. Les dépôts sont pré-importés soit :
Pour restaurer les importations interrompues, configurez l'indicateur --pre-import-skip-recent. Par défaut à 72 heures.
Par exemple :
# Skip repositories imported within 6 hours from the start of the import command
--pre-import-skip-recent 6h
# Disable skipping behavior
--pre-import-skip-recent 0
Pour plus d'informations sur les unités de durée valides, consultez les chaînes de durée Go.
Après avoir effectué une importation volumineuse, des centaines de milliers, voire des millions de blobs peuvent être mis en file d'attente pour examen par la collecte des déchets. C'est normal.
Comme les images taguées sont importées avant que les blobs orphelins ne soient inventoriés, le ramasse-miettes examine initialement les blobs qui sont encore référencés par des images taguées. La collecte des déchets supprime ces blobs de la file d'attente, mais ne les supprime pas du stockage.
Le stockage ne diminue qu'une fois que le ramasse-miettes atteint les blobs orphelins. Le stockage du registre peut prendre 48 heures ou plus pour diminuer après une post-importation, car le ramasse-miettes retarde l'examen pour éviter toute interférence avec les blobs d'images.
Pour surveiller et gérer le backlog de collecte des déchets post-importation :
{{< history >}}
{{< /history >}}
Le mode Prefer est une option de configuration pour la base de données de métadonnées qui permet au registre de revenir au stockage de métadonnées hérité lorsqu'un registre existant n'a pas encore été importé vers la base de données.
Pour activer le mode Prefer :
Dans /etc/gitlab/gitlab.rb, définissez database.enabled sur "prefer" au lieu de true ou false :
registry['database'] = {
'enabled' => 'prefer',
'host' => '<your_database_host>',
'port' => 5432,
'user' => '<your_database_user>',
'password' => '<your_database_password>',
'dbname' => '<your_database_name>',
}
Enregistrez le fichier et reconfigurez GitLab.
Après avoir reconfiguré GitLab, le registre évalue quel backend de métadonnées utiliser au démarrage en fonction des fichiers de verrouillage qui suivent les écritures précédentes sur le système de fichiers ou la base de données :
enabled: false jusqu'à ce que vous effectuiez une importation de métadonnées.enabled: true.La décision de repli se produit une seule fois au démarrage et ne change pas pendant que le registre est en cours d'exécution. Il n'y a pas de nouvelle tentative automatique ou de reconnexion à la base de données après un repli. Pour passer du mode système de fichiers au mode base de données après un repli, effectuez l'importation de métadonnées standard et redémarrez le registre.
{{< history >}}
prefer dans GitLab 19.0 pour les nouvelles installations de packages Linux et les installations auto-compilées.{{< /history >}}
Dans GitLab 19.0 et versions ultérieures, la base de données de métadonnées est activée par défaut en mode Prefer pour les nouvelles installations :
registry['database']['enabled'] est défini par défaut sur "prefer" lorsque le paramètre n'est pas spécifié dans /etc/gitlab/gitlab.rb. Pour plus d'informations, consultez l'issue 9396.database.enabled est défini par défaut sur "prefer" lorsque le paramètre n'est pas spécifié dans le fichier de configuration du registre.Après la mise à niveau, vérifiez quel backend le registre utilise. Pour la procédure, consultez Vérifier quel backend de métadonnées est actif.
Sur une nouvelle installation de GitLab 19.0 ou ultérieure, le registre démarre en mode Prefer. Si une base de données de métadonnées accessible est configurée, le registre l'utilise. Sans base de données accessible, le registre ne parvient pas à démarrer.
Pour conserver une nouvelle installation sur les métadonnées du système de fichiers, définissez le mode de base de données sur "false" avant le premier démarrage du registre :
Pour les installations de packages Linux (Omnibus), dans /etc/gitlab/gitlab.rb :
registry['database']['enabled'] = "false"
Pour les installations auto-compilées, dans /home/git/gitlab/config/gitlab.yml :
registry:
database:
enabled: false
La mise à niveau d'une installation existante vers GitLab 19.0 ou version ultérieure préserve le paramètre registry['database']['enabled'] actuel. La mise à niveau ne migre pas les métadonnées ni ne change le backend actif.
Une installation existante en mode Prefer avec des métadonnées de système de fichiers continue d'utiliser les métadonnées du système de fichiers après la mise à niveau. Pour passer à la base de données, effectuez une importation de métadonnées.
Lorsque le registre utilise la base de données de métadonnées, incluez la base de données du registre dans vos sauvegardes. Pour la procédure, consultez Sauvegarde avec la base de données de métadonnées.
Une installation en mode Prefer avec des métadonnées de système de fichiers existantes reste en repli après les redémarrages. Pendant le repli, le registre ne lit pas et n'écrit pas dans la base de données de métadonnées. Vous n'avez pas besoin de sauvegarder la base de données de métadonnées jusqu'à la fin du repli.
Pour mettre fin au repli, effectuez une importation de métadonnées et redémarrez le registre. Après le redémarrage, le registre utilise la base de données de métadonnées. Incluez-la dans votre routine de sauvegarde.
Pour vérifier quel backend de métadonnées votre registre utilise, utilisez l'une des méthodes suivantes.
Envoyez une requête au point de terminaison /v2/ du registre :
curl --silent --head "https://registry.example.com/v2/" | grep --ignore-case gitlab-container-registry-database-enabled
Inspectez l'en-tête de réponse gitlab-container-registry-database-enabled :
true signifie que le registre utilise la base de données de métadonnées.false signifie qu'il utilise le stockage du système de fichiers hérité.Pour vérifier les fichiers de verrouillage sur le disque, recherchez ces fichiers dans le backend de stockage configuré à <rootdirectory>/docker/registry/lockfiles/ :
database-in-use : Le registre utilise la base de données de métadonnées.filesystem-in-use : Le registre utilise le stockage du système de fichiers hérité.Si les deux fichiers de verrouillage existent, le registre est dans un état invalide et ne démarre pas.
Le registre enregistre quel backend de métadonnées il sélectionne au démarrage.
Pour vérifier les journaux du registre, recherchez l'un des messages suivants :
Si le registre revient au stockage hérité (mode Prefer uniquement) :
database prefer mode enabled, but found filesystem metadata: falling back to legacy metadata
Si le registre se connecte à la base de données :
using the metadata database
Le registre de conteneurs prend en charge deux types de migrations :
Par défaut, le registre applique simultanément les migrations de schéma régulières et les migrations post-déploiement. Pour réduire les temps d'arrêt lors des mises à niveau, vous pouvez ignorer les migrations post-déploiement et les appliquer manuellement après le démarrage de l'application.
{{< tabs >}}
{{< tab title="GitLab 18.7 et versions ultérieures" >}}
Pour appliquer les migrations de schéma régulières et les migrations post-déploiement avant le démarrage de l'application :
Exécuter les migrations de base de données :
sudo gitlab-ctl registry-database migrate up
Pour ignorer les migrations post-déploiement :
Exécuter uniquement les migrations de schéma régulières :
sudo gitlab-ctl registry-database migrate up --skip-post-deployment
Comme alternative à l'indicateur --skip-post-deployment, vous pouvez également définir la variable d'environnement SKIP_POST_DEPLOYMENT_MIGRATIONS sur true :
SKIP_POST_DEPLOYMENT_MIGRATIONS=true sudo gitlab-ctl registry-database migrate up
Après avoir démarré l'application, appliquez toutes les migrations post-déploiement en attente :
sudo gitlab-ctl registry-database migrate up
{{< /tab >}}
{{< tab title="GitLab 18.6 et versions antérieures" >}}
Pour appliquer les migrations de schéma régulières et les migrations post-déploiement avant le démarrage de l'application :
Exécuter les migrations de base de données :
sudo -u registry gitlab-ctl registry-database migrate up
Pour ignorer les migrations post-déploiement :
Exécuter uniquement les migrations de schéma régulières :
sudo -u registry gitlab-ctl registry-database migrate up --skip-post-deployment
Comme alternative à l'indicateur --skip-post-deployment, vous pouvez également définir la variable d'environnement SKIP_POST_DEPLOYMENT_MIGRATIONS sur true :
SKIP_POST_DEPLOYMENT_MIGRATIONS=true sudo -u registry gitlab-ctl registry-database migrate up
Après avoir démarré l'application, appliquez toutes les migrations post-déploiement en attente :
sudo -u registry gitlab-ctl registry-database migrate up
{{< /tab >}}
{{< /tabs >}}
[!note] La commande
migrate upoffre des indicateurs supplémentaires qui peuvent être utilisés pour contrôler la façon dont les migrations sont appliquées. Exécutezsudo gitlab-ctl registry-database migrate up --helppour plus de détails.
La durée des premières exécutions de la collecte des déchets en ligne après le processus d'importation varie en fonction du nombre d'images importées. Vous devez surveiller l'efficacité et l'état de votre collecte des déchets en ligne pendant cette période.
Après avoir effectué une importation, attendez-vous à ce que la base de données connaisse une période de charge élevée pendant que les files d'attente de collecte des déchets se vident. Cette charge élevée est causée par un nombre élevé d'appels de base de données individuels provenant du ramasse-miettes en ligne qui traite les tâches en file d'attente.
Vérifiez régulièrement les journaux PostgreSQL et du registre pour détecter les erreurs ou les avertissements. Dans les journaux du registre, portez une attention particulière aux journaux filtrés par component=registry.gc.*.
Utilisez des outils de surveillance comme Prometheus et Grafana pour visualiser et suivre les métriques de collecte des déchets, en vous concentrant sur les métriques avec un préfixe de registry_gc_*. Celles-ci comprennent le nombre d'objets marqués pour suppression, les objets supprimés avec succès, les intervalles d'exécution et les durées. Consultez activer le serveur de débogage du registre pour savoir comment activer Prometheus.
Surveillez l'état et le statut des files d'attente de tâches de collecte des déchets pour les blobs et les manifestes.
{{< tabs >}}
{{< tab title="GitLab 18.10 et versions ultérieures" >}}
La commande suivante affiche des informations relatives à la collecte des déchets en ligne.
sudo gitlab-ctl registry-database gc-stats
Exemple de sortie :
=== Blob Review Queue ===
Tasks Pending Removal: 42
Tasks ready for GC review (review_after has passed).
┌───────────────────────────────────────────────────────────────────┬─────────────────────┬─────────────────┐
│ DIGEST │ REVIEW AFTER │ EVENT │
├───────────────────────────────────────────────────────────────────┼─────────────────────┼─────────────────┤
│ sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22e │ 2026-01-16 21:56:13 │ blob_upload │
│ sha256:b4f5e6d7c8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2 │ 2026-01-16 19:56:13 │ manifest_delete │
│ sha256:c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3 │ 2026-01-16 17:56:13 │ layer_delete │
└───────────────────────────────────────────────────────────────────┴─────────────────────┴─────────────────┘
Long Overdue Tasks: 5
Tasks pending longer than configured delay - may need attention.
┌───────────────────────────────────────────────────────────────────┬─────────────────────┬──────────────┬─────────┐
│ DIGEST │ REVIEW AFTER │ EVENT │ OVERDUE │
├───────────────────────────────────────────────────────────────────┼─────────────────────┼──────────────┼─────────┤
│ sha256:d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4 │ 2026-01-11 23:56:13 │ blob_upload │ 4d 0h │
│ sha256:e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5 │ 2026-01-13 23:56:13 │ layer_delete │ 2d 0h │
└───────────────────────────────────────────────────────────────────┴─────────────────────┴──────────────┴─────────┘
High Retry Tasks: 2
Tasks with >10 review attempts - may indicate persistent issues.
┌───────────────────────────────────────────────────────────────────┬─────────────────────┬─────────────────┬─────────┐
│ DIGEST │ REVIEW AFTER │ EVENT │ RETRIES │
├───────────────────────────────────────────────────────────────────┼─────────────────────┼─────────────────┼─────────┤
│ sha256:f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6 │ 2026-01-17 00:56:13 │ blob_upload │ 15 │
│ sha256:a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7 │ 2026-01-17 01:56:13 │ manifest_delete │ 12 │
└───────────────────────────────────────────────────────────────────┴─────────────────────┴─────────────────┴─────────┘
=== Manifest Review Queue ===
Tasks Pending Removal: 128
Tasks ready for GC review (review_after has passed).
┌───────────────┬─────────────┬─────────────────────┬──────────────────────┐
│ REPOSITORY ID │ MANIFEST ID │ REVIEW AFTER │ EVENT │
├───────────────┼─────────────┼─────────────────────┼──────────────────────┤
│ 1001 │ 12345 │ 2026-01-16 22:56:13 │ tag_delete │
│ 1002 │ 67890 │ 2026-01-16 20:56:13 │ manifest_upload │
│ 1003 │ 11111 │ 2026-01-16 18:56:13 │ tag_switch │
│ 2001 │ 22222 │ 2026-01-16 16:56:13 │ manifest_list_delete │
└───────────────┴─────────────┴─────────────────────┴──────────────────────┘
Long Overdue Tasks: 8
Tasks pending longer than configured delay - may need attention.
┌───────────────┬─────────────┬─────────────────────┬─────────────────┬─────────┐
│ REPOSITORY ID │ MANIFEST ID │ REVIEW AFTER │ EVENT │ OVERDUE │
├───────────────┼─────────────┼─────────────────────┼─────────────────┼─────────┤
│ 3001 │ 33333 │ 2026-01-12 23:56:13 │ tag_delete │ 3d 0h │
│ 3002 │ 44444 │ 2026-01-14 23:56:13 │ manifest_delete │ 1d 0h │
└───────────────┴─────────────┴─────────────────────┴─────────────────┴─────────┘
High Retry Tasks: 3
Tasks with >10 review attempts - may indicate persistent issues.
┌───────────────┬─────────────┬─────────────────────┬─────────────────┬─────────┐
│ REPOSITORY ID │ MANIFEST ID │ REVIEW AFTER │ EVENT │ RETRIES │
├───────────────┼─────────────┼─────────────────────┼─────────────────┼─────────┤
│ 4001 │ 55555 │ 2026-01-17 00:26:13 │ tag_delete │ 18 │
│ 4002 │ 66666 │ 2026-01-17 00:41:13 │ manifest_upload │ 11 │
└───────────────┴─────────────┴─────────────────────┴─────────────────┴─────────┘
{{< /tab >}}
{{< tab title="GitLab 18.9 et versions antérieures" >}}
Utilisez la commande suivante pour vous connecter à la base de données de métadonnées du registre :
gitlab-psql -d registry
Les requêtes suivantes renvoient les tâches qui ont été réessayées plus de 10 fois ou qui étaient éligibles à l'examen pendant plus de 24 heures. Le ramasse-miettes en ligne doit prendre en charge un élément pour examen dans les 24 heures avec peu de tentatives échouées. Si des lignes sont renvoyées, examinez l'état de votre ramasse-miettes en ligne.
Pour les manifestes :
SELECT
repository_id,
manifest_id,
ROUND(
EXTRACT(
EPOCH
FROM
AGE(NOW(), review_after)
) / 3600
) AS hours_eligible_for_review,
review_count as failed_review_attempts,
event
FROM
gc_manifest_review_queue
WHERE
review_after < NOW() - INTERVAL '24 hours'
OR review_count > 10
LIMIT
20;
Pour les blobs :
SELECT
substring(encode(digest, 'hex'), 3) AS digest,
ROUND(
EXTRACT(
EPOCH
FROM
AGE(NOW(), review_after)
) / 3600
) AS hours_eligible_for_review,
review_count as failed_review_attempts,
event
FROM
gc_blob_review_queue
WHERE
review_after < NOW() - INTERVAL '24 hours'
OR review_count > 10
LIMIT
20;
Vérifiez le nombre de tâches éligibles à l'examen en exécutant les requêtes suivantes :
SELECT COUNT(*) FROM gc_blob_review_queue WHERE review_after < NOW();
SELECT COUNT(*) FROM gc_manifest_review_queue WHERE review_after < NOW();
{{< /tab >}}
{{< /tabs >}}
En général, il devrait y avoir un nombre relativement faible d'éléments prêts à être examinés, souvent proche de zéro. Cependant, il pourrait y en avoir davantage si :
S'il y a des tâches avec des nouvelles tentatives ou qui sont en retard depuis longtemps, vérifiez les journaux du registre pour les messages relatifs à la collecte des déchets. Filtrez les entrées par component="registry.gc.* et examinez les messages d'erreur.
La taille non filtrée de gc_manifest_review_queue et gc_blob_review_queue ne sont pas de bons indicateurs de l'état du ramasse-miettes en ligne. Ces files d'attente reçoivent constamment de nouvelles entrées ; par conséquent, ces files d'attente ne se vident jamais complètement pour un registre actif.
De plus, tous les éléments de ces files d'attente ne seront pas supprimés du stockage. Consultez la spécification de la collecte des déchets en ligne pour une explication complète de ces files d'attente pour plus de contexte.
De grandes quantités de tâches éligibles à l'examen ne sont pas nécessairement une source de préoccupation. Le ramasse-miettes peut traiter des éléments causés par un pic d'activité.
De même, la date created_at de ces tâches seule n'est pas un bon indicateur de santé. Lorsqu'un événement ajoute le même blob ou manifeste à la file d'attente, le review_after de la tâche existante est mis à jour, ce qui reporte l'examen. Aucune tâche en double n'est créée.
Cela peut se produire un nombre quelconque de fois, donc les tâches créées il y a des mois ne sont pas une source de préoccupation.
Si le nombre de tâches éligibles à l'examen reste élevé et que vous souhaitez augmenter la fréquence entre les exécutions du worker de blob ou de manifeste de la collecte des déchets, mettez à jour votre configuration d'intervalle de la valeur par défaut (5s) à 1s :
registry['gc'] = {
'blobs' => {
'interval' => '1s'
},
'manifests' => {
'interval' => '1s'
}
}
Une fois la charge de l'importation effacée, vous devez affiner ces paramètres à long terme pour éviter une charge CPU inutile sur les instances de base de données et de registre. Vous pouvez augmenter progressivement l'intervalle à une valeur qui équilibre les performances et l'utilisation des ressources.
Pour garantir la cohérence des données après l'importation, utilisez l'outil crane validate. Cet outil vérifie que toutes les couches d'images et les manifestes de votre registre de conteneurs sont accessibles et correctement liés. En exécutant crane validate, vous confirmez que les images de votre registre sont complètes et accessibles, garantissant une importation réussie.
Si la plupart de vos images sont taguées, la collecte des déchets ne réduira pas significativement l'espace de stockage car elle ne supprime que les images non taguées.
Implémentez des politiques de nettoyage pour supprimer les tags inutiles, ce qui finit par entraîner la suppression des images via la collecte des déchets et la récupération de l'espace de stockage.
Par défaut, GitLab 18.3 et versions ultérieures préprovisionne une base de données logique au sein de la base de données GitLab principale pour les métadonnées du registre de conteneurs. Cependant, vous pouvez souhaiter utiliser une base de données externe dédiée pour le registre de conteneurs si vous souhaitez faire évoluer votre registre.
Ensuite, suivez les mêmes étapes pour la base de données par défaut, en substituant vos propres valeurs de base de données. Commencez avec la base de données désactivée, en veillant à activer et désactiver la base de données comme indiqué :
registry['database'] = {
'enabled' => false,
'host' => '<registry_database_host_placeholder_change_me>',
'port' => 5432, # Default, but set to the port of your database instance if it differs.
'user' => '<registry_database_username_placeholder_change_me>',
'password' => '<registry_database_placeholder_change_me>',
'dbname' => '<registry_database_name_placeholder_change_me>',
'sslmode' => 'require', # See the PostgreSQL documentation for additional information https://www.postgresql.org/docs/16/libpq-ssl.html.
'sslcert' => '</path/to/cert.pem>',
'sslkey' => '</path/to/private.key>',
'sslrootcert' => '</path/to/ca.pem>'
}
{{< history >}}
{{< /history >}}
Lorsque la base de données de métadonnées est activée, les sauvegardes doivent inclure à la fois le backend de stockage du registre et la base de données.
La méthode de sauvegarde dépend de votre type de stockage :
gitlab-backup inclut le registre automatiquement.Sauvegardez le stockage et la base de données aussi proches que possible dans le temps pour garantir un état cohérent du registre. Pour restaurer le registre, vous devez appliquer les deux sauvegardes.
Dans GitLab 18.10 et versions ultérieures, gitlab-backup create et gitlab-backup restore incluent automatiquement la base de données de métadonnées du registre lorsque la base de données de métadonnées est configurée. Sur les installations Helm chart (Kubernetes), backup-utility se comporte de la même manière.
La base de données de métadonnées doit être configurée dans gitlab.rb ou dans votre fichier de valeurs Helm.
Aucune configuration supplémentaire n'est requise. Les outils de sauvegarde lisent les paramètres de connexion à la base de données du registre à partir de la configuration existante.
Si vous appelez directement la tâche Rake de sauvegarde, vous devez définir les variables d'environnement suivantes sur le nœud qui exécute la sauvegarde :
| Variable | Obligatoire | Description |
|---|---|---|
REGISTRY_DATABASE_HOST | Oui | L'hôte de la base de données. |
REGISTRY_DATABASE_NAME | Oui | Le nom de la base de données. |
REGISTRY_DATABASE_USER | Oui | L'utilisateur de la base de données. |
REGISTRY_DATABASE_PORT | Non | Le port de la base de données. Par défaut à 5432. |
REGISTRY_DATABASE_PASSWORD | Non | Le mot de passe de la base de données. |
REGISTRY_DATABASE_SSLMODE | Non | Indique si le mode SSL est requis ou non. Définissez sur require ou omettez. |
REGISTRY_DATABASE_SSLCERT | Non | Le chemin vers le certificat client. |
REGISTRY_DATABASE_SSLKEY | Non | Le chemin vers la clé privée du client. |
REGISTRY_DATABASE_SSLROOTCERT | Non | Le chemin vers le certificat CA. |
REGISTRY_DATABASE_CONNECT_TIMEOUT | Non | Le délai d'expiration de la connexion en secondes. |
La tâche Rake de sauvegarde active la sauvegarde de la base de données du registre lorsqu'elle détecte l'un des identifiants suivants :
REGISTRY_DATABASE_PASSWORDREGISTRY_DATABASE_SSLCERTREGISTRY_DATABASE_SSLKEYREGISTRY_DATABASE_SSLROOTCERTSans identifiants, la base de données du registre n'est pas incluse dans la sauvegarde. Les mêmes variables d'environnement doivent être définies lors de la restauration.
Si vous utilisez GitLab 18.9 ou version antérieure, ou si vous préférez gérer les sauvegardes de la base de données du registre séparément, utilisez les outils PostgreSQL standard comme pg_dump et pg_restore pour sauvegarder et restaurer la base de données du registre indépendamment.
{{< history >}}
{{< /history >}}
Pour les déploiements Helm chart (Kubernetes), configurez le pod toolbox avec des identifiants de base de données dédiés pour les opérations de sauvegarde et de restauration. Deux utilisateurs PostgreSQL distincts sont nécessaires :
Configurez un ou les deux utilisateurs, selon les opérations dont vous avez besoin.
Avant de commencer, activez la base de données de métadonnées du registre de conteneurs en définissant registry.database.enabled: true.
Vous devez créer manuellement le secret Kubernetes avant le déploiement. Le chart ne génère pas automatiquement ce secret.
Par exemple, pour créer un secret avec les mots de passe de sauvegarde et de restauration :
kubectl create secret generic my-registry-db-password-secret \
--from-literal=backupPassword="BACKUP_USER_PASSWORD" \
--from-literal=restorePassword="RESTORE_USER_PASSWORD"
Ajoutez le YAML requis à votre Helm values.yaml pour configurer les utilisateurs de sauvegarde et de restauration. Consultez le tableau suivant pour les définitions des paramètres de configuration.
| Paramètre | Valeur par défaut | Description |
|---|---|---|
backupUser | Nom d'utilisateur PostgreSQL pour les opérations de sauvegarde. Obligatoire pour activer les sauvegardes de la base de données du registre. | |
restoreUser | Nom d'utilisateur PostgreSQL pour les opérations de restauration. Obligatoire pour activer les restaurations de la base de données du registre. | |
password.secret | <release-name>-toolbox-registry-database-password | Nom du secret Kubernetes contenant les mots de passe. |
password.backupPasswordKey | backupPassword | Clé dans le secret Kubernetes pour le mot de passe de l'utilisateur de sauvegarde. |
password.restorePasswordKey | restorePassword | Clé dans le secret Kubernetes pour le mot de passe de l'utilisateur de restauration. |
L'exemple suivant configure à la fois les utilisateurs de sauvegarde et de restauration :
gitlab:
toolbox:
backups:
registry:
database:
# PostgreSQL username for backing up the registry database
backupUser: "registry_backup"
# PostgreSQL username for restoring the registry database
restoreUser: "registry_restore"
password:
# Name of the Kubernetes Secret containing the passwords
secret: "my-registry-db-password-secret"
# Key in the Secret for the backup user's password
backupPasswordKey: "backupPassword"
# Key in the Secret for the restore user's password
restorePasswordKey: "restorePassword"
Si aucun backupUser ou restoreUser n'est configuré, la sauvegarde de la base de données du registre est ignorée silencieusement et le pod toolbox fonctionne normalement.
L'utilisateur de sauvegarde nécessite un accès en lecture seule pour effectuer un dump de la base de données du registre. L'utilisateur de restauration nécessite des privilèges de superutilisateur pour la restaurer.
Pour les installations de packages Linux, ces utilisateurs et autorisations sont créés automatiquement lorsque database_backup_username, database_backup_password, database_restore_username et database_restore_password sont configurés.
Pour les installations auto-compilées ou avec base de données externe, créez les utilisateurs et accordez les autorisations manuellement :
-- Create the backup user with minimal privileges for pg_dump.
-- The registry database uses both the 'public' and 'partitions' schemas.
CREATE ROLE registry_backup WITH LOGIN PASSWORD 'password'
NOINHERIT NOCREATEDB NOSUPERUSER NOREPLICATION;
GRANT CONNECT ON DATABASE registry TO registry_backup;
-- Grant read-only access on both schemas
GRANT USAGE ON SCHEMA public TO registry_backup;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO registry_backup;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO registry_backup;
ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA public
GRANT SELECT ON TABLES TO registry_backup;
ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA public
GRANT SELECT ON SEQUENCES TO registry_backup;
GRANT USAGE ON SCHEMA partitions TO registry_backup;
GRANT SELECT ON ALL TABLES IN SCHEMA partitions TO registry_backup;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA partitions TO registry_backup;
ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA partitions
GRANT SELECT ON TABLES TO registry_backup;
ALTER DEFAULT PRIVILEGES FOR ROLE registry IN SCHEMA partitions
GRANT SELECT ON SEQUENCES TO registry_backup;
-- Create the restore user with superuser privileges.
-- SUPERUSER is required for database restore operations because the
-- restore process must SET ROLE to the registry owner and
-- CREATE TRIGGER on all tables.
CREATE ROLE registry_restore WITH LOGIN PASSWORD 'password' SUPERUSER;
Lorsqu'il est configuré, le chart crée un volume monté sur /etc/gitlab/registry-db/ dans le déploiement du toolbox et dans le CronJob de sauvegarde. Le volume est en lecture seule et inclut les éléments suivants :
backupUser et restoreUser configurés.Le backup-utility dans le pod toolbox lit ces fichiers et inclut la base de données de métadonnées du registre dans les opérations de sauvegarde et de restauration.
Si des fichiers d'identifiants requis sont manquants, le backup-utility enregistre un avertissement et continue avec la sauvegarde des autres ressources.
Les chemins de certificats SSL pour l'authentification TLS mutuel avec PostgreSQL ne sont inclus que lorsque SSL est configuré globalement (global.psql.ssl). Si SSL est configuré uniquement au niveau du sous-chart du registre (registry.database.ssl), ces paramètres ne sont pas transmis au toolbox.
Lors de l'utilisation de Geo, chaque site maintient sa propre base de données de registre et son propre stockage d'objets. Sauvegardez la base de données du registre et le stockage d'objets sur chaque site indépendamment. Geo ne réplique pas la base de données du registre entre les sites.
Pour rétrograder le registre vers une version précédente après la fin de l'importation, vous devez restaurer une sauvegarde de la version souhaitée afin de rétrograder.
Lors de l'utilisation de GitLab Geo avec le registre de conteneurs, vous devez configurer des piles de base de données et de stockage d'objets distinctes pour le registre sur chaque site. La réplication Geo vers le registre de conteneurs utilise des événements générés à partir des notifications du registre, plutôt que par la réplication de base de données.
Chaque site Geo nécessite un élément distinct, spécifique au site :
Ce diagramme illustre le flux de données et l'architecture de base :
%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart TB
accTitle: Geo architecture for the container registry metadata database
accDescr: The primary site sends events to the secondary site through the GitLab Rails notification system for Geo replication.
subgraph "Primary site"
P_Rails[GitLab Rails]
P_Reg[Container registry]
P_RegDB[(Registry database)]
P_Obj[(Object storage)]
P_Reg --> P_RegDB
P_RegDB --> P_Obj
end
subgraph "Secondary site"
S_Rails[GitLab Rails]
S_Reg[Container registry]
S_RegDB[(Registry database)]
S_Obj[(Object storage)]
S_Reg --> S_RegDB
S_RegDB --> S_Obj
end
P_Reg -- "Notifications" --> P_Rails
P_Rails -- "Events" --> S_Rails
S_Rails --> S_Reg
Utilisez des instances de base de données distinctes sur chaque site car :
Vous pouvez faire revenir votre registre à l'utilisation des métadonnées du stockage d'objets après avoir effectué une importation de métadonnées.
[!warning] Lorsque vous revenez aux métadonnées du stockage d'objets, toutes les images de conteneurs, les tags ou les dépôts ajoutés ou supprimés entre la fin de l'importation et cette opération de retour ne sont pas disponibles.
Pour revenir aux métadonnées du stockage d'objets :
Restaurez une sauvegarde effectuée avant la migration.
Ajoutez la configuration suivante à votre fichier /etc/gitlab/gitlab.rb :
registry['database'] = {
'enabled' => false,
}
Enregistrez le fichier et reconfigurez GitLab.
Pour examiner les erreurs et les solutions de dépannage et les solutions de contournement, consultez Dépannage de la base de données de métadonnées du registre de conteneurs.