infrastructure/docs/07-configuration-registrator.md

Configuration Registrator

Presentation

Registrator surveille automatiquement les conteneurs Docker et les enregistre dans Consul. Il detecte :

• Les nouveaux conteneurs demarres
• Les conteneurs arretes (deregistration automatique)
• Les ports exposes
• Les metadonnees (labels)

Fichiers de configuration

• registrator/docker-compose.yml : Configuration Docker Compose
• registrator/env.template : Template pour le token Consul

Configuration production (avec ACL)

docker-compose.yml

services:
  registrator:
    container_name: registrator
    image: gliderlabs/registrator:latest
    restart: unless-stopped
    
    env_file:
      - .env
    
    # -internal : utilise les IPs internes Docker
    # Le token est passe via la variable d'environnement CONSUL_HTTP_TOKEN
    command: -internal consul://consul:8500
    
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro
    
    networks:
      - gitgit_syoul_fr_gitea_net

networks:
  gitgit_syoul_fr_gitea_net:
    external: true

Fichier .env

Creer le fichier .env a partir du template env.template :

cp env.template .env

Contenu du fichier .env :

CONSUL_HTTP_TOKEN=votre-token-registrator-ici

IMPORTANT : Ne pas versionner le fichier .env dans git !

Configuration du token Registrator

Permissions requises

Le token Registrator doit avoir les permissions suivantes :

Ressource	Permission	Description
service_prefix ""	write	Enregistrer/desenregistrer des services
node_prefix ""	read	Lire les informations des noeuds
agent_prefix ""	read	Lire les informations des agents

Creer le token

Voir Configuration Consul pour les instructions detaillees.

Resume rapide :

# 1. Creer la policy
docker exec consul consul acl policy create \
  -name "registrator" \
  -description "Policy pour Registrator" \
  -rules '
service_prefix "" {
  policy = "write"
}
node_prefix "" {
  policy = "read"
}
agent_prefix "" {
  policy = "read"
}
' \
  -token "VOTRE_TOKEN_ADMIN"

# 2. Creer le token
docker exec consul consul acl token create \
  -description "Token Registrator" \
  -policy-name "registrator" \
  -token "VOTRE_TOKEN_ADMIN"

Options de la commande

Option	Description
-internal	Utilise les IPs internes Docker (vs IPs externes)
consul://consul:8500	Adresse du serveur Consul

Autres options disponibles

Option	Description
-ip	IP a utiliser pour l'enregistrement
-tags	Tags par defaut a ajouter
-resync	Intervalle de resynchronisation (ex: 60)
-deregister	Mode de deregistration : always, on-success
-cleanup	Nettoyer les services orphelins au demarrage

Variable d'environnement pour l'authentification

Variable	Description
CONSUL_HTTP_TOKEN	Token ACL pour s'authentifier aupres de Consul
CONSUL_HTTP_ADDR	Adresse de Consul (optionnel, defaut: localhost:8500)

Montage du socket Docker

Le montage /var/run/docker.sock:/tmp/docker.sock:ro permet a Registrator de :

• Surveiller les evenements Docker
• Lire les metadonnees des conteneurs
• Mode lecture seule (:ro) pour la securite

Enregistrement automatique des services

Sans configuration

Par defaut, Registrator enregistre chaque port expose avec :

• Nom du service : nom du conteneur + port
• ID du service : conteneur:port
• Port : port expose

Avec labels Docker

Personnaliser l'enregistrement avec des labels :

services:
  gitea:
    labels:
      - "SERVICE_NAME=gitea"
      - "SERVICE_TAGS=web,git,vcs"
      - "SERVICE_3000_CHECK_HTTP=/api/v1/version"
      - "SERVICE_3000_CHECK_INTERVAL=10s"

Labels disponibles

Label	Description
SERVICE_NAME	Nom du service (override)
SERVICE_TAGS	Tags separes par des virgules
SERVICE_ID	ID personnalise
SERVICE_IGNORE	Ignorer ce conteneur (true)
SERVICE_<port>_NAME	Nom pour un port specifique
SERVICE_<port>_TAGS	Tags pour un port specifique
SERVICE_<port>_CHECK_HTTP	Health check HTTP
SERVICE_<port>_CHECK_TCP	Health check TCP
SERVICE_<port>_CHECK_SCRIPT	Health check script
SERVICE_<port>_CHECK_INTERVAL	Intervalle du health check
SERVICE_<port>_CHECK_TIMEOUT	Timeout du health check

Exemples de configuration avec labels

Gitea avec health check

services:
  gitea:
    container_name: gitea
    image: gitea/gitea:latest
    labels:
      - "SERVICE_NAME=gitea"
      - "SERVICE_TAGS=web,git"
      - "SERVICE_3000_CHECK_HTTP=/api/v1/version"
      - "SERVICE_3000_CHECK_INTERVAL=15s"
      - "SERVICE_3000_CHECK_TIMEOUT=5s"

PostgreSQL avec health check TCP

services:
  gitea_db:
    container_name: gitea_db
    image: postgres:14
    labels:
      - "SERVICE_NAME=gitea-db"
      - "SERVICE_TAGS=postgres,database"
      - "SERVICE_5432_CHECK_TCP=true"
      - "SERVICE_5432_CHECK_INTERVAL=10s"

Woodpecker Server

services:
  woodpecker-server:
    container_name: woodpecker-server
    image: woodpeckerci/woodpecker-server:latest
    labels:
      - "SERVICE_NAME=woodpecker"
      - "SERVICE_TAGS=ci,web"
      - "SERVICE_8000_CHECK_HTTP=/healthz"
      - "SERVICE_8000_CHECK_INTERVAL=10s"

Ignorer un conteneur

services:
  internal-service:
    labels:
      - "SERVICE_IGNORE=true"

Verification

Services enregistres

# Via API Consul (avec token)
curl -H "X-Consul-Token: $CONSUL_TOKEN" \
  http://localhost:8500/v1/catalog/services | python3 -m json.tool

# Via UI Consul
# http://[serveur]:8500/ui/dc1/services

Details d'un service

curl -H "X-Consul-Token: $CONSUL_TOKEN" \
  http://localhost:8500/v1/catalog/service/gitea | python3 -m json.tool

Logs Registrator

docker logs registrator -f

Maintenance

Redemarrer Registrator

cd /opt/registrator
docker compose restart

Note : Au redemarrage, Registrator re-scanne tous les conteneurs et les re-enregistre dans Consul.

Forcer une resynchronisation

# Option 1 : Redemarrer Registrator
docker restart registrator

# Option 2 : Utiliser l'option -resync
# (modifier la commande pour ajouter -resync 60)

Nettoyer les services orphelins

Si des services restent enregistres apres l'arret d'un conteneur :

# Via API Consul (avec token)
curl -X PUT -H "X-Consul-Token: $CONSUL_TOKEN" \
  http://localhost:8500/v1/agent/service/deregister/[service-id]

# Ou relancer Registrator avec -cleanup
docker run --rm \
  -v /var/run/docker.sock:/tmp/docker.sock \
  -e CONSUL_HTTP_TOKEN="$REGISTRATOR_TOKEN" \
  gliderlabs/registrator:latest \
  -cleanup consul://consul:8500

Depannage

Erreur "Permission denied" ou "ACL disabled"

Le token Registrator est invalide ou n'a pas les bonnes permissions.

# Verifier que le token est defini
docker exec registrator env | grep CONSUL

# Verifier les logs
docker logs registrator

# Tester le token manuellement
curl -H "X-Consul-Token: $REGISTRATOR_TOKEN" \
  http://localhost:8500/v1/agent/services

Registrator ne demarre pas

# Verifier que Consul est accessible
docker exec registrator wget -qO- http://consul:8500/v1/status/leader

# Verifier le socket Docker
docker exec registrator ls -la /tmp/docker.sock

Services non enregistres

1. Verifier les logs Registrator :

   docker logs registrator
   

2. Verifier que le conteneur expose des ports :

   docker inspect [conteneur] | grep -A 10 "ExposedPorts"
   

3. Verifier que le label SERVICE_IGNORE n'est pas defini

4. Verifier que le token a les permissions service:write

Health checks echouent

1. Verifier que le endpoint existe :

   docker exec [conteneur] curl -s http://localhost:[port]/[path]
   

2. Verifier les logs du service

3. Ajuster l'intervalle ou le timeout du health check

Securite

Token minimal

Utiliser un token avec les permissions minimales necessaires (voir section "Configuration du token Registrator").

Socket Docker en lecture seule

Le socket Docker est monte en lecture seule (:ro) pour limiter les risques.

Ne pas versionner les secrets

Le fichier .env contenant le token ne doit pas etre versionne dans git.

Alternatives

Si Registrator ne repond pas a vos besoins, considerez :

• Consul-Template : Generation de configuration basee sur Consul
• Traefik : Reverse proxy avec service discovery Docker natif
• Fabio : Load balancer base sur Consul