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

Installez le chart Helm. 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.

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.

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.