Edge Gateway

El edge gateway es un contenedor Docker que corre dentro de la red de tu planta y hace el polling de los PLCs localmente. En vez de que Rela AI abra conexiones TCP entrantes al PLC, el gateway toma los datos y los empuja por HTTPS saliente hacia el worker de Cloud Run.

¿Para qué sirve?

Para plantas con firewall estricto donde no podés abrir puertos entrantes, ni siquiera por VPN. El gateway requiere sólo HTTPS saliente al dominio de Rela AI — una regla que el 95% de los firewalls industriales ya permite sin negociación con IT. También añade buffering local: si internet se cae, los eventos se acumulan en el disco del gateway y se drenan cuando la conexión vuelve.

¿Cómo funciona?

1. Instalás el contenedor en un equipo con Docker dentro de la red de la planta (Raspberry Pi, mini-PC industrial, NUC).
2. Al arrancar, el contenedor se registra con nuestro backend presentando un token único por gateway.
3. Recibe la configuración (qué fuentes tiene que pollear) vía HTTPS.
4. Abre conexiones Modbus / OPC UA / S7 localmente al PLC.
5. Cada lectura → evento → buffer SQLite → push HTTP al webhook del agente.
6. Si la red se cae, el buffer retiene hasta 100k eventos; al recuperarse, los drena en orden FIFO.
7. Emite heartbeats cada 60 segundos; si el backend no los ve durante >1h, dispara alarma GATEWAY_OFFLINE.

Beneficios

Instalación — paso a paso

1. Registrar el gateway en el dashboard

Dashboard → Conexiones → Edge Gateways → Registrar Gateway.

Te devuelve un gateway_id (ej. gw_a1b2c3) y un shared_secret que el contenedor usa para autenticarse. Guardalo — se muestra una sola vez.

2. Preparar el host

Requisitos mínimos:

• Linux x86_64 o ARM64 (Raspberry Pi 4+ funciona).
• Docker 20+ instalado.
• 1 GB RAM, 10 GB disco.
• Conectividad a la red del PLC (mismo subnet o con ruta).
• Salida a internet (HTTPS 443) al dominio rela-ai-worker-*.run.app.

3. Arrancar el contenedor

docker run -d \
  --name rela-ai-edge \
  --restart unless-stopped \
  -v rela-edge-data:/var/lib/rela-edge \
  -e GATEWAY_ID=gw_a1b2c3 \
  -e GATEWAY_SECRET=<shared_secret> \
  -e BACKEND_URL=https://rela-ai-worker-687568754456.europe-west1.run.app \
  gcr.io/rela-ai-488016/rela-ai-edge:latest

O con docker compose:

services:
  rela-ai-edge:
    image: gcr.io/rela-ai-488016/rela-ai-edge:latest
    restart: unless-stopped
    volumes:
      - rela-edge-data:/var/lib/rela-edge
    environment:
      GATEWAY_ID: gw_a1b2c3
      GATEWAY_SECRET: <shared_secret>
      BACKEND_URL: https://rela-ai-worker-687568754456.europe-west1.run.app

volumes:
  rela-edge-data:

4. Verificar que el gateway está online

En el dashboard, a los ~60 segundos deberías ver el gateway en verde con last_heartbeat reciente.

Logs locales:

docker logs -f rela-ai-edge

Deberías ver:

edge_started gateway_id=gw_a1b2c3
heartbeat_sent seq=1 latency_ms=142
config_fetched sources=0

5. Asignar fuentes al gateway

En el dashboard, edita las fuentes que querés que corran desde este gateway:

• Deployment Mode: edge
• Edge Gateway ID: gw_a1b2c3

En el próximo heartbeat (≤60s), el gateway descarga la config actualizada y empieza a pollear.

Fleet monitoring

Dashboard → Conexiones → Edge Gateways muestra todos los gateways del tenant con:

Alertas automáticas

Un Cloud Scheduler job corre cada hora y revisa todos los gateways. Si encuentra uno con last_heartbeat > 60min, dispara una alerta canónica GATEWAY_OFFLINE con severidad warning en el inbox. Los operadores la ven como cualquier otra alerta de activo.

La dedup del inbox consolida outages del mismo gateway en una sola fila hasta que vuelve a heartbeatear (no genera spam durante una caída larga).

Actualización de firmware

Dashboard → Edge Gateways → <gateway> → Actualizar firmware. Elegís la versión target. En el próximo heartbeat el gateway recibe la orden y:

1. Descarga la nueva imagen Docker.
2. Hace un docker stop del contenedor viejo.
3. Arranca el nuevo.
4. Reporta éxito o falla en el siguiente heartbeat.

Si la actualización falla (imagen corrupta, espacio insuficiente), el gateway queda en la versión anterior y vemos el error en el dashboard.

Troubleshooting

El gateway no aparece online después de 2 minutos

Check 1 — logs del contenedor:

docker logs rela-ai-edge | tail -50

Mensajes típicos y sus causas:

Check 2 — conectividad saliente:

curl -v https://rela-ai-worker-687568754456.europe-west1.run.app/internal/health

Debería devolver 200 OK con JSON {"status":"ok"}.

El gateway está online pero no lee del PLC

• Verificá que el gateway y el PLC están en la misma red (ping desde el gateway al PLC debería funcionar).
• Revisá los logs del contenedor por errores Modbus/OPC UA específicos (mismo troubleshooting que fuentes Modbus o fuentes OPC UA).
• En el dashboard, cada fuente tiene un widget "Última lectura" — si lleva rato en 0, los logs del contenedor te dicen por qué.

Queue depth subiendo sin parar

Significa que el gateway está leyendo más rápido de lo que puede pushear al backend. Causas comunes:

1. Internet lento: ver latencia HTTPS en los logs. >2s suele indicar problema.
2. Backend caído: el último POST devolvió 5xx. Ver dashboard.
3. Too many sources: redistribuí entre gateways.

El queue tiene tope de 100k eventos. Al llegar, empieza a descartar los más viejos con un warning. Si ves esto, es hora de añadir otro gateway o debuguear el cuello.

Queue depth en 0 y sin eventos llegando al dashboard

El gateway está conectado y pusheando OK, pero el pipeline backend no los está procesando. Causas:

• La fuente que debería emitir tiene enabled: false.
• El machine agent asignado a esa fuente tiene min_severity demasiado alto.
• Hay una regla de correlación suprimiendo (ver docs de Event Rules).

Consideraciones de seguridad

• El shared_secret es equivalente a una llave de API — tratalo como cualquier secreto.
• El gateway rota su auth token automáticamente cada 24 horas usando el secret.
• Cada gateway sólo puede leer las fuentes asignadas a su gateway_id. No puede suplantar a otros gateways del mismo tenant.
• Todo el tráfico saliente va cifrado TLS 1.3.
• No hay conexión entrante al gateway desde internet — no es un servidor, es un cliente.

Cómo probar que el gateway funciona end-to-end

Checklist operativo:

1. Dashboard → Edge Gateways → gw_xxx: estado online, last_heartbeat menor a 1min.
2. CPU / Mem razonables (menor al 20% CPU, menos de 500MB RAM en idle).
3. Queue depth bajo o 0.
4. Una fuente con deployment_mode=edge y edge_gateway_id=gw_xxx debe estar connected y leer.
5. Eventos llegando al inbox con source_system=edge_gateway en los metadatos.
6. Sin alertas GATEWAY_OFFLINE del propio gateway en el inbox.