infrastructure/docs/06-configuration-consul.md

Configuration Consul

Presentation

Consul est un outil de service discovery et de configuration distribuee. Dans cette infrastructure, il permet :

• Decouverte automatique des services Docker
• Resolution DNS des services (ex: gitea.service.consul)
• Health checks centralises
• Interface web de gestion
• Controle d'acces via ACL (mode production)

Fichiers de configuration

• consul/docker-compose.yml : Configuration Docker Compose
• consul/env.template : Template pour les variables d'environnement

Configuration production (avec ACL)

docker-compose.yml

services:
  consul:
    container_name: consul
    image: hashicorp/consul:latest
    restart: unless-stopped
    command: agent -server -ui -node=server-1 -bootstrap-expect=1 -client=0.0.0.0
    
    ports:
      - "8500:8500"      # UI web et API HTTP
      - "8600:8600/udp"  # DNS
      - "8600:8600/tcp"  # DNS
    
    environment:
      # Configuration ACL pour la production
      CONSUL_LOCAL_CONFIG: >-
        {
          "acl": {
            "enabled": true,
            "default_policy": "deny",
            "enable_token_persistence": true
          }
        }
    
    volumes:
      - consul-data:/consul/data
    
    networks:
      gitgit_syoul_fr_gitea_net:
        aliases:
          - consul
    
    healthcheck:
      test: ["CMD", "consul", "members"]
      interval: 10s
      timeout: 3s
      retries: 3

volumes:
  consul-data:

networks:
  gitgit_syoul_fr_gitea_net:
    external: true

Configuration ACL

Politique de securite

Parametre	Valeur	Description
acl.enabled	true	Active le systeme ACL
acl.default_policy	deny	Tout est interdit par defaut
acl.enable_token_persistence	true	Tokens sauvegardes sur disque

Types de tokens

Token	Usage	Permissions
Bootstrap (admin)	Administration Consul	Toutes
Registrator	Enregistrer des services	service:write, node:read, agent:read
Lecture seule	UI, monitoring	service:read, node:read

Initialisation des ACL

Apres le premier demarrage de Consul :

# 1. Bootstrap des ACL (genere le token admin)
docker exec consul consul acl bootstrap

Resultat :

AccessorID:       xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
SecretID:         yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy  <-- TOKEN ADMIN
Description:      Bootstrap Token (Global Management)
Local:            false
Create Time:      2025-01-01 00:00:00.000000000 +0000 UTC
Policies:
   00000000-0000-0000-0000-000000000001 - global-management

IMPORTANT : Notez le SecretID, c'est votre token administrateur.

Creer un token pour Registrator

# 2. Creer la policy pour Registrator
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"

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

Notez le SecretID du token Registrator pour configurer Registrator.

Creer un token de lecture (optionnel)

Pour l'acces a l'UI en lecture seule :

# Creer la policy de lecture
docker exec consul consul acl policy create \
  -name "read-only" \
  -description "Policy lecture seule" \
  -rules '
service_prefix "" {
  policy = "read"
}
node_prefix "" {
  policy = "read"
}
key_prefix "" {
  policy = "read"
}
' \
  -token "VOTRE_TOKEN_ADMIN"

# Creer le token
docker exec consul consul acl token create \
  -description "Token lecture seule" \
  -policy-name "read-only" \
  -token "VOTRE_TOKEN_ADMIN"

Options de la commande

Option	Description
-server	Mode serveur (vs client)
-ui	Active l'interface web
-node=server-1	Nom du noeud
-bootstrap-expect=1	Nombre de serveurs attendus (1 pour mode standalone)
-client=0.0.0.0	Ecoute sur toutes les interfaces

Ports

Port	Protocole	Description
8500	TCP	API HTTP et UI web
8600	TCP/UDP	DNS
8300	TCP	Communication serveur-a-serveur
8301	TCP/UDP	Gossip LAN
8302	TCP/UDP	Gossip WAN

Interface web

Accessible sur : http://[serveur]:8500

Avec ACL : Utilisez le token admin ou un token de lecture pour acceder a l'UI.

Sections principales

• Services : Liste des services enregistres
• Nodes : Liste des noeuds Consul
• Key/Value : Stockage cle-valeur
• ACL : Gestion des tokens et policies

API HTTP avec ACL

Authentification

Ajouter le header X-Consul-Token ou le parametre ?token= :

# Via header
curl -H "X-Consul-Token: VOTRE_TOKEN" http://localhost:8500/v1/catalog/services

# Via parametre
curl "http://localhost:8500/v1/catalog/services?token=VOTRE_TOKEN"

Lister les services

curl -H "X-Consul-Token: $CONSUL_TOKEN" http://localhost:8500/v1/catalog/services

Details d'un service

curl -H "X-Consul-Token: $CONSUL_TOKEN" http://localhost:8500/v1/catalog/service/gitea

Etat du cluster

curl http://localhost:8500/v1/status/leader  # Ne necessite pas de token
curl http://localhost:8500/v1/status/peers

Health checks

curl -H "X-Consul-Token: $CONSUL_TOKEN" http://localhost:8500/v1/health/service/gitea

DNS Consul

Le DNS Consul ne necessite pas de token par defaut.

Resolution d'un service

# Depuis le serveur
dig @localhost -p 8600 gitea.service.consul

# Depuis un conteneur Docker
docker exec consul dig @127.0.0.1 -p 8600 gitea.service.consul

Format des noms DNS

• <service>.service.consul : Service global
• <service>.service.<datacenter>.consul : Service dans un datacenter specifique
• <node>.node.consul : Noeud specifique

Utilisation avec les autres services

Configurer un service pour utiliser Consul DNS

Dans docker-compose.yml :

services:
  mon-service:
    dns:
      - 172.18.0.X  # IP du conteneur Consul
    dns_search:
      - service.consul

Exemple avec Woodpecker

services:
  woodpecker-server:
    environment:
      WOODPECKER_GITEA_URL: "http://gitea.service.consul:3000"
    dns:
      - 172.18.0.X

Maintenance

Verifier l'etat

docker exec consul consul members

Lister les tokens

docker exec consul consul acl token list -token "VOTRE_TOKEN_ADMIN"

Revoquer un token

docker exec consul consul acl token delete -id "TOKEN_ACCESSOR_ID" -token "VOTRE_TOKEN_ADMIN"

Voir les logs

docker logs consul -f

Forcer la deregistration d'un service

curl -X PUT -H "X-Consul-Token: $CONSUL_TOKEN" \
  http://localhost:8500/v1/agent/service/deregister/[service-id]

Sauvegarder les donnees

docker exec consul consul snapshot save /consul/data/backup.snap -token "VOTRE_TOKEN_ADMIN"
docker cp consul:/consul/data/backup.snap ./consul_backup_$(date +%Y%m%d).snap

Restaurer une sauvegarde

docker cp ./backup.snap consul:/consul/data/backup.snap
docker exec consul consul snapshot restore /consul/data/backup.snap -token "VOTRE_TOKEN_ADMIN"

Depannage

Erreur "Permission denied" ou "ACL not found"

Le token utilise n'a pas les permissions necessaires.

# Verifier les permissions du token
docker exec consul consul acl token read -id "TOKEN_ACCESSOR_ID" -token "VOTRE_TOKEN_ADMIN"

Consul ne demarre pas

# Verifier les logs
docker logs consul

# Verifier le volume
docker volume inspect consul-data

Services non visibles

# Verifier que Registrator fonctionne
docker logs registrator

# Verifier que Registrator a un token valide
docker exec registrator env | grep CONSUL

# Verifier les health checks
curl -H "X-Consul-Token: $CONSUL_TOKEN" http://localhost:8500/v1/health/checks/[service-name]

Erreur DNS

# Tester la resolution
dig @localhost -p 8600 consul.service.consul

# Verifier que le port 8600 est accessible
netstat -tuln | grep 8600

Securite - Recommandations production

1. ACL activees (fait)

La configuration actuelle active les ACL avec default_policy: deny.

2. Restreindre l'acces reseau

Ne pas exposer le port 8500 sur Internet. Utiliser un VPN ou un reverse proxy authentifie.

3. Configurer TLS (optionnel)

Pour chiffrer les communications :

environment:
  CONSUL_LOCAL_CONFIG: >-
    {
      "acl": {
        "enabled": true,
        "default_policy": "deny",
        "enable_token_persistence": true
      },
      "verify_incoming": true,
      "verify_outgoing": true,
      "verify_server_hostname": true,
      "ca_file": "/consul/config/ca.pem",
      "cert_file": "/consul/config/server.pem",
      "key_file": "/consul/config/server-key.pem"
    }

4. Rotation des tokens

Changer regulierement les tokens et revoquer les anciens.

Haute disponibilite

Pour un cluster de production, deployer au moins 3 serveurs Consul :

services:
  consul-1:
    command: agent -server -node=server-1 -bootstrap-expect=3 ...
  consul-2:
    command: agent -server -node=server-2 -join=consul-1 ...
  consul-3:
    command: agent -server -node=server-3 -join=consul-1 ...