Despliega y ejecuta el agent

El agent es un único ejecutable autocontenido. No tiene instalador, ni dependencias de ejecución, ni base de datos propia, y lee toda su configuración de las variables de entorno más la instantánea de configuración que extrae de ConnXL. Todo lo que sigue asume que ya creaste un complemento y un entorno en el panel — la pestaña Despliegue de la página del Agente es donde descargas un binario que ya viene grabado con su identidad.

Descarga y verifica el binario

Despliegue → Descargar agent configurado te da un binario con su URL del backend, el ID del complemento, el ID del entorno y un token de inscripción nuevo ya incrustados, así que se ejecuta con cero variables de entorno. Plataformas: Windows x64, Linux x64, Linux arm64.

Cada descarga se publica junto a un archivo SHA256SUMS. Verifícalo antes de ejecutarlo:

# 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]

Confirma en cualquier momento lo que tienes:

connxl-agent --version     # imprime la versión de compilación
connxl-agent --licenses    # imprime los avisos de terceros

Ejecútalo como un servicio

El agent se ejecuta en primer plano y escribe sus logs en stdout, así que sirve cualquier gestor de servicios. Dale un usuario dedicado y un directorio de trabajo estable — ahí escribe la identidad que inscribe.

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 debe superar el drenaje de 10 s de peticiones en vuelo del agent.
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

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

Windows (servicio)

El binario es una aplicación de consola normal, así que regístralo con sc.exe o con un envoltorio de servicios como NSSM:

# Usando NSSM (gestiona la redirección de stdout y los reinicios)
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

Ejecútalo en un contenedor

No hay imagen publicada — construye una mínima alrededor del binario de Linux. El agent necesita certificados de CA para el TLS saliente y un volumen persistente para su identidad, o se volverá a inscribir en cada reinicio.

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. Ejecútalo como un Deployment detrás de un Service, con el token de inscripción en un Secret. Usa solo una sonda de liveness — consulta el aviso sobre el endpoint de salud en la sección 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 de entorno

Un binario grabado no necesita ninguna de estas; aun así, cada variable anula su valor grabado. Solo el grupo de identidad es obligatorio en un binario sin configurar.

Identidad y backend

Listener y TLS

Almacenamiento y archivos de identidad

Logging

Secretos

Requisitos de red

Cada conexión con ConnXL la inicia el agent hacia fuera. Nada necesita alcanzar al agent desde internet, y no hace falta ninguna regla de firewall de entrada para el propio ConnXL.

Salida — permite hacia el host de tu API de ConnXL por TCP 443:

Dos de estas — el stream SSE de configuración y el canal de control por WebSocket — son conexiones de larga duración. Los middleboxes que cortan las conexiones inactivas provocarán reconexiones repetidas; el agent se recupera, pero el panel parpadeará.

Entrada: tus usuarios de Excel (y tu balanceador de carga) deben alcanzar al agent en CONNXL_LISTEN_ADDR, puerto 3000 por defecto.

Permite también: tus propias fuentes de datos y — solo si usas inscripción con identidad en la nube — el endpoint de metadatos de la instancia (169.254.169.254).

Comprobaciones de salud y monitorización

El agent sirve GET /healthz en su dirección de escucha. Devuelve 200 ok siempre que el proceso esté en marcha.

Para salud real, usa el panel: la página del Agente del entorno muestra la CPU, la memoria y el disco de cada réplica con una línea temporal de 24 horas, el último heartbeat y la versión de configuración realmente aplicada. El backend marca un agent como desconectado tras unos 90 segundos sin heartbeat, y las alertas pueden avisarte — consulta Alertas.

Actualiza a una versión nueva

El agent nunca se actualiza solo. Cuando una réplica reporta una versión más antigua que la última publicada, el panel la señala y puede levantar una notificación de Actualización disponible, pero no se descarga ni se reemplaza nada sin ti. Una actualización consiste en: colocar el binario nuevo y reiniciar.

Como no hay un protocolo de baja con tu balanceador de carga, saca tú mismo la instancia de rotación primero — /healthz seguirá devolviendo 200 incluso durante un apagado, así que no puede señalar el drenaje por ti.

1. Quita la réplica del balanceador de carga.
2. Envía drain desde la página del Agente. Esto desmonta los suscriptores de streaming para que se reconecten en otro sitio; no detiene el listener ni termina el proceso.
3. Detén el servicio (SIGTERM, o systemctl stop). Las peticiones en vuelo disponen de hasta 10 segundos para terminar, así que deja al menos 30 segundos de timeout de parada.
4. Reemplaza el binario y arranca el servicio de nuevo.
5. Confirma la nueva versión en la página del Agente, y devuelve la réplica a rotación.

Con más de una réplica, hazlo de una en una y el entorno se mantiene en marcha durante todo el proceso.

Qué guarda el agent en disco

Los resultados de función cacheados se guardan en memoria, o en Valkey/Redis cuando el entorno configura una caché externa — nunca en disco.

No necesitas hacer copia de seguridad de nada de esto. Si se pierde el directorio de datos, el agent se vuelve a inscribir automáticamente en el siguiente arranque y continúa, siempre que su token de inscripción (o la atestación en la nube, o la identidad grabada) siga en su entorno. El único coste es un certificado nuevo y un historial de logs desde cero. Solo necesitas un token nuevo si un administrador ha pulsado Regenerar desde entonces.

Dimensionamiento y escalado

El agent es un proxy ligero: no retiene ningún conjunto de datos, y su trabajo está dominado por la espera a tus fuentes de datos. Una instancia pequeña — 1 vCPU y 512 MB de memoria — ejecuta con holgura un entorno típico, y el uso de disco se limita a una semana de logs.

Escala horizontalmente, no verticalmente. Añade réplicas detrás de un balanceador de carga cuando necesites rendimiento o redundancia:

• Todas las réplicas de un entorno comparten un único token de inscripción y aparecen individualmente en la página del Agente.
• No hace falta afinidad de sesión — el agent no guarda estado por usuario entre peticiones.
• Dimensiona primero para la concurrencia en tus fuentes de datos; los valores por defecto del pool SQL (20 conexiones abiertas por motor, por réplica) se multiplican por el número de réplicas.

Retira un agent

Para dar de baja un host de forma limpia:

1. Sácalo de rotación y confirma que el tráfico se ha movido a otra réplica.
2. Detén el servicio y desactiva su arranque automático.
3. Expulsa la réplica desde la página del Agente del entorno. Esto la pone en lista de bloqueo para que no pueda reconectarse aunque el proceso vuelva — la forma fiable de cortar un host que ya no controlas.
4. Borra el directorio de datos para destruir la clave privada en disco.
5. Si estás retirando todos los agents de ese entorno, pulsa Regenerar en la pestaña Despliegue para que los tokens de inscripción antiguos dejen de funcionar.