## Introduction

La planification de la capacité Docker Hub n'est pas une devinette. Les équipes qui la traitent comme une réflexion après coup se heurtent à des limites de taux de tirage, épuisent leurs jetons d'API, remplissent les quotas de dépôts privés et ralentissent leurs pipelines d'intégration continue au pire moment possible. Un plan pratique transforme ces surprises en contraintes prévisibles et budgétisées que vous surveillez et ajustez avant qu'elles ne bloquent une version.

Ce guide s'adresse aux développeurs, aux consultants DevOps et aux équipes de startups qui exécutent des charges de travail conteneurisées, des petits projets annexes aux systèmes de production multi-services. Il relie quatre idées qui façonnent la capacité Docker Hub : la mise à l'échelle Docker Hub, les ressources Docker Hub, les limites Docker Hub et le dimensionnement Docker Hub. Tout au long, vous verrez des commandes concrètes, des chiffres réalistes, des sorties attendues et des étapes de récupération liées à chaque section.

L'état d'esprit opérationnel est simple : observez avant de modifier, limitez le rayon d'action de tout changement, utilisez des espaces réservés au lieu de secrets, vérifiez le résultat et documentez les chemins de récupération avant d'en avoir besoin.

## Inventaire des versions et de l'environnement

Avant de modifier une configuration Docker Hub, sachez avec quoi vous travaillez. Notez la version du moteur Docker, la version de Docker Compose le cas échéant, le point de terminaison du registre et la méthode d'authentification. Cet inventaire vous protège contre l'application d'instructions qui supposent une version de Docker ou un comportement de registre différent.

Exécutez d'abord ces commandes en lecture seule :

```bash
docker version --format '{{.Server.Version}}'
# Exemple de sortie : 24.0.7

docker compose version
# Exemple de sortie : Docker Compose version v2.23.0

docker info --format '{{.RegistryConfig.IndexHostname}}'
# Exemple de sortie : index.docker.io/v1/
```

Elles vous indiquent exactement le démon Docker avec lequel vous communiquez et s'il est configuré pour Docker Hub ou un miroir. Un piège courant est de supposer Docker Hub alors qu'un registre proxy d'entreprise est en réalité utilisé. Ce proxy peut avoir ses propres limites de capacité et un comportement de cache, invalidant les hypothèses sur le nombre de tirages.

Capturez l'état d'authentification actuel sans exposer les jetons :

```bash
docker system info | grep -A 5 -i username
# Exemple de sortie :
# Username: votre_nom_utilisateur_docker
# Registry: https://index.docker.io/v1/
```

Si vous avez un jeton d'accès Docker Hub stocké dans un fichier d'identification local, vérifiez son emplacement et ses permissions :

```bash
cat ~/.docker/config.json
# Exemple de sortie (tronquée) :
# {
#   "auths": {
#     "https://index.docker.io/v1/": {
#       "auth": "JETON_ENCODÉ_EN_BASE64"
#     }
#   }
# }
```

Le champ `auth` est encodé en base64, pas en texte brut. Ne l'imprimez jamais dans un journal de terminal partagé. Pour vérifier l'état actuel de la limite de taux du jeton, utilisez l'API Docker Hub :

```bash
TOKEN=$(cat ~/.docker/config.json | python3 -c "import sys, json, base64; print(base64.b64decode(json.load(sys.stdin)['auths']['https://index.docker.io/v1/']['auth']).decode().split(':')[1])")
curl -s -H "Authorization: Bearer $TOKEN" https://hub.docker.com/v2/rate-limits
# Exemple de sortie :
# {"rate_limit": {"limit": 100, "remaining": 97, "reset": 1712073600}}
```

Cela affiche le nombre de tirages restants pour la fenêtre actuelle (anonyme ou authentifié) et quand le compteur se réinitialise. Conservez cette sortie quelque part pour pouvoir comparer plus tard.

Un petit test local de type production devrait inclure un test de redémarrage : arrêtez un conteneur qui monte un volume nommé, recréez-le et confirmez que l'application voit toujours les fichiers attendus. Ce n'est pas spécifique à Docker Hub, mais cela protège vos expériences de planification de capacité contre la perte de données dans les écritures du système de fichiers du conteneur. Si les données disparaissent après un redémarrage, le service écrivait dans la couche du conteneur, pas dans un volume. Corrigez cela avant d'ajouter du trafic Docker Hub.

## Chemin de configuration sécurisé

Le chemin sécurisé pour la planification de la capacité Docker Hub comporte quatre étapes : mesure de référence, changement minimal, vérification et préparation de la restauration. Parcourons-les avec un exemple concret : augmenter le nombre de tirages d'images parallèles pour un travail CI basé sur BuildKit de 2 à 4.

### Mesure de référence

Commencez par votre débit de tirage actuel et votre taux d'échec. Pour un tirage d'image unique, mesurez le temps :

```bash
time docker pull alpine:3.19
# Exemple de sortie :
# real    0m3.412s
# user    0m0.045s
# sys     0m0.032s
```

Pour un pipeline CI qui tire plusieurs images, exécutez le pipeline et capturez le temps de l'étape. Si votre pipeline utilise Docker BuildKit avec un constructeur buildx, vérifiez le paramètre de parallélisme actuel :

```bash
docker buildx inspect --bootstrap --builder default | grep -i parallelism
# Aucune sortie par défaut signifie que BuildKit n'expose pas le parallélisme directement ; vérifiez plutôt max-parallelism dans la configuration BuildKit si vous utilisez un constructeur personnalisé.
```

Meilleure référence : enregistrez la durée totale du pipeline et le nombre d'images tirées. Par exemple, un travail qui tire 10 images séquentiellement prend 45 secondes. Cela fait 4,5 secondes par image en moyenne.

### Changement minimal

Ne modifiez qu'une seule variable. Supposons que vous vouliez paralléliser les tirages en utilisant la récupération d'images concurrente de BuildKit. Dans votre Dockerfile, utilisez `RUN --mount=type=cache,target=/var/cache/apt` pour les images basées sur apt, ou dans votre commande de construction, ajoutez `--progress=plain` pour voir le comportement de tirage. Pour contrôler explicitement le parallélisme dans Docker Compose, ajustez la variable d'environnement `COMPOSE_PARALLEL_LIMIT` :

```bash
export COMPOSE_PARALLEL_LIMIT=4
docker compose pull --parallel
# Sortie attendue : plusieurs tirages démarrent en même temps ; le temps total diminue.
```

Ou pour un fichier buildx bake :

```yaml
# docker-bake.hcl
group "default" {
  targets = ["app", "worker"]
}

target "app" {
  context = "."
  dockerfile = "Dockerfile.app"
  tags = ["myorg/app:latest"]
}

target "worker" {
  context = "."
  dockerfile = "Dockerfile.worker"
  tags = ["myorg/worker:latest"]
}
```

Exécutez `docker buildx bake --parallel` pour construire et pousser les deux images simultanément.

### Vérification

Après le changement, refaites la même mesure. Comparez l'avant et l'après :

- Avant : 10 images tirées séquentiellement en 45 secondes.
- Après : avec `COMPOSE_PARALLEL_LIMIT=4`, 10 images tirées en 18 secondes.

Vérifiez à nouveau la limite de taux Docker Hub pour vous assurer que vous n'avez pas consommé trop de quota de manière inattendue :

```bash
curl -s -H "Authorization: Bearer $TOKEN" https://hub.docker.com/v2/rate-limits
# Sortie : {"rate_limit": {"limit": 100, "remaining": 91, "reset": 1712073600}}
```

Nous avons consommé 6 tirages au lieu de 10 parce que certaines couches étaient mises en cache localement. C'est une information utile pour la planification de capacité : les couches mises en cache comptent différemment.

### Préparation de la restauration

Documentez le plan de restauration : remettez `COMPOSE_PARALLEL_LIMIT=2`, ou revenez à la commande de construction précédente. Conservez l'ancienne mesure dans une note. Si le nouveau parallélisme provoque une limitation de Docker Hub (en raison d'un trop grand nombre de connexions simultanées depuis une même IP), vous verrez des erreurs comme `toomanyrequests` ou `429 Too Many Requests`. La restauration est immédiate car il s'agit d'une variable d'environnement.

## Vérification et diagnostics

Après tout changement lié à la capacité, vérifiez que le système se comporte comme prévu et que vous pouvez diagnostiquer rapidement les problèmes. Deux indicateurs clés comptent : la consommation de la limite de taux de tirage et l'efficacité de la taille des images.

### Diagnostic de la limite de taux de tirage

Vérifiez votre statut actuel et l'historique de la limite de taux à l'aide de l'API de limites de taux de Docker Hub. La réponse inclut `limit`, `remaining` et `reset` (horodatage Unix). Utilisez jq pour l'analyser :

```bash
curl -s -H "Authorization: Bearer $TOKEN" https://hub.docker.com/v2/rate-limits | jq .
# Exemple de sortie :
# {
#   "rate_limit": {
#     "limit": 100,
#     "remaining": 85,
#     "reset": 1712073600
#   }
# }
```

Mettez en place un script de surveillance simple qui s'exécute toutes les quelques minutes et journalise les tirages restants. Par exemple :

```bash
#!/bin/bash
TOKEN=$(cat ~/.docker/config.json | python3 -c "import sys, json, base64; print(base64.b64decode(json.load(sys.stdin)['auths']['https://index.docker.io/v1/']['auth']).decode().split(':')[1])")
response=$(curl -s -H "Authorization: Bearer $TOKEN" https://hub.docker.com/v2/rate-limits)
echo "$(date -u +'%Y-%m-%dT%H:%M:%SZ') $(echo $response | jq -r '.rate_limit.remaining')" >> /var/log/docker_hub_rate.log
```

Planifiez-le avec cron toutes les 5 minutes. Vous pourrez ensuite tracer les tirages restants dans le temps et repérer les tendances avant qu'ils n'atteignent zéro.

### Diagnostic de la taille des images

Les grandes images consomment plus de bande passante de tirage et de stockage. Vérifiez la taille de vos images :

```bash
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"
# Exemple de sortie :
# REPOSITORY          TAG       SIZE
# myorg/app           latest    650MB
# myorg/worker        latest    220MB
```

Pour chaque image, inspectez ses couches pour trouver du superflu :

```bash
docker history myorg/app:latest
# Exemple de sortie (tronquée) :
# IMAGE          CREATED         CREATED BY                                      SIZE
# abc123         2 hours ago     RUN apt-get install -y build-essential        450MB
# def456         2 hours ago     COPY . /app                                     50MB
```

Une couche installant des outils de construction est souvent supprimable avec des constructions multi-étapes. Cela peut réduire l'image finale de 650 Mo à 120 Mo, diminuant le temps de tirage et la bande passante.

### Commandes de vérification après les changements

Après être passé à une image de base plus petite ou à une construction multi-étapes, vérifiez à nouveau le temps de tirage et la taille. Exemple :

```bash
time docker pull myorg/app:latest
# Avant : 6,5 s ; après : 1,8 s
docker images myorg/app:latest --format '{{.Size}}'
# Avant : 650 Mo ; après : 120 Mo
```

Vérifiez également que l'application fonctionne toujours correctement avec l'image plus petite. Si vous avez supprimé des paquets par accident, exécutez le contrôle de santé de votre conteneur :

```bash
curl -f http://localhost:8080/healthz && echo "OK"
# Attendu : OK
```

## Modes de défaillance et récupération

Les problèmes de capacité Docker Hub se répartissent généralement en quatre catégories. Pour chacune, voici le signal de défaillance, la cause, la récupération et la prévention.

### 1. Limite de taux de tirage dépassée

**Signal :** Vous voyez `toomanyrequests: You have reached your pull rate limit` ou des erreurs HTTP 429 dans les journaux CI.

**Cause :** Dépassement de la limite anonyme (actuellement 100 tirages par 6 heures par adresse IP) ou de la limite gratuite authentifiée (actuellement 200 tirages par 6 heures par utilisateur).

**Récupération immédiate :** Attendez l'horodatage de réinitialisation. Vérifiez votre nombre restant et l'heure de réinitialisation :

```bash
curl -s -H "Authorization: Bearer $TOKEN" https://hub.docker.com/v2/rate-limits | jq .rate_limit
# Sortie : {"limit": 200, "remaining": 0, "reset": 1712077200}
```

Convertissez l'horodatage `reset` en heure lisible :

```bash
date -u -d @1712077200
# Exemple : Mon Apr  1 12:00:00 UTC 2024
```

Si vous devez continuer immédiatement, passez à un abonnement Docker payant (Team ou Business) qui supprime les limites de taux, ou utilisez un miroir/cache de registre local (comme la mise en cache par tirage au niveau de l'organisation de Docker Hub, ou un outil comme Harbor avec cache proxy).

**Prévention :** Authentifiez tous les tirages CI avec un jeton utilisateur, pas anonyme. Surveillez les tirages restants et déclenchez des alertes lorsqu'ils passent sous un seuil (par ex., 50 restants). Utilisez la mise en cache des images dans la CI (par ex., la mise en cache des couches avec BuildKit ou la mise en cache des couches Docker dans GitHub Actions).

### 2. Quota de dépôt épuisé

**Signal :** Impossible de pousser une nouvelle étiquette : `denied: requested access to the resource is denied` ou `repository does not have enough storage`.

**Cause :** Le plan gratuit inclut un nombre limité de dépôts privés (actuellement 1 dépôt privé) ou un quota de stockage sur les dépôts privés.

**Récupération immédiate :** Supprimez les étiquettes anciennes ou inutilisées pour libérer de l'espace :

```bash
# Lister les étiquettes d'un dépôt
curl -s -H "Authorization: Bearer $TOKEN" https://hub.docker.com/v2/repositories/myorg/app/tags/ | jq -r '.results[].name'
# Exemple de sortie : latest, v1.0, v1.1, v1.2

# Supprimer une étiquette spécifique
curl -s -X DELETE -H "Authorization: Bearer $TOKEN" https://hub.docker.com/v2/repositories/myorg/app/tags/v1.0/
```

Ou passez à un plan avec plus de dépôts ou achetez du stockage supplémentaire.

**Prévention :** Mettez en œuvre une politique de nettoyage des étiquettes (par ex., gardez les 10 dernières versions, supprimez les plus anciennes). Automatisez le nettoyage avec les paramètres de dépôt de Docker Hub ou des scripts.

### 3. Expiration du jeton d'authentification

**Signal :** Les opérations échouent avec `unauthorized: authentication required` même si les informations d'identification étaient stockées.

**Cause :** Les jetons d'accès Docker Hub peuvent expirer (si vous définissez une date d'expiration) ou être révoqués. Les jetons d'accès personnels n'expirent pas par défaut mais peuvent être révoqués manuellement.

**Récupération immédiate :** Générez un nouveau jeton dans les paramètres Docker Hub et mettez à jour votre magasin d'identifiants :

```bash
docker login -u votre_nom_utilisateur
# Entrez le nouveau jeton comme mot de passe
```

Ou mettez à jour le fichier de configuration directement (encodez en base64 `nom_utilisateur:nouveau_jeton`).

**Prévention :** Définissez une date d'expiration pour tous les jetons CI et stockez-les dans un gestionnaire de secrets. Planifiez un rappel pour faire tourner les jetons avant l'expiration.

### 4. Limitation réseau par IP

**Signal :** Les tirages sont très lents ou expirent, mais l'API de limite de taux indique un nombre restant.

**Cause :** Docker Hub peut limiter les connexions depuis une seule IP si trop de requêtes simultanées se produisent, surtout pour les utilisateurs gratuits anonymes.

**Récupération immédiate :** Réduisez le parallélisme (définissez `COMPOSE_PARALLEL_LIMIT=2`), espacez les tirages ou utilisez une région adaptée au CDN.

**Prévention :** Authentifiez-vous pour éviter la limitation basée sur l'IP, utilisez un miroir local pour les images fortement utilisées et planifiez les gros lots de tirages pendant les heures creuses.

## Liste de contrôle des opérations

Utilisez cette liste de contrôle pour rendre la planification de la capacité Docker Hub opérationnelle. Chaque élément a un seul responsable et une fréquence de révision.

| Élément | Responsable (exemple) | Fréquence |
| --- | --- | --- |
| Surveiller le restant de la limite de taux de tirage | Ingénieure DevOps (Priya Shah) | Automatisé quotidiennement, révision hebdomadaire |
| Examiner l'utilisation du stockage des dépôts | Responsable de plateforme (Mark Chen) | Rapport hebdomadaire par e-mail, nettoyage mensuel |
| Faire tourner les jetons d'accès Docker Hub | Responsable de la sécurité (Alex Johnson) | Trimestriellement, ou immédiatement après le départ d'un membre de l'équipe |
| Évaluer les temps de tirage d'images dans la CI | Ingénieur CI/CD (Sam Lee) | Mensuellement, après tout changement de CI |
| Examiner le taux de réussite des opérations Docker Hub | Ingénieure de fiabilité des sites (Jordan Patel) | Hebdomadairement, avec revue d'incident |
| Tester la récupération après épuisement de la limite de taux | Ingénieure DevOps (Priya Shah) | Exercice semestriel |

Chaque responsable doit avoir accès aux tableaux de bord ou scripts pertinents et l'autorité de faire des changements dans son domaine.

### Pièges courants dans la planification de la capacité

Même avec une liste de contrôle, les équipes tombent dans des pièges prévisibles. Voici les plus fréquents et comment les éviter.

**Piège 1 : Traiter les limites de taux comme des nombres statiques.**
Docker Hub change occasionnellement les limites. Une équipe construit un plan autour de 100 tirages anonymes par 6 heures, puis Docker Hub le change à 200 ou introduit de nouvelles limites. Évitement : Abonnez-vous aux annonces officielles de Docker Hub et configurez une vérification programmée de l'API de limite de taux pour tout utilisateur. Récupération : Si votre plan casse, refaites la mesure de référence avec la nouvelle limite et ajustez la parallélisation.

**Piège 2 : Ignorer la mise en cache des couches d'images.**
Mal comprendre ce qui compte comme un tirage conduit à surestimer les besoins en capacité. Par exemple, un pipeline CI tire 20 images, mais 80 % des couches sont mises en cache, donc seulement 4 manifestes d'images touchent réellement Docker Hub. Évitement : Mesurez les nouveaux tirages réels en surveillant l'API de limite de taux avant et après une exécution de pipeline. Récupération : Si vous avez déjà dimensionné la capacité pour le pire cas sans cache, vous êtes peut-être surprovisionné, mais vous êtes en sécurité. Si vous avez dimensionné pour le cache et que le cache est invalidé, vous risquez de dépasser les limites ; revenez sur les changements récents de cache CI.

**Piège 3 : Partager un seul jeton entre tous les services.**
Si le jeton d'un service est compromis ou limité par le taux, tout s'arrête. Évitement : Utilisez des jetons séparés par service ou par équipe avec des libellés descriptifs (par ex., `ci-github`, `staging-k8s`, `backup-script`). Récupération : Si un jeton est compromis, révoquez-le immédiatement, émettez de nouveaux jetons et mettez à jour les services un par un. Documentez l'inventaire des jetons.

**Piège 4 : Ne pas tenir compte des constructions concurrentes.**
Une équipe active des constructions parallèles sur 10 branches et dépasse soudainement les limites de taux parce que chaque construction tire un ensemble complet d'images. Évitement : Estimez les tirages totaux comme `nombre_de_constructions x tirages_par_construction` et comparez avec votre limite de taux. Exemple : 10 constructions par heure, chacune tirant 5 images de Docker Hub = 50 tirages par heure. Si votre limite authentifiée est de 200 par 6 heures, vous êtes bon pour 6 heures mais vous atteindrez un mur lors d'une journée chargée. Récupération : Réduisez la concurrence des constructions, utilisez des images de base mises en cache, ou passez à un plan payant.

**Piège 5 : Négliger les contraintes des dépôts privés.**
Une équipe pousse de nombreuses petites images et atteint la limite de dépôts privés ou le quota de stockage. Évitement : Définissez une politique d'étiquetage et de rétention. Par exemple, ne gardez que les 5 dernières versions de production et 3 instantanés de développement. Utilisez les paramètres de dépôt de Docker Hub pour supprimer automatiquement les étiquettes de plus de 90 jours. Récupération : Nettoyez immédiatement les anciennes étiquettes, puis réévaluez si certains dépôts devraient être publics ou déplacés vers un registre auto-hébergé.

## Conclusion

La planification de la capacité Docker Hub est une pratique continue, pas une configuration unique. Les commandes et les seuils de ce guide vous donnent une base, mais la vraie valeur vient de la surveillance, de l'ajustement et de la répétition des défaillances avant qu'elles ne surviennent.

Commencez par une vérification à faible risque de la liste de contrôle des opérations. Par exemple, confiez à Priya Shah la mise en place d'une vérification quotidienne de la limite de taux avec alertes. Enregistrez les tirages restants actuels, exécutez la vérification et confirmez que l'alerte se déclenche lorsque le seuil est franchi. Passez ensuite en revue les dépendances : l'étiquetage des images, la configuration du miroir de registre et la rotation des jetons.

Un flux de travail fiable rend la défaillance visible : il protège les valeurs sensibles, limite les changements à la ressource prévue et définit la vérification de la récupération avant qu'un incident ne force la décision. Si vous suivez le chemin de configuration sécurisé et évitez les pièges courants, la mise à l'échelle des workflows de conteneurs sur Docker Hub devient une contrainte gérée plutôt qu'une panne surprise.