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, la pipeline publie une nouvelle image kirexo-prod:<x.y.z> et ses tags d'architecture kirexo-prod:<x.y.z>-amd64 et, si la jambe arm64 a poussé, kirexo-prod:<x.y.z>-arm64 (~150-300 Mo par architecture), en plus du tag mobile :latest. Sans nettoyage, le registry accumule deux tags par release sans arm64 (version + -amd64), trois avec, sans limite.

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 motif, en conservant les N plus récents et :latest.

Prérequis

  • Tu as les droits Maintainer ou Owner sur le projet GitLab.
  • Tu connais la convention des tags poussés par la CI : kirexo-prod reçoit :php8.5-alpine + :latest + :<x.y.z> (la version sémantique du tag Git, ex. :0.0.1), plus les tags d'architecture :<x.y.z>-amd64 et, si la jambe arm64 a poussé, :<x.y.z>-arm64 ; kirexo-base et kirexo-dev reçoivent :php8.5-alpine + :latest ; kirexo-docs n'a que :latest. Voir Images publiées dans le registry.
  • Le registry peut encore contenir des images kirexo-prod:<YYYYMMDDHHMM> : ce sont les images des anciennes releases horodatées, antérieures au versionnement sémantique. La politique ci-dessous les purge aussi.

Pourquoi nettoyer

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

Cadence de release Tags kirexo-prod accumulés / an (2 ou 3 par release) Releases conservées
1 release / semaine ~104 à ~156 tags ~52
1 release / jour ~730 à ~1 095 tags ~365

Les deux ou trois tags d'une release désignent une ou deux images, une par architecture publiée : le tag de version pointe l'index qui les référence, les tags d'architecture pointent chacun l'une d'elles. Chaque release ajoute donc au registry le poids d'une ou deux images.

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 30 derniers tags de version et d'architecture, soit 10 à 15 releases selon la présence d'arm64, + :latest. Cadence hebdomadaire.

  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 30 tags per image name Filet de sécurité — même si le filtre remove matche plus de tags, les 30 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 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]+\.[0-9]+\.[0-9]+(?:-(?:amd64\|arm64))?\|[0-9]{12}) Vise exclusivement les tags de version de kirexo-prod : versions sémantiques X.Y.Z (créées par docker:manifest-prod), tags d'architecture X.Y.Z-amd64 / X.Y.Z-arm64 (poussés par docker:build-prod et docker:build-prod-arm64), et anciens tags horodatés YYYYMMDDHHMM. :php8.5-alpine et :latest ne matchent pas — ils sont préservés même s'ils ont plus de 30 jours.

    Motif à copier tel quel dans Remove tags matching :

    (?:[0-9]+\.[0-9]+\.[0-9]+(?:-(?:amd64|arm64))?|[0-9]{12})
    
  5. Cliquer sur Save.

Pourquoi 30 tags : deux ou trois tags par release

Chaque release publie deux ou trois tags qui matchent le motif : le tag de version X.Y.Z, cible de KIREXO_VERSION, le tag d'architecture X.Y.Z-amd64 et, si la jambe arm64 a poussé, X.Y.Z-arm64. Les tags d'architecture sont les intermédiaires de la pipeline à partir desquels l'index est assemblé (cf. Images publiées dans le registry). « Keep the most recent » les compte tous : 30 tags ≈ 10 releases de rollback possible avec arm64, 15 sans.

Les tags d'une release sont poussés à quelques minutes d'intervalle, dans la même pipeline : ils ont le même âge et occupent des rangs voisins dans le classement par date de push. La politique les supprime donc ensemble.

Ne pas supprimer un tag d'architecture à la main

Le tag de version pointe un index qui référence les images désignées par les tags d'architecture. Que le garbage collector du registry conserve une image encore référencée par un index taggé après la suppression de son tag d'architecture n'est pas confirmé. Tant que ce n'est pas établi, ne supprime jamais un tag X.Y.Z-amd64, ni un tag X.Y.Z-arm64 quand il existe, sans son tag de version X.Y.Z.

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 : même si latest matchait le filtre de suppression (ce n'est pas le cas), le Keep tags matching: latest le protégerait.

Les images horodatées historiques partent en premier

« Keep the most recent » compte tous les tags qui matchent le motif, quel que soit leur format, par date de push. Les images kirexo-prod:<YYYYMMDDHHMM> sont plus anciennes que toute image semver : elles sortent de la fenêtre des 30 tags au fur et à mesure que des versions sémantiques sont publiées, puis sont supprimées une fois passés les 30 jours. Tant qu'elles restent dans le registry, un rollback vers l'une d'elles reste possible.

Ne pas ajouter ^ ni $

GitLab évalue le motif en syntaxe RE2 et l'ancre automatiquement sur le nom complet du tag. Des ancres ajoutées à la main sont inutiles, et une erreur de saisie autour d'elles suffit à ne plus rien matcher.

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). Le motif ne vise que des tags de version, que seul kirexo-prod reçoit : il n'a pas d'effet de bord sur les autres images. Si tu veux des politiques différenciées par repository (par exemple garder 30 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 de version :

Image Tags produits Cleanup utile ?
kirexo-base :php8.5-alpine + :latest (cf. KIREXO_BASE_IMAGE dans .gitlab-ci.yml) Non — deux tags mobiles écrasés à chaque build.
kirexo-dev :php8.5-alpine + :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 le motif de suppression ;
  • le Keep tags matching: latest protège leur tag mobile principal de toute façon.

Et le tag :php8.5-alpine ?

Il n'est pas listé dans Keep tags matching parce qu'il ne matche pas non plus Remove tags matching — donc il sort intact du filtrage initial. Si la convention de tag PHP change un jour (ex. :php9.0-alpine), l'ancien :php8.5-alpine resterait dans le registry indéfiniment ; un nettoyage ponctuel manuel suffit à ce moment-là. C'est aussi le cas du tag legacy :php8.5 sans suffixe -alpine, vestige des images d'avant le passage à Alpine et que la CI ne republie plus : ne matchant aucun filtre, il reste figé dans le registry jusqu'à un nettoyage manuel.

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 30 tags de version au maximum (sémantiques, d'architecture ou horodatés) doivent rester, plus :php8.5-alpine et :latest. Pour chaque version conservée, son tag -amd64 est présent, et son tag -arm64 si la jambe arm64 l'avait poussé.
  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 motif Remove tags matching a été modifié : GitLab ancre déjà le motif sur le nom complet du tag. Des ancres ^…$ ajoutées, une barre oblique inverse ajoutée devant |, ou un ancien motif [0-9]{12} seul (qui ne vise que les images horodatées historiques) font que les tags de version sémantique ne matchent plus. Repartir de (?:[0-9]+\.[0-9]+\.[0-9]+(?:-(?:amd64|arm64))?|[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 30 tags de version 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 (tag Git de version sémantique) recréera :latest automatiquement via docker:manifest-prod.

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

Ne devrait pas arriver avec le motif recommandé — php8.5-alpine ne le matche pas. Si tu as un autre filtre Remove, le restreindre. Pour repousser les images :

  • Les deux images ont disparu, ou seule kirexo-dev a disparu : les jobs PHP échouent sur ErrImagePull et docker:build-dev ne part jamais. Suivre la procédure de Bootstrapper la pipeline CI, étape 6 : ▶ sur docker:build-base si besoin, puis build + push de kirexo-dev depuis l'hôte.
  • Seule kirexo-base a disparu : les jobs PHP qui la consomment échouent sur ErrImagePull. Cliquer sur ▶ sur docker:build-base dans une pipeline main.
  • kirexo-dev doit être reconstruite alors que les deux images existent : lancer Run pipeline sur main depuis l'UI. docker:build-dev s'exécute après les stages quality et test.

Voir aussi