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

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

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

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

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

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

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

### Details d'un service

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

### Etat du cluster

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

### Health checks

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

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

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

### Exemple avec Woodpecker

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

## Maintenance

### Verifier l'etat

```bash
docker exec consul consul members
```

### Lister les tokens

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

### Revoquer un token

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

### Voir les logs

```bash
docker logs consul -f
```

### Forcer la deregistration d'un service

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

### Sauvegarder les donnees

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

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

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

### Consul ne demarre pas

```bash
# Verifier les logs
docker logs consul

# Verifier le volume
docker volume inspect consul-data
```

### Services non visibles

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

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

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

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