# 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

```yaml
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` :

```bash
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](06-configuration-consul.md#creer-un-token-pour-registrator) pour les instructions detaillees.

Resume rapide :

```bash
# 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 :

```yaml
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

```yaml
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

```yaml
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

```yaml
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

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

## Verification

### Services enregistres

```bash
# 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

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

### Logs Registrator

```bash
docker logs registrator -f
```

## Maintenance

### Redemarrer Registrator

```bash
cd /opt/registrator
docker compose restart
```

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

### Forcer une resynchronisation

```bash
# 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 :

```bash
# 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.

```bash
# 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

```bash
# 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 :
   ```bash
   docker logs registrator
   ```

2. Verifier que le conteneur expose des ports :
   ```bash
   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 :
   ```bash
   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