Gestion des certificats TLS

Gérez les certificats TLS 1.3 pour la communication gRPC agent-vers-Hub. Couvre le mode CA auto-signée générée automatiquement et la configuration de certificats personnalisés avec votre propre PKI.

Le Hub utilise TLS 1.3 pour toutes les communications agent↔Hub sur le port gRPC (50051). Deux modes sont disponibles : auto (défaut) et custom.

Mode auto (défaut)

Avec TLS_MODE=auto, le Hub génère une autorité de certification (CA) auto-signée et un certificat serveur au premier démarrage. Ils sont stockés dans le volume Docker pki_data et réutilisés à chaque démarrage suivant.

pki_data/
├── ca.pem       # certificat CA, envoyé aux agents à l'enrôlement
├── ca.key       # clé privée CA
├── server.pem   # certificat serveur, signé par la CA
└── server.key   # clé privée serveur

Les deux certificats utilisent des clés ECDSA P-256.

Certificat	CN	Validité
CA	`watchflare CA`	10 ans
Serveur	`watchflare`	5 ans

À l’enrôlement, le Hub envoie le certificat CA à l’agent. L’agent l’épingle pour toutes les connexions futures, sans distribution manuelle de certificat. Sous Linux, il est enregistré dans /etc/watchflare/ca.pem, et sous macOS dans $(brew --prefix)/etc/watchflare/ca.pem.

Attention

En mode auto, le Hub régénère la CA et le certificat serveur ensemble. Il n’est pas possible de renouveler le certificat serveur seul. Si vous supprimez server.pem pour forcer un renouvellement, la CA sera également remplacée et tous les agents enrôlés devront être réenrôlés.

Mode custom

Avec TLS_MODE=custom, le Hub utilise vos propres certificats. C’est utile si vous avez une PKI interne existante.

Ajoutez ces variables à votre .env :

TLS_MODE=custom
TLS_CERT_FILE=/certs/server.pem
TLS_KEY_FILE=/certs/server.key
TLS_CA_FILE=/certs/ca.pem

Montez votre répertoire de certificats dans le conteneur Hub :

services:
  watchflare:
    volumes:
      - pki_data:/var/lib/watchflare/pki
      - /etc/ssl/watchflare:/certs:ro

Contraintes

TLS_CA_FILE doit être la CA qui a signé TLS_CERT_FILE. Cette CA est renvoyée aux agents à l’enrôlement et épinglée de leur côté.
TLS 1.3 est obligatoire. Le Hub rejette les connexions en dessous de cette version, quel que soit le mode.
Le certificat serveur n’a pas besoin de correspondre au nom d’hôte du Hub. La valeur server_name dans agent.conf (défaut : watchflare) doit figurer dans les SAN DNS du certificat (Go vérifie les SAN, pas le CN). Utiliser HostSNI("*") sur votre reverse proxy évite tout décalage de nom. Voir Reverse proxy.

Attention

Si vous remplacez la CA après que les agents se soient enrôlés, ces agents rejetteront le nouveau certificat, car la CA qu’ils ont épinglée ne correspond plus. Vous devrez réenrôler chaque agent concerné.

Inspecter les certificats

Pour inspecter les certificats générés automatiquement depuis l’intérieur du conteneur :

docker exec watchflare openssl x509 -in /var/lib/watchflare/pki/ca.pem -noout -text
docker exec watchflare openssl x509 -in /var/lib/watchflare/pki/server.pem -noout -text

Port gRPC et reverse proxies

Le port gRPC (50051) ne doit pas être terminé en TLS par un reverse proxy. Les agents épinglent la CA du Hub, donc tout certificat d’une CA différente est rejeté. Configurez votre proxy en passthrough TCP. Voir Reverse proxy.