Agents privés

Vue d’ensemble

Un agent privé tourne dans votre propre infrastructure et surveille des services qu’OKStatus ne peut pas atteindre depuis internet — APIs internes, bases de données, apps intranet. Il récupère ses checks depuis OKStatus en HTTPS sortant uniquement : rien à exposer, aucun port entrant, pas de VPN. Disponible à partir du plan Max (Max : 5 agents, Enterprise : 20).

Déploiement

Cliquez sur Déployer un agent et choisissez comment il tournera : Binaire (systemd) sur un hôte Linux, Docker, Helm (Kubernetes), ou Sans état (variables d’env.). La fenêtre donne la commande exacte pour chacun. La suite de cette section suit le chart Helm, où il y a deux façons de donner son identité à l’agent — au choix.

D’où vient le chart

La fenêtre Déployer un agent du tableau de bord vous donne la commande exacte pour votre agent, avec le dépôt de charts, l’image et les identifiants déjà remplis — y compris les variantes Docker, Kubernetes (env) et script VPS. Le dépôt de charts n’est pas encore sur une URL publique : copiez la commande depuis là plutôt que de la retaper depuis cette page.

Recommandé : credentials sans état

Enrôlez-vous une fois pour obtenir la paire de credentials longue durée, puis lancez l’agent depuis un Secret — aucun jeton à consommer, aucun volume à persister, résilient à tout redémarrage ou reprogrammation :

helm install okstatus-agent okstatus/private-agent \
  --set credentials.agentId=<agentId> \
  --set credentials.agentSecret=<agentSecret>

Vous obtenez la paire depuis la page Agents privés : menu de l’agent (⋮) → Credentials stateless, ou l’onglet Kubernetes (env) du dialogue de déploiement puis Générer les credentials. Le secret n’est affiché qu’une seule fois ; régénérer le remplace.

Deux valeurs souvent confondues

• agentId est l’UUID de l’agent (ex. d3cf1947-…) — pas son nom (dc-milan-01). Un nom ici est rejeté avec 401 INVALID_AGENT_ID.
• agentSecret est le secret longue durée oksas_… — pas le jeton d’enrôlement oksa_live_…, à usage unique et réservé au mode jeton (OKSTATUS_TOKEN).

Pour un Deployment sans Helm, les variables d’environnement équivalentes sont OKSTATUS_AGENT_ID, OKSTATUS_AGENT_SECRET, OKSTATUS_AGENT_NAME et AGGREGATOR_URL=https://backend.okstatus.eu.

Ancien : jeton à usage unique

L’agent échange le jeton au premier démarrage et persiste le résultat dans un petit PVC (requis — sans lui, un redémarrage nécessite un nouveau jeton) :

helm install okstatus-agent okstatus/private-agent \
  --set token=oksa_live_xxxxxxxx

Le jeton vient de la page Agents privés et est à usage unique.

Ce que montre la page

Les quatre chiffres du haut couvrent le parc : agents en ligne sur ceux enrôlés, checks en cours par rapport à la capacité totale, checks exécutés sur la dernière heure, et nombre d’agents en retard sur la dernière version. Sélectionner un agent ouvre son détail : checks simultanés, checks et taux d’échec sur la dernière heure, une bande des heartbeats des 60 dernières minutes (un heartbeat manqué y laisse un trou), sa version, son nom d’hôte, son IP privée, sa plateforme et depuis quand il tourne.

Un agent déployé mais pas encore connecté affiche En attente de la première connexion.

Un agent = une seule instance en cours d’exécution

Les credentials d’un agent privé sont une identité unique. Exécutez exactement un pod par credential :

• Le chart fournit replicas: 1 et strategy: Recreate à dessein — jamais RollingUpdate (son surge ferait tourner brièvement deux pods et doublerait les heartbeats et les checks de cet agent).
• Le serveur l’impose aussi. Si une seconde instance démarre avec les mêmes credentials, le lease mono-instance du backend la rejette avec un 409 et ce pod s’arrête, en journalisant « another instance of this agent is already running ». Augmenter replicas, ou appliquer un second Deployment avec les mêmes credentials, ne donne pas plus de débit — les instances en trop s’arrêtent.

Pour plus d’agents, enrôlez plus d’agents

Ne réutilisez pas un credential sur plusieurs pods pour « scaler ». Déployez un autre agent depuis la page Agents privés — chacun a sa propre identité — et installez-le comme sa propre release. Chaque agent est un worker.

Lors d’un redémarrage propre, le pod partant libère son lease, donc un remplaçant prend le relais immédiatement ; après un kill brutal, un remplaçant prend le relais en ~2–3 minutes.

Créer et tester un monitor sur un agent

Dès que votre organisation a au moins un agent privé, la fenêtre Nouveau monitor demande d’abord d’où partent les checks :

• Réseau OKStatus — les régions publiques, pour ce qui est joignable depuis Internet ;
• Mes agents privés — choisissez directement un ou plusieurs de vos agents. Les adresses internes (10.0.0.5, redis.internal, *.svc.cluster.local…) sont autorisées.

En mode agent, le bouton devient Tester depuis l’agent : le test est exécuté par le premier agent sélectionné, depuis votre réseau, et sa vraie réponse s’affiche dans la fenêtre (par exemple REDIS · bureau-lyon). C’est une sonde ponctuelle : rien n’est enregistré, aucune alerte n’est envoyée, le statut du monitor ne change pas. Le bouton Tester du panneau d’édition fait de même pour un monitor dont toutes les régions sont privées.

Message	Que faire
Aucun agent privé en ligne	L’agent n’a pas envoyé de heartbeat depuis 5 minutes : vérifiez le pod ou le service.
L’agent … est trop ancien pour les tests	Mettez à jour l’image de l’agent. La surveillance continue ; seul le bouton Tester en a besoin.
L’agent … n’a pas répondu en 25 s	L’agent est en ligne mais saturé ou coupé de backend.okstatus.eu : consultez ses logs.

Les identifiants des monitors restent chiffrés

Les identifiants que porte un monitor — en-têtes et corps personnalisés, Basic auth, mots de passe de base de données, SMTP, IMAP ou Redis, clé d’API d’un fournisseur d’IA — sont chiffrés pour l’agent qui exécute le contrôle avant de quitter OKStatus. Chaque agent dérive une paire de clés de son propre secret et ne publie que la moitié publique ; les identifiants traversent la file des contrôles chiffrés, et seul cet agent peut les ouvrir. Rien à configurer : renouveler le secret de l’agent renouvelle aussi sa clé.

Il faut un agent en version 1.1.0 ou plus récente (image okstatus-agent 1.1.0, chart Helm private-agent 0.6.0). Un agent plus ancien ne peut pas lire ces identifiants : mettez-le à jour, sinon ses monitors qui portent des identifiants ne sont pas exécutés et le bouton Tester indique que l’agent n’a pas encore de clé de chiffrement.

Résilience

• Le mode sans état (credentials) ne nécessite aucun volume persistant — le pod charge son identité depuis le Secret à chaque démarrage et ne se ré-enrôle jamais.
• Le mode jeton nécessite persistence.enabled (un PVC) pour que le credential enrôlé survive aux redémarrages ; sans lui, un redémarrage nécessite un jeton renouvelé.

Dépannage

Symptôme	Cause / solution
enrollment token rejected — already used or revoked	Le jeton à usage unique a déjà été consommé (ou vous êtes en mode jeton sans PVC, donc il se ré-enrôle à chaque démarrage). Renouvelez le jeton et mettez à jour, ou passez aux credentials sans état.
CrashLoopBackOff juste après le déploiement	Presque toujours le jeton ci-dessus, ou des clés de Secret mal nommées (doivent être agentId / agentSecret).
409 / « another instance is already running »	Deux pods partagent un credential. Gardez replicas: 1 ; déployez un agent séparé pour plus de capacité.
L’agent n’apparaît jamais sur le dashboard	Vérifiez l’egress HTTPS sortant vers backend.okstatus.eu, et kubectl logs sur le pod.
401 INVALID_AGENT_ID, ou l’agent quitte au démarrage en se plaignant de l’id	OKSTATUS_AGENT_ID contient le nom de l’agent — il faut son UUID (menu de l’agent → Credentials stateless).
401 UNAUTHORIZED en mode stateless, ou l’agent quitte en se plaignant du secret	OKSTATUS_AGENT_SECRET contient le jeton d’enrôlement oksa_live_… — il faut le secret oksas_…. Générez-en un depuis le menu de l’agent.