Harbor : le registre d'images pour les équipes DevSecOps

Ce guide vous montre comment installer et utiliser Harbor pour stocker vos images conteneur, scanner automatiquement les vulnérabilités et éviter les problèmes de rate limiting Docker Hub. Vous apprendrez à déployer Harbor via Docker Compose, configurer le proxy-cache pour mettre en cache Docker Hub, et créer des comptes robot pour vos pipelines CI/CD. Prérequis : un serveur Linux avec Docker installé.

Ce que vous allez apprendre

• Installer Harbor en production avec HTTPS
• Comprendre l'architecture et les fonctionnalités clés
• Configurer le proxy-cache pour Docker Hub (éviter le rate limiting)
• Créer des comptes robot pour vos pipelines CI/CD
• Scanner automatiquement les images avec Trivy
• Répliquer des images entre plusieurs registries

Qu'est-ce que Harbor ?

Harbor est un registre d'artefacts cloud-native open source, développé initialement par VMware et désormais projet CNCF graduated (le plus haut niveau de maturité). Pensez à Harbor comme un Docker Hub privé hébergé dans votre infrastructure, avec des fonctionnalités de sécurité intégrées.

Pourquoi ne pas utiliser Docker Hub directement ?

Docker Hub, le registre public par défaut, pose plusieurs problèmes en entreprise :

Problème	Impact	Solution Harbor
Rate limiting	100 pulls/6h en anonyme, builds CI/CD bloqués	Proxy-cache : 1 pull externe → N pulls internes
Disponibilité	Pannes Docker Hub = arrêt des déploiements	Images mises en cache localement
Sécurité	Pas de scan de vulnérabilités intégré	Trivy scanne chaque push automatiquement
Conformité	Images stockées chez un tiers (USA)	Données dans votre datacenter
Coût	Plans payants pour features avancées	Open source, fonctionnalités complètes

Glissez pour voir

Ce que Harbor gère

Harbor ne se limite plus aux images Docker. Depuis la version 2.x, il stocke également :

• Images de conteneurs : Docker, OCI, multi-architectures
• Helm charts : charts Kubernetes versionnés
• SBOM (depuis v2.11) : Software Bill of Materials pour la traçabilité
• Artefacts IA/ML (depuis v2.13) : modèles via CloudNativeAI

Architecture de Harbor

Harbor est composé de plusieurs services qui communiquent entre eux. Comprendre cette architecture vous aidera à diagnostiquer les problèmes et à dimensionner correctement votre installation.

Composants principaux :

Composant	Rôle	Pourquoi c'est important
NGINX	Reverse proxy, terminaison TLS	Point d'entrée unique, gestion HTTPS
Core	API REST, authentification, autorisation	Cerveau de Harbor
Registry	Stockage des images (Docker Distribution)	Où vos images sont réellement stockées
Trivy	Scan de vulnérabilités	Détecte les CVE dans vos images
JobService	Tâches asynchrones (réplication, scan, GC)	Travaux en arrière-plan
PostgreSQL	Base de données	Métadonnées, utilisateurs, projets
Redis	Cache et sessions	Performance et sessions utilisateurs

Glissez pour voir

Fonctionnalités de sécurité intégrées

Harbor intègre Trivy comme scanner de vulnérabilités par défaut. Chaque image poussée peut être automatiquement scannée pour détecter les CVE connues.

Workflow de scan :

1. Un développeur pousse une image
2. Harbor déclenche automatiquement Trivy
3. Trivy analyse chaque couche de l'image
4. Les résultats sont attachés à l'image dans l'interface
5. Si des vulnérabilités critiques sont détectées, le pull peut être bloqué

Contrôle d'accès et authentification

Harbor propose plusieurs méthodes d'authentification pour s'adapter à votre infrastructure :

• Base de données locale : pour les petites équipes ou les labs
• LDAP/Active Directory : intégration avec l'annuaire d'entreprise
• OIDC (OpenID Connect) : SSO avec Keycloak, Azure AD, Okta, Google
• Robot accounts : comptes techniques pour les pipelines CI/CD (voir section dédiée)

Installation de Harbor

Harbor peut être installé de deux manières selon votre environnement :

Méthode	Cas d'usage	Complexité
Docker Compose	Lab, petite équipe, serveur dédié	Simple
Helm sur Kubernetes	Production, haute disponibilité, cloud	Moyenne

Glissez pour voir

Dans ce guide, nous couvrons les deux méthodes. Commencez par Docker Compose pour vous familiariser avec Harbor, puis passez à Helm pour la production.

HTTPS obligatoire

En production, configurez toujours HTTPS avec des certificats valides (Let's Encrypt ou PKI d'entreprise). Docker refuse par défaut de communiquer avec un registre HTTP (sauf configuration explicite d'insecure-registries).

Prérequis système

Configuration matérielle et logicielle requise :

Ressource	Minimum (lab)	Recommandé (prod)	Pourquoi
CPU	2 cores	4 cores	Trivy consomme beaucoup lors des scans
RAM	4 Go	8 Go	PostgreSQL + Trivy + Redis
Disque	40 Go	160 Go+	Dépend du volume d'images stockées

Glissez pour voir

Logiciels requis :

• Docker Engine 20.10.10+
• Docker Compose v2 (ou v1.18+)
• OpenSSL (pour générer les certificats)

Ports réseau à ouvrir :

Port	Protocole	Usage
443	HTTPS	Portail Harbor et API (défaut)
80	HTTP	Redirection vers HTTPS
4443	HTTPS	Docker Content Trust (optionnel)

Glissez pour voir

Téléchargement de Harbor

Téléchargez l'installeur depuis le dépôt officiel GitHub. Deux options :

Installeur	Taille	Cas d'usage
Online	~50 Mo	Télécharge les images depuis Docker Hub à l'installation
Offline	~800 Mo	Images pré-incluses, pour environnements sans internet

Glissez pour voir

1. Télécharger l'archive

   cd /opt
   wget https://github.com/goharbor/harbor/releases/download/v2.15.2/harbor-offline-installer-v2.15.2.tgz

2. Vérifier l'authenticité

   Depuis fin 2025, Harbor ne signe plus ses archives en GPG (le fichier .asc a disparu) mais via Sigstore/cosign : un bundle .sigstore.json accompagne chaque archive, plus un fichier md5sum. Vérifiez d'abord l'intégrité, puis l'authenticité avec cosign :

   # Intégrité (md5)
   wget https://github.com/goharbor/harbor/releases/download/v2.15.2/md5sum
   grep offline md5sum | md5sum -c -
   
   # Authenticité (Sigstore/cosign)
   wget https://github.com/goharbor/harbor/releases/download/v2.15.2/harbor-offline-installer-v2.15.2.tgz.sigstore.json
   cosign verify-blob \
     --bundle harbor-offline-installer-v2.15.2.tgz.sigstore.json \
     --certificate-identity-regexp 'https://github.com/goharbor/harbor' \
     --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
     harbor-offline-installer-v2.15.2.tgz
   # Verified OK

3. Extraire l'archive

   tar xzvf harbor-offline-installer-v2.15.2.tgz
   cd harbor

Configuration de Harbor

Le fichier harbor.yml contient toute la configuration de Harbor. Copiez le template et éditez-le :

cp harbor.yml.tmpl harbor.yml
vi harbor.yml

Voici les paramètres essentiels à configurer :

# Nom d'hôte ou IP publique (jamais localhost en production)
hostname: registry.example.com

# Configuration HTTPS (obligatoire en production)
https:
  port: 443
  certificate: /opt/harbor/certs/server.crt
  private_key: /opt/harbor/certs/server.key

# Mot de passe admin initial (changez-le !)
harbor_admin_password: VotreMotDePasseSecurise

# Répertoire de stockage des images
data_volume: /data

# Activer Trivy pour le scan de vulnérabilités
trivy:
  ignore_unfixed: false          # Inclure les CVE sans correctif
  security_check: vuln,config,secret
  skip_update: false             # Mettre à jour la base de CVE

Mot de passe admin

Le mot de passe par défaut Harbor12345 doit être modifié avant la mise en production. Ce paramètre n'est utilisé qu'au premier démarrage ; ensuite, changez-le via l'interface web.

Lancement de l'installation

L'option --with-trivy active le scan de vulnérabilités :

sudo ./install.sh --with-trivy

Le script vérifie les prérequis, génère les configurations et démarre les conteneurs. Une fois terminé :

✔ ----Harbor has been installed and started successfully.----

Vous pouvez accéder à l'interface web d'Harbor via https://registry.example.com (ou l'URL configurée dans hostname).

Installation via Helm (Kubernetes)

Pour un déploiement sur Kubernetes en production, utilisez le chart Helm officiel. Cette méthode offre la haute disponibilité et une meilleure intégration avec l'écosystème cloud-native.

1. Ajouter le dépôt Helm Harbor

   helm repo add harbor https://helm.goharbor.io
   helm repo update

2. Créer un fichier de values personnalisé

   values-harbor.yaml

   expose:
     type: ingress
     ingress:
       hosts:
         core: harbor.example.com
     tls:
       enabled: true
       certSource: secret
       secret:
         secretName: harbor-tls
   
   externalURL: https://harbor.example.com
   
   persistence:
     enabled: true
     persistentVolumeClaim:
       registry:
         size: 100Gi
   
   trivy:
     enabled: true
   
   harborAdminPassword: "VotreMotDePasseSecurise"

3. Installer Harbor

   helm install harbor harbor/harbor \
     --namespace harbor \
     --create-namespace \
     -f values-harbor.yaml

4. Vérifier le déploiement

   kubectl -n harbor get pods

Consultez la documentation Helm Harbor pour les options avancées (HA multi-réplicas, stockage S3, PostgreSQL externe...).

Premier accès

Lors du premier accès à Harbor :

1. Ouvrez https://harbor.example.com dans votre navigateur
2. Connectez-vous avec admin / Harbor12345 (ou le mot de passe configuré)
3. Changez immédiatement le mot de passe via Administration → Users

Utiliser Harbor au quotidien

Cette section couvre les opérations courantes : pousser une image, la récupérer, et comprendre le scan de vulnérabilités.

Pousser votre première image

Prenons un exemple concret : vous avez une application web simple à conteneuriser.

1. Créer un projet dans Harbor

   Avant de pousser une image, créez un projet dans l'interface Harbor : Projects → New Project → "monprojet". Un projet est comme un dossier qui regroupe des images liées (par application, par équipe, etc.).

2. Créer votre Dockerfile

   FROM nginx:1.31.3-alpine@sha256:4a73073bd557c65b759505da037898b61f1be6cbcc3c2c3aeac22d2a470c1752
   COPY index.html /usr/share/nginx/html/
   EXPOSE 80

3. Construire l'image

   docker build -t monserveurweb:0.1 .

4. Taguer l'image pour Harbor

   Le format du tag est : <harbor-url>/<projet>/<image>:<version>

   docker tag monserveurweb:0.1 registry.example.com/monprojet/monserveurweb:0.1

5. Se connecter à Harbor

   docker login registry.example.com
   # Entrez vos identifiants Harbor

6. Pousser l'image

   docker push registry.example.com/monprojet/monserveurweb:0.1

Vérification : Dans l'interface Harbor, naviguez vers Projects → monprojet. Vous devriez voir votre image avec son tag 0.1.

Comprendre le scan de vulnérabilités

Une fois l'image poussée, Harbor déclenche automatiquement un scan Trivy (si configuré). Dans l'interface :

1. Cliquez sur l'image pour voir ses tags
2. Cliquez sur un tag pour voir le détail
3. L'onglet Vulnerabilities affiche les CVE détectées

Interpréter les résultats :

Sévérité	Signification	Action recommandée
Critical	Faille exploitable à distance, impact majeur	Corriger immédiatement
High	Faille sérieuse	Corriger rapidement
Medium	Faille modérée	Planifier la correction
Low	Faille mineure	Corriger quand possible

Glissez pour voir

Bloquer les images vulnérables

Dans les paramètres du projet, vous pouvez activer "Prevent vulnerable images from running" pour bloquer le pull d'images avec des CVE critiques. C'est une bonne pratique pour les projets de production.

Configurer le proxy-cache

Le proxy-cache est l'une des fonctionnalités les plus utiles de Harbor. Il permet de mettre en cache les images de registries externes (Docker Hub, Quay, GCR...) pour :

• Éviter le rate limiting Docker Hub (100 pulls/6h en anonyme)
• Accélérer les pulls (images servies depuis votre réseau local)
• Garantir la disponibilité même si Docker Hub est en panne

Comment fonctionne le proxy-cache ?

Premier pull : Harbor récupère l'image depuis Docker Hub, la stocke localement, et la sert au client.

Pulls suivants : Harbor sert l'image depuis son cache local. Docker Hub n'est pas contacté (sauf pour vérifier les mises à jour).

Configurer un proxy-cache Docker Hub

1. Créer un endpoint de registry

   Dans l'interface Harbor : Administration → Registries → New Endpoint

   Champ	Valeur
   Provider	Docker Hub
   Name	dockerhub
   Endpoint URL	https://hub.docker.com
   Access ID	(optionnel, votre username Docker Hub)
   Access Secret	(optionnel, votre token Docker Hub)

   Glissez pour voir

   Cliquez sur Test Connection pour vérifier, puis OK.

2. Créer un projet proxy-cache

   Projects → New Project

   Champ	Valeur
   Project Name	dockerhub-proxy
   Access Level	Public (ou Private selon vos besoins)
   Proxy Cache	✅ Activé
   Registry	dockerhub (l'endpoint créé à l'étape 1)

   Glissez pour voir

3. Utiliser le proxy-cache

   Au lieu de :

   docker pull nginx:latest

   Utilisez :

   docker pull registry.example.com/dockerhub-proxy/library/nginx:latest

   Pour les images non-officielles :

   docker pull registry.example.com/dockerhub-proxy/bitnami/redis:latest

Intégration avec Kubernetes

Dans un cluster Kubernetes, configurez les pods pour utiliser le proxy-cache en préfixant les images. Vous pouvez aussi utiliser kube-image-keeper (kuik) pour automatiser cette réécriture.

Registries supportés

Harbor supporte le proxy-cache pour de nombreux registries :

• Docker Hub
• Quay.io
• GitHub Container Registry (ghcr.io)
• AWS ECR
• Azure ACR
• Google Container Registry
• JFrog Artifactory

Nouveautés Harbor 2.15

Depuis Harbor 2.15, vous pouvez limiter le nombre de connexions vers le registry amont par projet proxy-cache (max_upstream_conn), pour ne pas saturer Docker Hub. La version ajoute aussi la vérification des signatures Cosign v3 (format bundle) et le support d'un certificat CA par endpoint de réplication.

Comptes robot pour la CI/CD

Les robot accounts sont des comptes techniques conçus pour les pipelines CI/CD. Contrairement aux comptes utilisateurs, ils :

• N'ont pas accès à l'interface web
• Ont des permissions limitées (push/pull uniquement)
• Peuvent être révoqués sans impacter les utilisateurs
• Ont une durée de vie configurable

Créer un compte robot

1. Naviguer vers le projet

   Projects → votre-projet → Robot Accounts

2. Créer le robot

   Cliquez sur New Robot Account :

   Champ	Valeur recommandée
   Name	ci-pipeline
   Expiration	365 jours (ou selon votre politique)
   Permissions	Push Artifact, Pull Artifact

   Glissez pour voir

3. Sauvegarder les credentials

   Harbor affiche le token une seule fois. Copiez-le immédiatement et stockez-le dans votre gestionnaire de secrets (Vault, GitLab CI variables, GitHub Secrets...).

Utiliser dans GitLab CI

.gitlab-ci.yml

variables:
  HARBOR_URL: registry.example.com
  HARBOR_PROJECT: monprojet

build:
  stage: build
  script:
    - docker login -u "${HARBOR_ROBOT_USER}" -p "${HARBOR_ROBOT_TOKEN}" ${HARBOR_URL}
    - docker build -t ${HARBOR_URL}/${HARBOR_PROJECT}/myapp:${CI_COMMIT_SHA} .
    - docker push ${HARBOR_URL}/${HARBOR_PROJECT}/myapp:${CI_COMMIT_SHA}

Les variables HARBOR_ROBOT_USER et HARBOR_ROBOT_TOKEN sont définies dans Settings → CI/CD → Variables (type "masked").

Réplication entre registries

La réplication permet de synchroniser des images entre plusieurs instances Harbor ou vers d'autres registries. Cas d'usage :

• Multi-datacenter : répliquer les images vers un site de DR
• Edge computing : pré-pousser les images vers des clusters edge
• Migration : copier des images depuis un ancien registry

Modes de réplication

Mode	Direction	Cas d'usage
Push	Harbor → External	Distribuer vers d'autres registries
Pull	External → Harbor	Importer depuis Docker Hub, GCR, etc.

Glissez pour voir

Configurer une réplication push

1. Créer l'endpoint de destination

   Administration → Registries → New Endpoint

   Configurez l'accès au registry de destination (Harbor distant, ECR, etc.).

2. Créer une règle de réplication

   Administration → Replications → New Replication Rule

   Champ	Valeur
   Name	prod-datacenter-2
   Replication mode	Push-based
   Source resource filter	monprojet/**
   Destination registry	(l'endpoint créé)
   Trigger mode	Event Based (à chaque push)

   Glissez pour voir

3. Tester la réplication

   Poussez une image dans le projet source. Elle devrait apparaître dans le registry de destination après quelques secondes.

Dépannage

Les problèmes avec Harbor se manifestent généralement de deux façons : l'interface est inaccessible ou les opérations Docker échouent (login, push, pull). Voici les causes les plus fréquentes.

Problèmes d'installation

Symptôme	Cause probable	Solution
Harbor ne démarre pas	Conteneur en erreur	docker compose ps puis logs du conteneur en échec
Erreur "port already in use"	Port 443/80 déjà utilisé	Arrêter le service conflictuel ou changer le port
Interface inaccessible	HTTPS mal configuré	Vérifier les chemins des certificats dans harbor.yml
Erreur base de données	PostgreSQL corrompu	Vérifier les logs PostgreSQL dans /var/log/harbor/

Glissez pour voir

Problèmes de connexion Docker

Symptôme	Cause probable	Solution
x509: certificate signed by unknown authority	Certificat auto-signé non trusté	Ajouter le CA au système (voir ci-dessous)
unauthorized: authentication required	Mauvais credentials	Vérifier username/password, refaire docker login
denied: requested access to the resource is denied	Permissions insuffisantes	Vérifier les droits sur le projet Harbor
Timeout lors du push	Réseau ou firewall	Vérifier la connectivité sur le port 443

Glissez pour voir

Faire confiance à un certificat auto-signé

Si vous utilisez un certificat auto-signé (lab), vous devez l'ajouter au système :

Ubuntu/Debian

# Copier le certificat CA
sudo cp ca.crt /usr/local/share/ca-certificates/harbor-ca.crt
sudo update-ca-certificates

# Redémarrer Docker
sudo systemctl restart docker

RHEL/CentOS

# Copier le certificat CA
sudo cp ca.crt /etc/pki/ca-trust/source/anchors/harbor-ca.crt
sudo update-ca-trust

# Redémarrer Docker
sudo systemctl restart docker

Consulter les logs

Les logs Harbor sont stockés dans /var/log/harbor/ avec un fichier par composant :

# Logs du composant core (API)
tail -f /var/log/harbor/core.log

# Logs du registry
tail -f /var/log/harbor/registry.log

# Logs Trivy (scanner)
tail -f /var/log/harbor/trivy-adapter.log

Pour les installations Helm, utilisez kubectl :

kubectl -n harbor logs deployment/harbor-core -f

À retenir

• Harbor est un registre d'artefacts cloud-native qui stocke images Docker, Helm charts, SBOM et artefacts IA
• Le proxy-cache résout le rate limiting Docker Hub : 1 pull externe → N pulls internes
• Trivy scanne automatiquement les images pour détecter les CVE
• Les robot accounts sont essentiels pour la CI/CD : credentials dédiés, révocables, avec permissions minimales
• La réplication permet le multi-datacenter et la haute disponibilité
• HTTPS est obligatoire en production ; Docker refuse les registries HTTP par défaut
• Projet CNCF graduated = maturité et pérennité garanties

Prochaines étapes

Trivy : scanner de vulnérabilités Approfondissez le scan de sécurité : images, IaC, SBOM

kuik : cache d'images Kubernetes Automatisez le routage vers Harbor dans vos clusters

Cosign : signature d'images Signez vos images pour garantir leur intégrité

GitLab CI/CD Intégrez Harbor dans vos pipelines GitLab

×

📖 Voir la documentation →