Gérer le nettoyage automatique

Ce guide explique comment configurer et gérer le nettoyage automatique dans le Container Registry Numspot.

Vue d'ensemble

Le nettoyage automatique (Garbage Collection ou GC) est le processus de suppression des blobs, artefacts et manifests inutilisés du registry Harbor pour récupérer de l'espace de stockage. Le nettoyage automatique de Harbor supprime :

Blobs non référencés : Couches d'images non associées à un manifest
Artefacts orphelins : Manifests sans tags ni références
Artefacts supprimés : Artefacts marqués pour suppression mais non retirés du stockage

Pourquoi le nettoyage automatique est important

Optimisation du stockage : Récupérez l'espace disque occupé par les données inutilisées
Réduction des coûts : Diminuez les coûts de stockage objet
Performance : Améliorez les performances du registry en supprimant les données inutiles
Conformité : Respectez les politiques de rétention des données

Fonctionnement du nettoyage automatique

Architecture de stockage Harbor

┌────────────────────────────────────────────────────────┐
│                   Harbor Registry                       │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────┐ │
│  │   Metadata   │  │   Manifests  │  │    Blobs    │ │
│  │  (PostgreSQL)│  │   (JSON)     │  │  (Layers)   │ │
│  └──────────────┘  └──────────────┘  └─────────────┘ │
│                            │                           │
│                            ▼                           │
│                  ┌─────────────────────┐              │
│                  │   Object Storage    │              │
│                  │   (S3/MinIO)        │              │
│                  └─────────────────────┘              │
└────────────────────────────────────────────────────────┘

Processus de GC

Identifier les blobs non référencés : Trouver les blobs non référencés par un manifest
Marquer pour suppression : Marquer les artefacts et blobs pour suppression dans les métadonnées
Supprimer du stockage : Supprimer les blobs marqués du stockage objet
Nettoyer les métadonnées : Supprimer les enregistrements d'artefacts de la base de données

Modes de GC

Harbor prend en charge deux modes de nettoyage automatique :

Mode	Description	Impact
GC en ligne	Exécution pendant que le registry est accessible	Impact minimal, plus lent
GC hors ligne	Le registry est en mode lecture seule pendant le GC	Plus rapide, mais registry en lecture seule

Prérequis

Accès administrateur : Requis pour configurer et exécuter le GC
Instance de registry : Container Registry Numspot en cours d'exécution
Visibilité du quota de stockage : Connaître votre utilisation actuelle du stockage
Fenêtre de maintenance : Pour le GC hors ligne, planifiez pendant les périodes de faible trafic

Étape 1 : Vérifier l'utilisation actuelle du stockage

Via l'interface Harbor

Connectez-vous à l'interface Harbor
Accédez à Administration → Paramètres système
Consultez la section Stockage pour voir :
- Stockage total utilisé
- Espace libre disponible
- Quota de stockage

Via l'API

curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/systeminfo" \
  -u "admin:{password}" | jq '.storage'

Réponse :

{
  "total": 107374182400,
  "free": 53687091200,
  "used": 53687091200
}

Étape 2 : Configurer le nettoyage automatique

Via l'interface Harbor

Accédez à Administration → Nettoyage automatique
Configurez les paramètres GC :

Paramètre	Valeur
Type de GC	`En ligne` ou `Hors ligne`
Planification	Expression cron ou manuel
Supprimer les artefacts sans tag	Activer pour supprimer les manifests sans tag
Inclure les artefacts sans tag	Inclure les artefacts sans tag dans le GC

Cliquez sur Enregistrer

Exemples de planification

Planification	Expression Cron	Cas d'utilisation
Quotidien à 2h	`0 2 * * *`	Nettoyage régulier
Hebdomadaire le dimanche	`0 2 * * 0`	Maintenance hebdomadaire
Toutes les 6 heures	`0 /6 * *`	Environnements à forte rotation
Manuel	N/A	Nettoyage à la demande

Via l'API

curl -X PUT "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/system/gc/schedule" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "type": "Scheduled",
      "cron": "0 2 * * *"
    },
    "delete_untagged": true
  }'

Étape 3 : Exécuter le nettoyage automatique

Exécution manuelle

Via l'interface Harbor

Accédez à Administration → Nettoyage automatique
Cliquez sur GC maintenant
Sélectionnez le type de GC :
- GC en ligne : Le registry reste accessible
- GC hors ligne : Le registry passe en mode lecture seule
Sélectionnez les options :
- Supprimer les artefacts sans tag
Cliquez sur Démarrer GC
Suivez la progression dans l'historique GC

Via l'API

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/system/gc/schedule" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "type": "Manual"
    },
    "delete_untagged": true,
    "gc_executed_now": true
  }'

Étape 4 : Surveiller le nettoyage automatique

Via l'interface Harbor

Accédez à Administration → Nettoyage automatique
Consultez l'onglet Historique GC
Cliquez sur une exécution GC pour voir :
- Statut (En cours, Succès, Échec)
- Heure de début et durée
- Nombre d'artefacts supprimés
- Espace récupéré
- Journaux

Via l'API

# Lister les exécutions GC
curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/system/gc" \
  -u "admin:{password}"

# Obtenir une exécution GC spécifique
curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/system/gc/{gc_id}" \
  -u "admin:{password}"

# Obtenir le journal GC
curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/system/gc/{gc_id}/log" \
  -u "admin:{password}"

Statuts GC

Statut	Description
`Pending`	Tâche GC en file d'attente
`Running`	GC en cours
`Success`	GC terminé avec succès
`Failed`	GC a rencontré des erreurs
`Stopped`	GC a été arrêté manuellement

Bonnes pratiques

Planification

Planifiez pendant les heures creuses : Exécutez le GC quand l'utilisation du registry est faible
Fréquence basée sur la rotation : Les registries à forte rotation nécessitent un GC plus fréquent
Commencez par le GC en ligne : Testez avec le GC en ligne avant d'utiliser le GC hors ligne
Surveillez la durée : Suivez la durée du GC pour estimer les fenêtres de maintenance

Configuration

Activez la suppression des artefacts sans tag : Supprimez les artefacts sans tags
Utilisez le GC hors ligne pour les nettoyages importants : Plus rapide pour une récupération significative
Définissez des quotas de projet : Prévenez la croissance illimitée du stockage
Configurez des politiques de rétention : Utilisez la rétention d'artefacts pour supprimer automatiquement les anciennes images

Tests

Testez en non-production : Validez la configuration GC en staging d'abord
Surveillez après le GC : Vérifiez que le stockage est récupéré et que le registry fonctionne
Vérifiez la disponibilité des images : Assurez-vous que les images critiques restent accessibles après le GC

Nettoyage automatique et rétention d'images

Stratégie combinée

Implémentez une stratégie de nettoyage complète :

Politiques de rétention d'artefacts : Suppression automatique des anciens artefacts basée sur le temps ou le nombre
Quotas de projet : Limiter le stockage par projet
Règles de rétention de tags : Conserver uniquement les tags nécessaires
Nettoyage automatique planifié : Nettoyage régulier des données non référencées

Configurer la rétention d'artefacts

Accédez à Administration → Rétentions
Créez une règle de rétention :

Champ	Valeur
Portée	Global ou projet spécifique
Motif de dépôt	`**` ou motif spécifique
Critère	Tiré au cours des 30 derniers jours, ou les 10 plus récemment poussés
Action	`Supprimer`

Via l'API

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/retentions" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "or",
    "rules": [
      {
        "action": "delete",
        "scope_selectors": {
          "repository": [
            {
              "kind": "doublestar",
              "decoration": "repoMatches",
              "pattern": "**"
            }
          ]
        },
        "tag_selectors": [
          {
            "kind": "doublestar",
              "decoration": "matches",
              "pattern": "**",
              "extras": "{\"untagged\":true}"
          }
        ],
        "params": "{\"latest_pushed_k\":10}"
      }
    ],
    "trigger": {
      "kind": "Schedule",
      "settings": {
        "cron": "0 0 * * *"
      }
    },
    "scope": {
      "level": "system"
    }
  }'

Conseils d'optimisation du stockage

Réduire le stockage avant le GC

Supprimer les dépôts inutilisés :

curl -X DELETE "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project}/repositories/{repo}" \
  -u "admin:{password}"

Supprimer les anciens tags :
- Supprimez des tags spécifiques manuellement
- Utilisez des politiques de rétention pour la suppression automatique
Nettoyer les artefacts sans tag :
- Activez delete_untagged dans la configuration GC

Surveiller les tendances de stockage

# Obtenir l'utilisation du stockage au fil du temps
curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/statistics" \
  -u "admin:{password}" | jq '.total_storage_consumption'

Définir des quotas de projet

Accédez à Administration → Projets
Sélectionnez le projet → Configuration
Définissez le Quota de stockage (ex: 50Go)

Via l'API

curl -X PUT "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "storage_limit": "53687091200"
    }
  }'

Dépannage

Problème 1 : Le GC ne récupère pas d'espace

Symptôme : L'utilisation du stockage reste élevée après le GC

Solutions :

Vérifiez si les artefacts sont encore référencés par des tags
Vérifiez que delete_untagged est activé
Vérifiez les téléversements incomplets :

curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/systeminfo" \
  -u "admin:{password}" | jq '.incomplete_upload_count'

Exécutez un GC hors ligne pour un nettoyage plus agressif

Problème 2 : Le GC prend trop de temps

Symptôme : Le GC s'exécute pendant des heures

Solutions :

Vérifiez la taille du stockage et le nombre d'artefacts
Envisagez de diviser en projets plus petits
Planifiez un GC plus fréquent avec une portée de nettoyage plus petite
Utilisez le GC hors ligne au lieu du GC en ligne

Problème 3 : Registry lent pendant le GC en ligne

Symptôme : Dégradation des performances pendant le GC en ligne

Solutions :

Planifiez le GC pendant les heures creuses
Utilisez le GC hors ligne pour les nettoyages importants
Augmentez les ressources du registry (contactez le support)
Réduisez la fréquence du GC

Problème 4 : Tâche GC échouée

Symptôme : L'exécution du GC affiche le statut Failed

Solutions :

Vérifiez les journaux GC pour les détails de l'erreur :

curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/system/gc/{gc_id}/log" \
  -u "admin:{password}"

Vérifiez la connectivité au stockage objet
Vérifiez la connectivité à la base de données
Contactez le support avec les détails de l'erreur

Référence API

Obtenir la planification GC

GET /api/v2.0/system/gc/schedule
Authorization: Basic {base64(admin:password)}

Mettre à jour la planification GC

PUT /api/v2.0/system/gc/schedule
Authorization: Basic {base64(admin:password)}
Content-Type: application/json

{
  "schedule": {
    "type": "Scheduled",
    "cron": "0 2 * * *"
  },
  "delete_untagged": true
}

Déclencher un GC manuel

POST /api/v2.0/system/gc/schedule
Authorization: Basic {base64(admin:password)}
Content-Type: application/json

{
  "schedule": {
    "type": "Manual"
  },
  "delete_untagged": true,
  "gc_executed_now": true
}

Lister les exécutions GC

GET /api/v2.0/system/gc
Authorization: Basic {base64(admin:password)}

Obtenir les détails d'une exécution GC

GET /api/v2.0/system/gc/{gc_id}
Authorization: Basic {base64(admin:password)}

Obtenir le journal GC

GET /api/v2.0/system/gc/{gc_id}/log
Authorization: Basic {base64(admin:password)}

Limitations

GC en ligne plus lent : Peut prendre plus de temps que le GC hors ligne
GC hors ligne en lecture seule : Le registry est inaccessible en écriture pendant le GC hors ligne
Impossible d'arrêter un GC en cours : Il faut attendre la fin ou redémarrer le registry
Stockage non libéré immédiatement : Le stockage objet peut avoir un nettoyage différé
GC ne supprime pas les tags : Supprime uniquement les blobs et artefacts non référencés

Vue d'ensemble​

Pourquoi le nettoyage automatique est important​

Fonctionnement du nettoyage automatique​

Architecture de stockage Harbor​

Processus de GC​

Modes de GC​

Prérequis​

Étape 1 : Vérifier l'utilisation actuelle du stockage​

Via l'interface Harbor​

Via l'API​

Étape 2 : Configurer le nettoyage automatique​

Via l'interface Harbor​

Exemples de planification​

Via l'API​

Étape 3 : Exécuter le nettoyage automatique​

Exécution manuelle​

Via l'interface Harbor​

Via l'API​

Étape 4 : Surveiller le nettoyage automatique​

Via l'interface Harbor​

Via l'API​

Statuts GC​

Bonnes pratiques​

Planification​

Configuration​

Tests​

Nettoyage automatique et rétention d'images​

Stratégie combinée​

Configurer la rétention d'artefacts​

Via l'API​

Conseils d'optimisation du stockage​

Réduire le stockage avant le GC​

Surveiller les tendances de stockage​

Définir des quotas de projet​

Via l'API​

Dépannage​

Problème 1 : Le GC ne récupère pas d'espace​

Problème 2 : Le GC prend trop de temps​

Problème 3 : Registry lent pendant le GC en ligne​

Problème 4 : Tâche GC échouée​

Référence API​

Obtenir la planification GC​

Mettre à jour la planification GC​

Déclencher un GC manuel​

Lister les exécutions GC​

Obtenir les détails d'une exécution GC​

Obtenir le journal GC​

Limitations​

Vue d'ensemble

Pourquoi le nettoyage automatique est important

Fonctionnement du nettoyage automatique

Architecture de stockage Harbor

Processus de GC

Modes de GC

Prérequis

Étape 1 : Vérifier l'utilisation actuelle du stockage

Via l'interface Harbor

Via l'API

Étape 2 : Configurer le nettoyage automatique

Via l'interface Harbor

Exemples de planification

Via l'API

Étape 3 : Exécuter le nettoyage automatique

Exécution manuelle

Via l'interface Harbor

Via l'API

Étape 4 : Surveiller le nettoyage automatique

Via l'interface Harbor

Via l'API

Statuts GC

Bonnes pratiques

Planification

Configuration

Tests

Nettoyage automatique et rétention d'images

Stratégie combinée

Configurer la rétention d'artefacts

Via l'API

Conseils d'optimisation du stockage

Réduire le stockage avant le GC

Surveiller les tendances de stockage

Définir des quotas de projet

Via l'API

Dépannage

Problème 1 : Le GC ne récupère pas d'espace

Problème 2 : Le GC prend trop de temps

Problème 3 : Registry lent pendant le GC en ligne

Problème 4 : Tâche GC échouée

Référence API

Obtenir la planification GC

Mettre à jour la planification GC

Déclencher un GC manuel

Lister les exécutions GC

Obtenir les détails d'une exécution GC

Obtenir le journal GC

Limitations