Implementare un host di connettori on-premise

Scopri i passaggi tecnici per l’implementazione, la configurazione e la manutenzione degli OPCH (On-Premise Connector Host) per le tue integrazioni Tulip.

Questo articolo è una guida di riferimento tecnico destinata ai responsabili dell’implementazione fisica e della gestione del ciclo di vita degli OPCH. Il Connector Host è un servizio utilizzato per facilitare le connessioni da

servizi web esterni, database e server OPC UA. Tutte le istanze di Tulip dispongono di un Cloud Connector Host per impostazione predefinita.

Ci sono diverse considerazioni da fare per determinare se un host connettore on-premise sia la soluzione architettonica più adatta.

Prerequisiti

Prima di continuare, assicurati di aver appreso le nozioni di base sui Connector Host di Tulip:* Connector Host* Connector Host on-premise

Rete

Il motivo più comune per implementare un Connector Host on-premise è rappresentato dai vantaggi che offre quando ci si connette a sistemi ospitati all’interno di una rete locale. Con l’offerta on-premise, tutte le connessioni da Tulip ai sistemi esterni partono dall’interno della rete locale. Tutte le connessioni dalla rete locale sono in uscita verso Tulip tramite un WebSocket sicuro.

Ciò è in contrasto con gli host di connessione cloud, che richiedono l’accesso in entrata ai servizi. Si tratta in genere di una decisione del reparto IT volta a consentire connessioni WebSocket sicure in entrata dal cloud di Tulip al servizio, spesso utilizzando regole di inoltro delle porte sul router/firewall WAN.

Implementare un host connettore on-premise

Standard tecnici

Quando si decide di implementare una soluzione on-premise, Tulip raccomanda un approccio self-service che utilizza un’immagine Docker distribuita. Il modo più semplice per farlo è utilizzare una macchina virtuale con una distribuzione Linux.

Tulip raccomanda inoltre di ospitare un solo host del connettore on-premise per macchina virtuale, al fine di evitare un singolo punto di guasto per i siti.

Requisiti della macchina virtuale:

• RAM - 4 GB
• Spazio su disco: 8-16 GB
• CPU: 2 core
• Versione Docker: 20.10 o superiore

Per quanto riguarda i requisiti di rete, l'host del connettore on-premise presenta le seguenti caratteristiche:

• Un indirizzo IP
• Risoluzione DNS verso
• Accesso in uscita sulla porta 443 a Tulip (indirizzi IP elencati qui)
• Accesso in uscita al repository Docker qui
• Accesso in uscita a tutti i sistemi esterni rilevanti tramite le porte

Consulta l'elenco completo dei requisiti di rete qui

Implementazione

La sezione seguente illustra come implementare un host del connettore on-premise in diversi ambienti. Sia AWS che Azure offrono servizi di container in grado di eseguire l’immagine Docker.

AWS

Utilizza l’interfaccia utente web e questa guida: https://aws.amazon.com/getting-started/hands-on/deploy-docker-containers/

Azure (Bash): LTS16+ OPCH

az container create `-g <NOME DEL GRUPPO DI RISORSE IN AZURE> `--name <NOME DEL CONTENITORE> `--cpu 2 `--memory 3 `--restart-policy Always `--public.ecr.aws/tulip/connector-host:<TAG>--os-type Linux `-e TULIP_UUID='<UUID>' `TULIP_FACTORY='https://<IL TUO SITO>.tulip.co' `TULIP_MACHINE_SECRET='<SEGRETO>' `TULIP_DEVICE_TYPE='onprem' `TULIP_LOGGING_TO_TULIP=true`TULIP_TELEMETRY_TO_TULIP=true`TULIP_CONNECTORS_HTTP_PROXY='' `TULIP_CONNECTORS_HTTPS_PROXY=''

Azure (Bash): OPCH pre-LTS16

az container create `-g <NOME DEL GRUPPO DI RISORSE IN AZURE> `--name <NOME DEL CONTENITORE> `--cpu 2 `--memory 3 `--restart-policy Always `--public.ecr.aws/tulip/connector-host:<TAG> `--os-type Linux `-e TULIP_UUID='<UUID>' `TULIP_FACTORY='https://<IL TUO SITO>.tulip.co' `TULIP_MACHINE_SECRET='<SEGRETO>' `TULIP_DEVICE_TYPE='onprem' `CONNECTORS_HTTP_PROXY='' `CONNECTORS_HTTPS_PROXY=''

VM Linux: LTS16+ OPCH

docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://<FACTORY>.tulip.co' \ -e TULIP_UUID='<UUID>' \ -e TULIP_MACHINE_SECRET='<SECRET>' \ -e TULIP_DEVICE_TYPE='onprem' \ -e TULIP_LOGGING_TO_TULIP=true \ -e TULIP_TELEMETRY_TO_TULIP=true \ -e TULIP_CONNECTORS_HTTP_PROXY='' \ -e TULIP_CONNECTORS_HTTPS_PROXY='' \ --restart=always \ --net=host \ public.ecr.aws/tulip/connector-host:<TAG>

VM Linux: OPCH precedente alla versione LTS16

 --name tulip-connector-host \  
 -e TULIP\_FACTORY='https://.tulip.co' \  
 -e TULIP\_UUID='' \  
 -e TULIP\_MACHINE\_SECRET='' \  
 -e TULIP\_DEVICE\_TYPE='onprem' \  
 -e CONNECTORS\_HTTP\_PROXY='' \  
 -e CONNECTORS\_HTTPS\_PROXY='' \  
 -e EXIT\_ON\_DISCONNECT=true \ --restart=always \  
 --net=host \  
 --mount type=volume,source=tuliplog,target=/log \  
 public.ecr.aws/tulip/connector-host:

Windows (PowerShell): LTS16+ OPCH

docker run -d --name tulip-connector-host -e TULIP_FACTORY='https://<FACTORY>.tulip.co' -e TULIP_UUID='<UUID>' -e TULIP_MACHINE_SECRET='<SECRET>' -e TULIP_DEVICE_TYPE='onprem' -e TULIP_LOGGING_TO_TULIP=true -e TULIP_TELEMETRY_TO_TULIP=true -e TULIP_CONNECTORS_HTTP_PROXY='' -e TULIP_CONNECTORS_HTTPS_PROXY='' --restart=always --net=host public.ecr.aws/tulip/connector-host:<TAG>

Windows (PowerShell): OPCH pre-LTS16

docker run -d --name tulip-connector-host -e TULIP_FACTORY='https://<FACTORY>.tulip.co' -e TULIP_UUID='<UUID>' -e TULIP_MACHINE_SECRET='<SECRET>' -e TULIP_DEVICE_TYPE='onprem' -e HTTP_PROXY='' -e HTTPS_PROXY='' -e EXIT_ON_DISCONNECT=true --restart=always --net=host --mount type=volume,source=tuliplog,target=/log public.ecr.aws/tulip/connector-host:<TAG>

Risoluzione degli errori relativi ai certificati

Se OPCH non si avvia a causa di errori relativi a "certificato autofirmato nella catena di certificati", la causa principale potrebbe essere che il proxy/firewall aziendale con certificati personalizzati impedisce le connessioni sicure a Tulip Cloud.

Sintomi: - OPCH mostra lo stato "Never seen" - Il processo si interrompe durante l’avvio - Errori relativi alla catena di certificati SSL nei log

Per risolvere il problema, è possibile specificare autorità di certificazione aggiuntive a cui fare riferimento durante l’avvio di OPCH utilizzando la seguente variabile d’ambiente, come indicato di seguito. Si noti che il file deve essere presente nel container Docker.

Per OPCH precedenti alla versione LTS16: -e CONNECTORS_EXTRA_TRUSTED_CAS_FROM_FILES='["/etc/tulipCa/ca.pem"]'

Per OPCH LTS16 e versioni successive: -e TULIP_CONNECTORS_EXTRA_TRUSTED_CAS_FROM_FILES='["/etc/tulipCa/ca.pem"]'

Aggiornamento di un host del connettore on-premise

:::(Avviso) (Potrebbe essere necessario aggiornare anche il dispositivo Edge IO)
OPCH può essere eseguito su dispositivi Edge IO. Se sul dispositivo non è abilitato l’aggiornamento automatico, è necessario eseguire l’aggiornamento manualmente.

Se questo banner di avviso continua a comparire dopo aver completato tutti gli aggiornamenti di OPCH, assicurati che anche il tuo Edge IO sia stato aggiornato.
:::

Tulip rilascia aggiornamenti per l’On-Premise Connector Host in conformità con il nostro programma di rilascio del supporto a lungo termine (LTS). Per aggiornare il servizio, segui le istruzioni riportate di seguito:

Il processo di aggiornamento di un OPCH comporterà un periodo di inattività durante il quale il pod verrà arrestato e ricreato.

1. Procurarsi l’ultima versione dell’immagine Docker di On-Premise Connector Host.

   docker pull public.ecr.aws/tulip/connector-host:<TAG>2. Eseguire il comando riportato di seguito per ottenere l’ID del container Docker.

   docker ps3. Se si dispone dell’accesso a TULIP_FACTORY, TULIP_UUID e TULIP_MACHINE_SECRET, passare al punto 4. In caso contrario, eseguire il comando seguente e conservare l’output in un luogo sicuro.

   docker exec <ID-container> env4. Arresta il container Docker esistente.

   docker stop <ID-container>5. Rimuovere il container Docker esistente.

   docker rm <ID-container>6. Eseguire il comando standard docker run utilizzando le credenziali salvate.

Per OPCH LTS16+: docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://<FACTORY>.tulip.co' \ -e TULIP_UUID='<UUID>' \ -e TULIP_MACHINE_SECRET='<SECRET>' \ -e TULIP_DEVICE_TYPE='onprem' \ -e TULIP_LOGGING_TO_TULIP=true \ -e TULIP_TELEMETRY_TO_TULIP=true \ -e TULIP_CONNECTORS_HTTP_PROXY='' \ -e TULIP_CONNECTORS_HTTPS_PROXY='' \ --restart=always \ --net=host \ public.ecr.aws/tulip/connector-host:<TAG>Per OPCH precedenti alla versione LTS16: docker run -d \ --name tulip-connector-host \ -e TULIP_FACTORY='https://<FACTORY>.tulip.co' \ -e TULIP_UUID='<UUID>' \ -e TULIP_MACHINE_SECRET='<SECRET>' \ -e TULIP_DEVICE_TYPE='onprem' \ -e CONNECTORS_HTTP_PROXY='' \ -e CONNECTORS_HTTPS_PROXY='' \ -e EXIT_ON_DISCONNECT=true \ --restart=always \ --net=host \ --mount type=volume,source=tuliplog,target=/log \ public.ecr.aws/tulip/connector-host:<TAG>

1. Verifica che il nuovo container Docker sia attivo.

   docker ps

Utilizzare gli ambienti dei connettori per testare l’aggiornamento

Ogni connettore dispone di tre diversi ambienti (produzione, pre-produzione e sviluppo) e ciascuno di questi ambienti può avere il proprio host del connettore, che può essere di versione diversa. A seconda dello stato dell’applicazione (versione di sviluppo, in attesa di approvazione, pubblicata) è possibile utilizzare un ambiente diverso.Il processo previsto per eseguire la convalida dell’host del connettore dovrebbe essere il seguente: 1. Aggiornare l’OPCH di sviluppo 2. Aggiornare l’host del connettore di convalida (in questo caso l’ambiente di pre-produzione punta a quello di sviluppo) 1. Testare il connettore nella pagina dei connettori o in modalità di sviluppo dell’applicazione 3. Una volta completati i test di convalida, aggiornare l’host del connettore di produzione

Per ulteriori informazioni, consultare la sezione Ambienti dei connettori.

In alternativa, è possibile aggiornare l’OPCH sull’istanza di sviluppo e quindi procedere con sicurezza all’aggiornamento dell’ambiente di produzione.

Registrazione in strumenti di gestione dei log esterni

È possibile inoltrare i log dell’host del connettore on-premise a strumenti di terze parti per il monitoraggio centralizzato e la risoluzione dei problemi. L’OPCH supporta Datadog, Grafana Loki e Splunk tramite variabili d’ambiente. I tipi di log disponibili riguardano lo stato di integrità dell’OPCH (in particolare per quanto riguarda la connessione a Factory), l’esecuzione delle chiamate al connettore e i log delle sottoscrizioni. Come parte del flusso di avvio dell’OPCH, gli utenti possono specificare la configurazione dello strumento di registrazione esterno a cui desiderano che i log vengano instradati. Se vengono aggiunte credenziali per più servizi, i log vengono inviati a tutti i servizi

1. Scegli la destinazione
2. Datadog: endpoint globale; è richiesta solo una chiave API.
3. Grafana Loki: Loki ospitato dal cliente; l’URL può includere l’autenticazione di base.
4. Splunk (HEC): multi-istanza; richiede sia l’URL che il token.
5. Aggiungi le variabili d’ambiente: aggiungi le variabili riportate di seguito all’ambiente dell’host del connettore. Utilizza solo quelle relative alla destinazione scelta.

Datadog

• TULIP_LOGGING_DATADOG_API_KEY=<la_tua_chiave_API_Datadog>

Grafana Loki

• TULIP_LOGGING_LOKI_URL=https://<user>:<password>@loki.your-domain.com/loki/api/v1/push
  (L’autenticazione di base è supportata inserendo user:password nell’URL — opzionale.)

Splunk (HEC)

• TULIP_LOGGING_SPLUNK_URL=https://splunk.your-domain.com:8088/services/collector
• TULIP_LOGGING_SPLUNK_TOKEN=<il_tuo_token_splunk_hec>

1. Riavvia l'host del connettore

Riavviare il servizio affinché le nuove variabili d’ambiente abbiano effetto.

1. Verifica la consegna

Generare attività (ad es., eseguire una funzione del connettore) e verificare che i log compaiano nella destinazione:

• Datadog: controllare i log recenti alla ricerca del nome dell'host o del servizio.
• Loki: eseguire una query in Grafana Explore in base all'etichetta dell'host o a una sottostringa nota del messaggio.
• Splunk: cerca gli eventi recenti provenienti dal tuo host (ad es., index=<your_index> source="tulip-connector-host").
• Modifica o disattiva la registrazione
• Per cambiare destinazione, aggiorna le variabili con quelle del nuovo provider (e rimuovi quelle precedenti).
• Per disabilitare la registrazione, rimuovi le variabili di registrazione e riavvia il servizio.

Ulteriori informazioni

Implementazione basata sugli esportatori Grafana Alloy:

Esportatore Datadog:https://grafana.com/docs/alloy/next/reference/components/otelcol/otelcol.exporter.datadog/

Esportatore Splunk HEC: https://grafana.com/docs/alloy/next/reference/components/otelcol/otelcol.exporter.splunkhec/

Carico delle chiamate in entrata e in uscita

Questa sezione spiega quante richieste HTTP l'OPCH invia a Tulip Cloud. Queste richieste possono essere raggruppate in richieste a frequenza fissa (sempre in esecuzione) e richieste a frequenza variabile (a seconda della configurazione e dell'attività).

Richieste a frequenza fissa

Queste richieste avvengono a una frequenza costante e prevedibile:

Richieste a frequenza variabile

Queste richieste dipendono dalla configurazione e dall'attività.
Maggiori sono le modifiche o gli eventi che si verificano, maggiore è la frequenza delle richieste.

Esempio di calcolo

Si consideri una configurazione con: - 1 fonte di dati macchina - 500 attributi macchina, ciascuno dei quali invia dati a 1 Hz (una volta al secondo)

Frequenza delle richieste nel caso peggiore:`Frequenza (caso peggiore) = (6 + 1 + 20) + 40 + 60 + 240 = 367 richieste al minuto

Riferimenti aggiuntivi

Abilitare la rotazione dei log per Docker

Per le istanze On-Premise di Connector Hosts esistenti che non utilizzano la rotazione dei log di Docker, seguire le istruzioni documentate qui per garantire che lo spazio su disco sia gestito correttamente.

Verifica lo stato di salute dell’OPCH

Per integrare l’OPCH con il proprio orchestratore di servizi basato su Azure o Kubernetes, è possibile utilizzare la seguente configurazione:

Per OPCH LTS16+:

Per integrare l'OPCH con il proprio orchestratore di servizi basato su Azure o Kubernetes, è possibile utilizzare la seguente configurazione: L'endpoint di controllo dello stato viene assegnato in modo casuale su una porta ed esposto al percorso radice /health-check. Facoltativamente, la porta assegnata può essere sovrascritta impostando TULIP_HEALTH_HTTP_PORT sulla porta specificata. Ad esempio: TULIP_HEALTH_HTTP_PORT = 80. Una risposta positiva restituirà un codice di stato HTTP pari a 204, indicando che il servizio OPCH è integro e operativo.

Per OPCH precedenti alla versione LTS16:

Per integrare OPCH con il proprio orchestratore di servizi basato su Azure o Kubernetes, è possibile utilizzare la seguente configurazione: l’endpoint di controllo dello stato di integrità deve essere abilitato impostando la variabile d’ambiente CONNECTORS_HEALTHZ_SERVER_ENABLED su true.L'endpoint è disponibile sulla porta 9223 ed è esposto al percorso radice /. Facoltativamente, la porta predefinita 9223 può essere sovrascritta impostando CONNECTORS_PORT sul valore della porta specificata. Ad esempio: CONNECTORS_PORT = 80

Una risposta positiva restituirà un codice di stato HTTP 200 (OK), a indicare che il servizio OPCH è integro e operativo.
Facoltativamente, la porta predefinita 9223 può essere sovrascritta impostando CONNECTORS_PORT sul valore della porta specificata. Ad esempio: CONNECTORS_PORT = 80

Una risposta positiva restituirà un codice di stato HTTP 200 (OK), a indicare che il servizio OPCH è integro e operativo.

{{snippet.Hai trovato quello che cercavi?}}