Déployer et exécuter l'agent

L'agent est un exécutable unique et autonome. Il n'a ni installeur, ni dépendance d'exécution, ni base de données propre, et il lit toute sa configuration dans les variables d'environnement plus l'instantané de configuration qu'il récupère depuis ConnXL. Tout ce qui suit suppose que vous avez déjà créé un complément et un environnement dans le tableau de bord — l'onglet Déploiement de la page Agent est l'endroit où vous téléchargez un binaire déjà gravé avec son identité.

Télécharger et vérifier le binaire

Déploiement → Télécharger l'agent configuré vous donne un binaire avec son URL de backend, son ID de complément, son ID d'environnement et un jeton d'enrôlement neuf déjà intégrés, de sorte qu'il s'exécute avec zéro variable d'environnement. Plateformes : Windows x64, Linux x64, Linux arm64.

Chaque téléchargement est publié avec un fichier SHA256SUMS. Vérifiez-le avant de l'exécuter :

# Linux / macOS
sha256sum -c SHA256SUMS --ignore-missing

# Windows PowerShell
(Get-FileHash .\connxl-agent.exe -Algorithm SHA256).Hash -eq (Get-Content .\SHA256SUMS | Select-String 'connxl-agent.exe').ToString().Split()[0]

Confirmez à tout moment ce dont vous disposez :

connxl-agent --version     # affiche la version de build
connxl-agent --licenses    # affiche les mentions tierces

L'exécuter comme un service

L'agent s'exécute au premier plan et écrit ses logs sur stdout, n'importe quel gestionnaire de services convient donc. Donnez-lui un utilisateur dédié et un répertoire de travail stable — c'est là qu'il écrit l'identité qu'il enrôle.

Linux (systemd)

[Unit]
Description=ConnXL Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=connxl
WorkingDirectory=/opt/connxl
ExecStart=/opt/connxl/connxl-agent
Restart=always
RestartSec=5
Environment=CONNXL_DATA_DIR=/var/lib/connxl
# TimeoutStopSec doit dépasser le drainage de 10 s des requêtes en vol de l'agent.
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now connxl-agent
sudo systemctl status connxl-agent

Windows (service)

Le binaire est une simple application console, enregistrez-le donc avec sc.exe ou un wrapper de service tel que NSSM :

# Avec NSSM (gère la redirection de stdout et les redémarrages)
nssm install ConnXLAgent "C:\Program Files\ConnXL\connxl-agent.exe"
nssm set ConnXLAgent AppDirectory "C:\Program Files\ConnXL"
nssm set ConnXLAgent AppEnvironmentExtra "CONNXL_DATA_DIR=C:\ProgramData\ConnXL"
nssm set ConnXLAgent AppStdout "C:\ProgramData\ConnXL\logs\stdout.log"
nssm start ConnXLAgent

L'exécuter dans un conteneur

Il n'y a pas d'image publiée — construisez-en une minimale autour du binaire Linux. L'agent a besoin des certificats CA pour le TLS sortant et d'un volume persistant pour son identité, sans quoi il se réenrôle à chaque redémarrage.

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY connxl-agent /usr/local/bin/connxl-agent
ENV CONNXL_DATA_DIR=/var/lib/connxl
VOLUME /var/lib/connxl
EXPOSE 3000
ENTRYPOINT ["/usr/local/bin/connxl-agent"]

Kubernetes. Exécutez-le comme un Deployment derrière un Service, avec le jeton d'enrôlement issu d'un Secret. Utilisez uniquement une sonde de liveness — voir l'avertissement sur l'endpoint de santé à la section 6.

spec:
containers:
  - name: connxl-agent
    image: your-registry/connxl-agent:0.1.0
    ports:
      - containerPort: 3000
    env:
      - name: CONNXL_BACKEND_URL
        value: https://api.connxl.com
      - name: CONNXL_ADDIN_ID
        value: "<add-in id>"
      - name: CONNXL_ENV_ID
        value: "<environment id>"
      - name: CONNXL_ENROLL_TOKEN
        valueFrom:
          secretKeyRef: { name: connxl-agent, key: enrollToken }
    livenessProbe:
      httpGet: { path: /healthz, port: 3000 }
      initialDelaySeconds: 10
      periodSeconds: 30
    terminationGracePeriodSeconds: 30

Variables d'environnement

Un binaire gravé n'a besoin d'aucune de ces variables ; chacune remplace tout de même sa valeur gravée. Seul le groupe identité est requis sur un binaire non configuré.

Identité et backend

Listener et TLS

Stockage et fichiers d'identité

Logging

Secrets

Prérequis réseau

Chaque connexion vers ConnXL est initiée par l'agent en sortant. Rien n'a besoin d'atteindre l'agent depuis internet, et aucune règle de pare-feu entrante n'est requise pour ConnXL lui-même.

Sortant — autorisez vers l'hôte de votre API ConnXL sur TCP 443 :

Deux d'entre elles — le flux SSE de configuration et le canal de contrôle WebSocket — sont des connexions de longue durée. Les middleboxes qui tuent les connexions inactives provoqueront des reconnexions répétées ; l'agent s'en remet, mais le tableau de bord clignotera.

Entrant : vos utilisateurs Excel (et votre répartiteur de charge) doivent atteindre l'agent sur CONNXL_LISTEN_ADDR, port 3000 par défaut.

Autorisez aussi : vos propres sources de données et — uniquement si vous utilisez l'enrôlement par identité cloud — l'endpoint de métadonnées d'instance (169.254.169.254).

Contrôles de santé et surveillance

L'agent sert GET /healthz sur son adresse d'écoute. Il renvoie 200 ok dès lors que le processus tourne.

Pour une véritable santé, utilisez le tableau de bord : la page Agent de l'environnement affiche le CPU, la mémoire et le disque de chaque réplique avec une chronologie sur 24 heures, le dernier heartbeat et la version de configuration réellement appliquée. Le backend signale un agent hors ligne après environ 90 secondes sans heartbeat, et les alertes peuvent vous prévenir — voir Alertes.

Mettre à jour vers une nouvelle version

L'agent ne se met jamais à jour tout seul. Lorsqu'une réplique rapporte une version plus ancienne que la dernière publiée, le tableau de bord la signale et peut lever une notification Mise à jour disponible, mais rien n'est téléchargé ni remplacé sans vous. Une mise à jour consiste à : mettre le nouveau binaire en place et redémarrer.

Comme il n'y a pas de poignée de main de désenregistrement avec votre répartiteur de charge, sortez vous-même l'instance de la rotation en premier — /healthz continuera de renvoyer 200 jusque pendant un arrêt, il ne peut donc pas signaler le drainage à votre place.

1. Retirez la réplique du répartiteur de charge.
2. Envoyez drain depuis la page Agent. Cela démonte les abonnés en streaming afin qu'ils se reconnectent ailleurs ; cela n'arrête ni le listener ni le processus.
3. Arrêtez le service (SIGTERM, ou systemctl stop). Les requêtes en vol disposent de 10 secondes maximum pour finir, prévoyez donc au moins 30 secondes de timeout d'arrêt.
4. Remplacez le binaire et redémarrez le service.
5. Confirmez la nouvelle version sur la page Agent, puis remettez la réplique en rotation.

Avec plus d'une réplique, faites-le une à la fois et l'environnement reste disponible du début à la fin.

Ce que l'agent stocke sur le disque

Les résultats de fonctions mis en cache sont conservés en mémoire, ou dans Valkey/Redis lorsque l'environnement configure un cache externe — jamais sur le disque.

Vous n'avez besoin de sauvegarder rien de tout cela. Si le répertoire de données est perdu, l'agent se réenrôle automatiquement au démarrage suivant et poursuit, tant que son jeton d'enrôlement (ou son attestation cloud, ou son identité gravée) est toujours dans son environnement. Le seul coût est un nouveau certificat et un historique de logs remis à zéro. Vous n'avez besoin d'un nouveau jeton que si un administrateur a cliqué sur Régénérer entre-temps.

Dimensionnement et mise à l'échelle

L'agent est un proxy léger : il ne détient aucun jeu de données, et son travail est dominé par l'attente de vos sources de données. Une petite instance — 1 vCPU et 512 Mo de mémoire — fait tourner confortablement un environnement typique, et l'usage disque se limite à une semaine de logs.

Mettez à l'échelle horizontalement, pas verticalement. Ajoutez des répliques derrière un répartiteur de charge quand vous avez besoin de débit ou de redondance :

• Toutes les répliques d'un environnement partagent un seul jeton d'enrôlement et apparaissent individuellement sur la page Agent.
• Aucune affinité de session n'est requise — l'agent ne conserve aucun état par utilisateur entre les requêtes.
• Dimensionnez d'abord pour la concurrence au niveau de vos sources de données ; les valeurs par défaut du pool SQL (20 connexions ouvertes par moteur, par réplique) se multiplient par le nombre de répliques.

Retirer un agent

Pour mettre un hôte hors service proprement :

1. Sortez-le de la rotation et confirmez que le trafic est passé sur une autre réplique.
2. Arrêtez le service et désactivez son démarrage automatique.
3. Évincez la réplique depuis la page Agent de l'environnement. Cela la met en liste de blocage afin qu'elle ne puisse pas se reconnecter même si le processus revient — le moyen fiable de couper un hôte que vous ne contrôlez plus.
4. Supprimez le répertoire de données pour détruire la clé privée sur le disque.
5. Si vous retirez tous les agents de cet environnement, cliquez sur Régénérer dans l'onglet Déploiement pour que les anciens jetons d'enrôlement cessent de fonctionner.