Edge Gateway

L'edge gateway è un container Docker che gira dentro la rete del tuo impianto e fa il polling dei PLC localmente. Invece che Rela AI apra connessioni TCP in ingresso al PLC, il gateway prende i dati e li spinge in uscita via HTTPS verso il worker Cloud Run.

A cosa serve

Per impianti con firewall rigido dove non puoi aprire porte in ingresso, nemmeno via VPN. Il gateway richiede solo HTTPS in uscita verso il dominio Rela AI — una regola che il 95% dei firewall industriali già permette senza negoziazione con IT. Aggiunge anche buffering locale: se internet cade, gli eventi si accumulano sul disco del gateway e si drenano al ritorno della connessione.

Come funziona

1. Installi il container su una macchina con Docker dentro la rete dell'impianto (Raspberry Pi, mini-PC, NUC).
2. All'avvio, il container si registra col nostro backend presentando un token univoco per gateway.
3. Riceve la configurazione (quali fonti deve polling) via HTTPS.
4. Apre connessioni Modbus / OPC UA / S7 localmente al PLC.
5. Ogni lettura → evento → buffer SQLite → push HTTP al webhook dell'agente.
6. Se la rete cade, il buffer tiene fino a 100k eventi; al recupero, li drena FIFO.
7. Manda heartbeat ogni 60 secondi; se il backend non li vede per >1h, scatta allarme GATEWAY_OFFLINE.

Benefici

Installazione — passo per passo

1. Registrare il gateway nel dashboard

Dashboard → Connessioni → Edge Gateways → Registra Gateway.

Restituisce un gateway_id (es. gw_a1b2c3) e uno shared_secret che il container usa per autenticarsi. Salvalo — mostrato una sola volta.

2. Preparare l'host

Requisiti minimi:

• Linux x86_64 o ARM64 (Raspberry Pi 4+ va bene).
• Docker 20+ installato.
• 1 GB RAM, 10 GB disco.
• Connettività alla rete del PLC (stessa subnet o con rotta).
• Uscita a internet (HTTPS 443) verso rela-ai-worker-*.run.app.

3. Avviare il container

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. Verificare che il gateway sia online

Nel dashboard, entro ~60 secondi dovresti vedere il gateway in verde con last_heartbeat recente.

Log locali:

docker logs -f rela-ai-edge

Dovresti vedere:

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

5. Assegnare fonti al gateway

Nel dashboard, modifica le fonti che vuoi far girare da questo gateway:

• Deployment Mode: edge
• Edge Gateway ID: gw_a1b2c3

Al prossimo heartbeat (≤60s), il gateway scarica la config aggiornata e inizia a fare polling.

Fleet monitoring

Dashboard → Connessioni → Edge Gateways mostra tutti i gateway del tenant con:

Allarmi automatici

Un job Cloud Scheduler gira ogni ora e controlla tutti i gateway. Se trova uno con last_heartbeat > 60min, scatta un allarme canonico GATEWAY_OFFLINE con severità warning nell'inbox. Gli operatori lo vedono come qualsiasi altro allarme di asset.

La dedup dell'inbox consolida outage dello stesso gateway in una singola riga fino al ritorno dell'heartbeat (no spam durante un blackout lungo).

Aggiornamento del firmware

Dashboard → Edge Gateways → <gateway> → Aggiorna firmware. Scegli la versione target. Al prossimo heartbeat il gateway riceve il comando e:

1. Scarica la nuova immagine Docker.
2. Fa docker stop del container vecchio.
3. Avvia il nuovo.
4. Riporta successo o fallimento al prossimo heartbeat.

Se l'update fallisce (immagine corrotta, spazio insufficiente), il gateway resta sulla versione precedente e vediamo l'errore nel dashboard.

Troubleshooting

Il gateway non appare online dopo 2 minuti

Check 1 — log del container:

docker logs rela-ai-edge | tail -50

Messaggi tipici e loro cause:

Check 2 — connettività in uscita:

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

Dovrebbe restituire 200 OK con JSON {"status":"ok"}.

Il gateway è online ma non legge il PLC

• Verifica che gateway e PLC siano nella stessa rete (ping dal gateway al PLC dovrebbe funzionare).
• Rivedi i log del container per errori Modbus/OPC UA specifici (stesso troubleshooting di fonti Modbus o fonti OPC UA).
• Nel dashboard, ogni fonte ha un widget "Ultima lettura" — se è da tempo a 0, i log del container ti dicono perché.

Queue depth che sale senza fermarsi

Significa che il gateway legge più veloce di quanto possa pushare al backend. Cause comuni:

1. Internet lento: vedi latenza HTTPS nei log. >2s di solito indica problema.
2. Backend giù: ultimo POST restituì 5xx. Controlla dashboard.
3. Troppe fonti: ridistribuisci tra gateway.

La queue ha tetto di 100k eventi. Al raggiungimento, inizia a scartare i più vecchi con warning. Se lo vedi, è ora di aggiungere un altro gateway o fare debug del collo di bottiglia.

Queue depth a 0 e nessun evento che arriva al dashboard

Il gateway è connesso e pushando OK, ma il pipeline backend non li sta processando. Cause:

• La fonte che dovrebbe emettere ha enabled: false.
• Il machine agent assegnato a quella fonte ha min_severity troppo alto.
• Una regola di correlazione sta sopprimendo (vedi docs Event Rules).

Considerazioni di sicurezza

• Lo shared_secret è equivalente a una chiave API — trattalo come qualsiasi segreto.
• Il gateway ruota il suo auth token automaticamente ogni 24 ore usando il secret.
• Ogni gateway può leggere solo le fonti assegnate al suo gateway_id. Non può impersonare altri gateway dello stesso tenant.
• Tutto il traffico in uscita è cifrato TLS 1.3.
• Niente connessione in ingresso al gateway da internet — è un client, non un server.

Come testare che il gateway funziona end-to-end

Checklist operativo:

1. Dashboard → Edge Gateways → gw_xxx: stato online, last_heartbeat inferiore a 1min.
2. CPU / Mem ragionevoli (sotto il 20% CPU, sotto 500MB RAM in idle).
3. Queue depth basso o 0.
4. Una fonte con deployment_mode=edge e edge_gateway_id=gw_xxx deve essere connected e leggere.
5. Eventi che arrivano all'inbox con source_system=edge_gateway nei metadata.
6. Nessun allarme GATEWAY_OFFLINE del gateway stesso nell'inbox.