Configurer le proxy cache

Ce guide explique comment configurer et utiliser les projets proxy cache dans le Container Registry Numspot.

Vue d'ensemble

Le proxy cache permet au Container Registry Numspot d'agir comme un cache de type pull-through pour les images provenant de registries externes. Lorsqu'une image demandée n'existe pas localement, Harbor la tire automatiquement depuis le registry amont configuré et la met en cache pour une utilisation ultérieure.

Avantages

Réduction de la latence : Tirez les images depuis un cache local au lieu de registries externes
Économie de bande passante : Réduisez le trafic réseau externe et les coûts associés
Haute disponibilité : Accédez aux images en cache même si le registry amont n'est pas disponible
Évitement des limites de débit : Évitez les limites de débit de Docker Hub en mettant les images en cache localement
Environnements isolés (air-gapped) : Fournissez un accès aux images externes dans des réseaux restreints

Registries amont pris en charge

Le Container Registry Numspot peut faire du proxy cache depuis :

Docker Hub
AWS Elastic Container Registry (ECR)
Azure Container Registry (ACR)
Google Container Registry (GCR) / Artifact Registry
Quay
D'autres instances Harbor

Fonctionnement du proxy cache

┌─────────────┐        ┌──────────────────────────┐        ┌─────────────────┐
│   Docker    │        │  Numspot Container       │        │   Upstream      │
│   Client    │───────▶│  Registry (Proxy Cache)  │───────▶│   Registry      │
└─────────────┘        └──────────────────────────┘        └─────────────────┘
                                │
                                │ Au premier pull :
                                │ 1. Vérifier le cache local
                                │ 2. Si non trouvé, tirer depuis l'amont
                                │ 3. Mettre l'image en cache
                                │ 4. Retourner au client
                                │
                                │ Aux pulls suivants :
                                │ 1. Retourner l'image en cache
                                │ 2. Mettre à jour le cache si une version plus récente existe

Prérequis

Instance de registry : Container Registry Numspot opérationnel
Identifiants administrateur : Accès à l'interface Harbor avec les privilèges administrateur
Identifiants du registry amont : (Optionnel) Pour les dépôts privés
Connectivité réseau : Le registry doit pouvoir atteindre le registry amont

Étape 1 : Créer un endpoint de réplication

Avant de créer un projet proxy cache, configurez un endpoint pour le registry amont.

Via l'interface Harbor

Connectez-vous à l'interface Harbor
Naviguez vers Administration → Registries
Cliquez sur + New Endpoint
Configurez l'endpoint :

Champ	Valeur
Provider	`Docker Hub`, `AWS ECR`, etc.
Name	`docker-hub-cache`
Endpoint URL	`https://registry-1.docker.io` (Docker Hub)
Access ID	Votre nom d'utilisateur Docker Hub (optionnel pour les dépôts publics)
Access Secret	Votre mot de passe/token Docker Hub (optionnel pour les dépôts publics)
Verify Remote Cert	Activé

Cliquez sur Test Connection
Cliquez sur OK pour enregistrer

Exemples de configuration d'endpoint

Docker Hub (images publiques)

{
  "name": "docker-hub-public",
  "type": "docker-hub",
  "url": "https://registry-1.docker.io"
}

Docker Hub (images privées)

{
  "name": "docker-hub-private",
  "type": "docker-hub",
  "url": "https://registry-1.docker.io",
  "credential": {
    "access_key": "dockerhub-username",
    "access_secret": "dockerhub-access-token"
  }
}

AWS ECR

{
  "name": "aws-ecr",
  "type": "aws-ecr",
  "url": "https://123456789.dkr.ecr.us-east-1.amazonaws.com",
  "credential": {
    "access_key": "AKIAIOSFODNN7EXAMPLE",
    "access_secret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }
}

Google GCR

{
  "name": "google-gcr",
  "type": "google-gcr",
  "url": "https://gcr.io/my-project",
  "credential": {
    "access_key": "_json_key",
    "access_secret": "{\"type\":\"service_account\",\"project_id\":\"my-project\",...}"
  }
}

Via API

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/registries" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "docker-hub-cache",
    "type": "docker-hub",
    "url": "https://registry-1.docker.io",
    "credential": {
      "type": "basic",
      "access_key": "dockerhub-username",
      "access_secret": "dockerhub-token"
    }
  }'

Étape 2 : Créer un projet proxy cache

Via l'interface Harbor

Connectez-vous à l'interface Harbor
Cliquez sur Projects → New Project
Configurez le projet :

Champ	Valeur
Name	`docker-hub-cache` (ou un nom descriptif)
Access Level	`Public` (pour permettre le pull à tous) ou `Private`
Proxy Cache	Activer
Endpoint	Sélectionnez l'endpoint `docker-hub-cache` créé à l'étape 1

Cliquez sur OK pour créer

Via API

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "docker-hub-cache",
    "public": true,
    "registry_id": 1,
    "metadata": {
      "public": "true"
    }
  }'

Étape 3 : Utiliser le projet proxy cache

Tirer des images

Tirez des images via le projet proxy cache :

# Tirer une image officielle Docker Hub via le cache
docker pull registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/docker-hub-cache/library/nginx:latest

# Tirer une image d'un dépôt utilisateur via le cache
docker pull registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/docker-hub-cache/myuser/myimage:v1.0

# Tirer une image AWS ECR via le cache
docker pull registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/aws-ecr-cache/my-app:latest

Dans Kubernetes

Configurez Kubernetes pour tirer depuis le proxy cache :

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - name: nginx
    image: registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/docker-hub-cache/library/nginx:latest

Dans Docker Compose

version: '3'
services:
  nginx:
    image: registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/docker-hub-cache/library/nginx:latest

Étape 4 : Configurer le pull-through d'images

Mise en cache automatique

Lorsque vous tirez une image via un projet proxy cache :

Harbor vérifie si l'image existe localement
Si elle n'est pas trouvée :
- Harbor tire l'image depuis le registry amont
- La stocke dans le projet proxy cache
- La retourne au client
Les pulls ultérieurs servent l'image en cache

Comportement du cache

Scénario	Comportement
Premier pull	Tirer depuis l'amont, mettre en cache localement
Pulls suivants	Servir depuis le cache
Nouveau tag en amont	Tirer et mettre en cache la nouvelle version
Image supprimée en amont	Continuer à servir la version en cache
Amont non disponible	Servir la version en cache si disponible

Configuration avancée

Mettre en cache plusieurs registries

Créez des projets proxy cache séparés pour différents registries amonts :

Nom du Projet	Registry Amont	Cas d'utilisation
`docker-hub-cache`	Docker Hub	Images officielles, dépôts Docker Hub
`aws-ecr-cache`	AWS ECR	Images AWS privées
`gcr-cache`	Google GCR	Images Google Cloud
`quay-cache`	Quay.io	Dépôts Quay

Cache en cascade (multi-niveaux)

Configurez le proxy cache Harbor-vers-Harbor :

External Registry → Harbor Instance A (Prod) → Harbor Instance B (DR)

Créez des endpoints pointant vers d'autres registries Numspot :

curl -X POST "https://registry-{dest-id}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/registries" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "harbor-prod",
    "type": "harbor",
    "url": "https://registry-{source-id}.hcp.cloudgouv-eu-west-1.numspot.com",
    "credential": {
      "access_key": "admin",
      "access_secret": "source-registry-password"
    }
  }'

Surveillance du proxy cache

Consulter les images en cache

Naviguez vers le projet proxy cache dans l'interface Harbor
Consultez les dépôts pour voir les images en cache
Vérifiez le nombre de pulls et la date du dernier pull

Via API

# Lister les dépôts dans le projet proxy cache
curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/docker-hub-cache/repositories" \
  -u "admin:{password}"

# Obtenir les détails d'un dépôt
curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/docker-hub-cache/repositories/library%2Fnginx" \
  -u "admin:{password}"

Statistiques du cache

Surveillez les performances du cache :

Taux de succès : Pourcentage de pulls servis depuis le cache
Utilisation du stockage : Espace consommé par les images en cache
Fréquence de pull : Images les plus fréquemment tirées
Latence amont : Temps pour tirer depuis l'amont en cas de cache miss

Maintenance du cache

Rafraîchissement manuel du cache

Forcez le rafraîchissement des images en cache :

Naviguez vers le projet proxy cache
Sélectionnez le dépôt
Cliquez sur Delete pour supprimer l'image en cache
Tirez à nouveau l'image pour la rafraîchir depuis l'amont

Via API

# Supprimer un dépôt en cache
curl -X DELETE "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/docker-hub-cache/repositories/library%2Fnginx" \
  -u "admin:{password}"

Nettoyage automatique du cache

Configurez des politiques de rétention :

Naviguez vers Administration → Configuration → System Settings
Définissez Artifact Read-only pour des projets spécifiques
Configurez le nettoyage automatique (voir Nettoyage automatique)

Bonnes pratiques

Performance

Proximité géographique : Créez des projets proxy cache dans des régions proches de vos workloads
Pré-chauffage du cache : Tirez les images fréquemment utilisées avant le déploiement en production
Utilisez des projets publics : Rendez les projets proxy cache publics pour éviter la surcharge d'authentification
Surveillez l'utilisation : Suivez les taux de succès du cache et ajustez la stratégie en conséquence

Sécurité

Validez les images amont : Activez l'analyse de vulnérabilités pour les images en cache
Utilisez des images signées : Configurez des politiques de confiance pour les registries amonts
Limitez l'accès : Utilisez des projets proxy cache privés pour les images sensibles
Auditez les pulls : Consultez les journaux d'audit pour les accès au proxy cache

Opérations

Définissez des quotas de stockage : Configurez des quotas sur les projets proxy cache pour empêcher une croissance non bornée
Nettoyage régulier : Mettez en œuvre des politiques de nettoyage automatique
Surveillez l'amont : Surveillez la disponibilité du registry amont et mettez à jour les endpoints si nécessaire
Documentez les correspondances : Maintenez une documentation des correspondances entre projets proxy cache et registries amonts

Résolution des problèmes

Problème 1 : image non mise en cache

Symptôme : Les pulls sont lents, les images n'apparaissent pas dans le projet proxy cache

Solutions :

Vérifiez que le projet proxy cache est correctement configuré
Vérifiez la configuration de l'endpoint et les identifiants
Vérifiez la connectivité réseau vers le registry amont
Consultez les journaux Harbor :

kubectl logs -n registry-instance-{registryId} deployment/harbor-core

Problème 2 : échec d'authentification

Symptôme : Impossible de tirer des images privées via le proxy cache

Solutions :

Vérifiez que les identifiants de l'endpoint sont corrects
Vérifiez que les identifiants ont les permissions de pull sur le registry amont
Mettez à jour les identifiants de l'endpoint s'ils ont expiré
Testez la connexion de l'endpoint dans l'interface Harbor

Problème 3 : images en cache obsolètes

Symptôme : Les images en cache sont datées

Solutions :

Supprimez le dépôt en cache pour forcer le rafraîchissement
Tirez avec un digest spécifique au lieu d'un tag
Configurez des politiques d'invalidation du cache
Utilisez le flag --no-cache pour contourner le cache

Problème 4 : limites de débit du registry amont

Symptôme : Impossible de tirer de nouvelles images, erreurs de limite de débit

Solutions :

Utilisez un endpoint authentifié (Docker Hub offre des limites plus élevées pour les utilisateurs authentifiés)
Pré-chauffez le cache pendant les heures creuses
Réduisez la fréquence de pull en utilisant des tags d'image stables
Envisagez de mettre en miroir les images critiques au lieu d'utiliser le proxy cache

Référence API

Créer un projet proxy cache

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

{
  "project_name": "string",
  "public": true,
  "registry_id": number,
  "metadata": {
    "public": "true"
  }
}

Lister les projets proxy cache

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

Obtenir les détails d'un projet

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

Lister les dépôts en cache

GET /api/v2.0/projects/{project_name}/repositories
Authorization: Basic {base64(admin:password)}

Limitations

Le proxy cache est en lecture seule : Impossible de pousser des images vers les projets proxy cache
Les images sont mises en cache au premier pull : Pas de pre-fetching automatique
Le cache est basé sur les tags : L'utilisation de digests contourne la validation du cache
Le stockage est non borné par défaut : Configurez des quotas pour limiter la croissance
Disponibilité amont : Les cache misses nécessitent une connectivité avec le registry amont

Vue d'ensemble​

Avantages​

Registries amont pris en charge​

Fonctionnement du proxy cache​

Prérequis​

Étape 1 : Créer un endpoint de réplication​

Via l'interface Harbor​

Exemples de configuration d'endpoint​

Docker Hub (images publiques)​

Docker Hub (images privées)​

AWS ECR​

Google GCR​

Via API​

Étape 2 : Créer un projet proxy cache​

Via l'interface Harbor​

Via API​

Étape 3 : Utiliser le projet proxy cache​

Tirer des images​

Dans Kubernetes​

Dans Docker Compose​

Étape 4 : Configurer le pull-through d'images​

Mise en cache automatique​

Comportement du cache​

Configuration avancée​

Mettre en cache plusieurs registries​

Cache en cascade (multi-niveaux)​

Surveillance du proxy cache​

Consulter les images en cache​

Via API​

Statistiques du cache​

Maintenance du cache​

Rafraîchissement manuel du cache​

Via API​

Nettoyage automatique du cache​

Bonnes pratiques​

Performance​

Sécurité​

Opérations​

Résolution des problèmes​

Problème 1 : image non mise en cache​

Problème 2 : échec d'authentification​

Problème 3 : images en cache obsolètes​

Problème 4 : limites de débit du registry amont​

Référence API​

Créer un projet proxy cache​

Lister les projets proxy cache​

Obtenir les détails d'un projet​

Lister les dépôts en cache​

Limitations​

Vue d'ensemble

Avantages

Registries amont pris en charge

Fonctionnement du proxy cache

Prérequis

Étape 1 : Créer un endpoint de réplication

Via l'interface Harbor

Exemples de configuration d'endpoint

Docker Hub (images publiques)

Docker Hub (images privées)

AWS ECR

Google GCR

Via API

Étape 2 : Créer un projet proxy cache

Via l'interface Harbor

Via API

Étape 3 : Utiliser le projet proxy cache

Tirer des images

Dans Kubernetes

Dans Docker Compose

Étape 4 : Configurer le pull-through d'images

Mise en cache automatique

Comportement du cache

Configuration avancée

Mettre en cache plusieurs registries

Cache en cascade (multi-niveaux)

Surveillance du proxy cache

Consulter les images en cache

Via API

Statistiques du cache

Maintenance du cache

Rafraîchissement manuel du cache

Via API

Nettoyage automatique du cache

Bonnes pratiques

Performance

Sécurité

Opérations

Résolution des problèmes

Problème 1 : image non mise en cache

Problème 2 : échec d'authentification

Problème 3 : images en cache obsolètes

Problème 4 : limites de débit du registry amont

Référence API

Créer un projet proxy cache

Lister les projets proxy cache

Obtenir les détails d'un projet

Lister les dépôts en cache

Limitations