Aller au contenu

Configurer la cleanup policy du registry

Tu es mainteneur·se de Kirexo et tu veux empêcher le GitLab Container Registry du projet de gonfler indéfiniment : à chaque tag de release, le job docker:build-prod pousse une nouvelle image kirexo-prod:<YYYYMMDDHHMM> (~150-300 Mo) en plus du tag mobile :latest. Sans nettoyage, le registry accumule des dizaines de tags par mois.

Cette recette configure la cleanup policy for tags native de GitLab : une règle qui s'applique chaque semaine et supprime les anciens tags selon un pattern, en conservant les N plus récents et :latest.

Prérequis

  • Tu as les droits Maintainer ou Owner sur le projet GitLab.
  • Au moins un tag de release a été créé : kirexo-prod:<YYYYMMDDHHMM> existe dans le registry. La cleanup policy est utile à partir du moment où plusieurs tags datés s'accumulent (cf. Créer un tag de release).
  • Tu connais la convention des tags poussés par la CI : kirexo-prod reçoit :php8.5 + :latest + :<YYYYMMDDHHMM> ; kirexo-base et kirexo-dev reçoivent :php8.5 + :latest ; kirexo-docs n'a que :latest. Voir Images publiées dans le registry.

Pourquoi nettoyer

Le scénario par défaut (sans cleanup) :

Cadence de release Tags kirexo-prod accumulés / an Poids approx. / an
1 release / semaine ~52 tags YYYYMMDDHHMM 8-15 Go
1 release / jour ~365 tags 55-110 Go

Chaque tag pointe sur un manifeste qui référence les couches Docker poussées. Les couches partagées entre versions ne sont pas dupliquées sur le blob storage tant qu'un tag les référence — mais dès qu'une couche cesse d'être référencée par tout tag, elle reste tout de même en attente du garbage collector d'instance (cf. dernière section).

L'objectif réaliste est de conserver assez de tags pour pouvoir rollback en confiance (cf. Déployer Kirexo en production — un rollback réexporte un KIREXO_VERSION antérieur et re-pull), sans accumuler à l'infini.

Politique recommandée pour kirexo-prod

Garder les 10 derniers tags datés + :latest. Cadence hebdomadaire. Avec une release / semaine, cela couvre ~2 mois de rollback ; avec une release / jour, ~10 jours.

  1. Dans le projet GitLab cible, aller dans Settings → Packages and registries.
  2. Déplier la section Container registry.
  3. Repérer la sous-section Cleanup policy for tags et cliquer sur Edit.

  4. Renseigner les champs suivants :

    Champ Valeur Pourquoi
    Enable cleanup policy Coché Active la règle.
    Run cleanup Every week Une fois par semaine suffit largement — la suppression est de toute façon logique côté GitLab, la place disque est libérée plus tard par le GC d'instance.
    Keep the most recent 10 tags per image name Filet de sécurité — même si le filtre remove matche plus de tags, ce nombre est respecté (les 10 plus récents par date de push sont gardés).
    Keep tags matching latest Le tag mobile :latest est toujours conservé, indépendamment du reste.
    Remove tags older than 30 days Tous les tags datés de plus de 30 jours deviennent candidats à la suppression (toujours limités par la règle « Keep the most recent »).
    Remove tags matching [0-9]{12} Vise exclusivement les tags au format YYYYMMDDHHMM poussés par docker:build-prod. Le tag :php8.5 et :latest ne matchent pas — ils sont préservés même s'ils ont plus de 30 jours.

  5. Cliquer sur Save.

Comment GitLab combine les règles

La politique s'applique en deux temps :

  1. Filtrer : ne garder comme candidats à la suppression que les tags qui matchent Remove tags matching ET qui sont plus vieux que Remove tags older than.
  2. Protéger : parmi les candidats, garder les N plus récents (Keep the most recent) et tout ce qui matche Keep tags matching.

La règle Keep gagne toujours sur la règle Remove. C'est pour ça que latest peut être vieux et matcher le filtre [0-9]{12} indirectement (il ne le matche pas, mais même s'il le matchait, le Keep tags matching: latest le protégerait).

La cleanup policy s'applique à TOUT le registry du projet

Le filtre Remove tags matching est testé sur tous les repositories du registry (kirexo-prod, kirexo-base, kirexo-dev, kirexo-docs). Choisir [0-9]{12} — un format que seul kirexo-prod produit — évite tout effet de bord sur les autres images. Si tu veux des politiques différenciées par repository (par exemple garder 20 tags sur kirexo-prod et 5 sur les autres), il faut utiliser l'API GitLab Container Registry Protection Rules — non couvert dans cette recette.

kirexo-base, kirexo-dev, kirexo-docs : rien de spécifique à configurer

Ces trois repositories n'accumulent pas de tags datés :

Image Tags produits Cleanup utile ?
kirexo-base :php8.5 + :latest (cf. KIREXO_BASE_IMAGE dans .gitlab-ci.yml) Non — deux tags mobiles écrasés à chaque build.
kirexo-dev :php8.5 + :latest (cf. KIREXO_DEV_IMAGE dans .gitlab-ci.yml) Non — idem.
kirexo-docs :latest uniquement Non — un seul tag mobile.

La politique recommandée ci-dessus laisse ces trois repositories tranquilles parce que :

  • aucun de leurs tags ne matche [0-9]{12} ;
  • le Keep tags matching: latest protège leur tag mobile principal de toute façon.

Et le tag :php8.5 ?

Il n'est pas listé dans Keep tags matching parce qu'il ne matche pas non plus Remove tags matching: [0-9]{12} — donc il sort intact du filtrage initial. Si la convention de tag PHP change un jour (ex. :php9.0), l'ancien :php8.5 resterait dans le registry indéfiniment ; un nettoyage ponctuel manuel suffit à ce moment-là.

Vérifier que la politique fonctionne

  1. La page Settings → Packages and registries → Container registry → Cleanup policy affiche désormais Enabled et la prochaine date d'exécution (un compteur « Next run » en heures/jours).
  2. Après le premier passage, aller dans Deploy → Container Registry → kirexo-prod : seuls 10 tags YYYYMMDDHHMM au maximum doivent rester, plus :php8.5 et :latest.
  3. Si tu veux forcer une exécution sans attendre la cadence hebdo, modifier brièvement le champ Remove tags older than (ex. 7 days), sauvegarder, attendre quelques minutes, puis remettre la valeur originale. La cleanup est rejouée à chaque modification.

Limite — la suppression est logique, pas physique

Côté UI GitLab, la cleanup policy supprime les tags du repository : ils disparaissent de Deploy → Container Registry, on ne peut plus les docker pull. Mais les blobs (couches Docker physiques) qui ne sont plus référencés par aucun tag ne sont pas immédiatement libérés du stockage : c'est le garbage collector du registry, côté instance GitLab, qui s'en charge dans un second temps.

Hébergement Comportement
gitlab.com (Kirexo de référence) Le GC tourne automatiquement, sans intervention. La place est libérée sous quelques jours après la suppression logique des tags.
GitLab self-hosted Le GC doit être exécuté à la main : sudo gitlab-ctl registry-garbage-collect -m (ou via une schedule système). Tant qu'il n'a pas tourné, la place disque n'est pas récupérée.

Pour Kirexo hébergé sur gitlab.com, rien à faire côté instance : la cleanup policy configurée ci-dessus suffit.

Cas d'erreur

La cleanup ne supprime jamais aucun tag

Cas typiques :

  • Le filtre Remove tags matching est trop strict : ^[0-9]{12}$ est interprété tel quel par GitLab (qui ancre déjà sur le nom complet du tag). Si tu as ajouté des ancres ou des caractères supplémentaires, beaucoup de tags ne matchent plus. Repartir de [0-9]{12}.
  • Aucun tag n'a encore atteint Remove tags older than : la fenêtre 30 days n'est pas encore franchie. Réduire temporairement à 7 days pour vérifier que la mécanique fonctionne, puis remettre à 30 days.
  • Tous les tags candidats sont protégés par Keep the most recent : tu as moins de 10 tags YYYYMMDDHHMM dans le registry — la politique a fait ce qu'elle devait faire : ne rien supprimer.

Le tag :latest a été supprimé par erreur

Ne devrait pas arriver avec la politique recommandée (Keep tags matching: latest). Si tu as initialement saisi un regex Keep tags matching qui ne couvre pas latest, ré-éditer la cleanup policy pour ajouter latest. La prochaine release (n'importe quel tag Git YYYYMMDDHHMM poussé) repoussera :latest automatiquement via docker:build-prod.

La cleanup supprime les tags kirexo-base:php8.5 ou kirexo-dev:php8.5

Ne devrait pas arriver avec Remove tags matching: [0-9]{12} — php8.5 ne matche pas ce regex. Si tu as un autre filtre Remove, le restreindre. En dépannage, relancer manuellement docker:build-base puis docker:build-dev depuis l'UI GitLab pour les repousser (cf. Bootstrapper la pipeline CI — Étape 6).

Voir aussi