Initial commit: Infrastructure Git CI/CD avec Gitea, Woodpecker, PostgreSQL, Consul et Registrator
This commit is contained in:
370
docs/07-configuration-registrator.md
Normal file
370
docs/07-configuration-registrator.md
Normal file
@ -0,0 +1,370 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user