Configurare un dispositivo IoT Edge per comunicare tramite un server proxy

Articolo
07/17/2024

Si applica a: IoT Edge 1.5 IoT Edge 1.4

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 LTS sono versioni supportate. IoT Edge 1.4 LTS raggiungerà il fine vita il 12 novembre 2024. Se si usa una versione precedente, vedere Aggiornare IoT Edge.

I dispositivi IoT Edge inviano le richieste HTTPS per comunicare con l'hub IoT. Se il dispositivo è connesso a una rete che usa un server proxy, è necessario configurare il runtime di IoT Edge per comunicare tramite il server. I server proxy possono influire anche sui singoli moduli IoT Edge se vengono effettuate richieste HTTP o HTTPS che non vengono instradate tramite l'hub di IoT Edge.

Questo articolo illustra i quattro passaggi seguenti per configurare e quindi gestire un dispositivo IoT Edge dietro un server proxy:

Installare il runtime di IoT Edge nel dispositivo

Gli script di installazione di IoT Edge estraggono pacchetti e file da Internet, quindi il dispositivo deve comunicare tramite il server proxy per effettuare tali richieste. Per i dispositivi Windows, lo script di installazione fornisce anche un'opzione di installazione offline.

Questo passaggio è un processo una tantum per la prima configurazione del dispositivo IoT Edge. Queste stesse connessioni sono necessarie anche quando si aggiorna il runtime di IoT Edge.
Configurare IoT Edge e il runtime del contenitore nel dispositivo

IoT Edge effettua le comunicazioni con l'hub IoT. Il runtime del contenitore effettua la gestione dei contenitori, quindi comunica con i registri contenitori. Entrambi questi componenti devono effettuare richieste Web tramite il server proxy.

Questo passaggio è un processo una tantum per la prima configurazione del dispositivo IoT Edge.
Configurare le proprietà dell’agente IoT Edge nel file di configurazione nel dispositivo

Il daemon IoT Edge avvia inizialmente il modulo edgeAgent. Il modulo edgeAgent, quindi, recupera il manifesto della distribuzione dall'hub IoT e avvia tutti gli altri moduli. Configurare manualmente le variabili di ambiente del modulo edgeAgent nel dispositivo stesso, in modo che l'agente IoT Edge possa stabilire la connessione iniziale all'hub IoT. Dopo la connessione iniziale, è possibile configurare il modulo edgeAgent in modalità remota.

Questo passaggio è un processo una tantum per la prima configurazione del dispositivo IoT Edge.
Per tutte le distribuzioni future dei moduli, impostare le variabili di ambiente per tutti i moduli che comunicano tramite il proxy

Dopo aver configurato e connesso un dispositivo IoT Edge all'hub IoT tramite il server proxy, è necessario mantenere la connessione in tutte le distribuzioni future dei moduli.

Questo passaggio è un processo continuo eseguito in remoto, in modo che ogni nuovo modulo o aggiornamento della distribuzione mantenga la capacità del dispositivo di comunicare tramite il server proxy.

Conoscere l'URL proxy

Prima di iniziare uno dei passaggi descritti in questo articolo, è necessario conoscere l'URL del proxy.

Gli URL proxy hanno il formato seguente: protocollo://host_proxy:porta_proxy.

Il protocollo è HTTP o HTTPS. Il daemon Docker può utilizzare entrambi i protocolli a seconda delle impostazioni del registro contenitori, ma i contenitori di runtime e il daemon di IoT Edge devono usare sempre HTTP per collegarsi al proxy.
L'host_proxy è un indirizzo per il server proxy. Se il server proxy richiede l'autenticazione, è possibile fornire le credenziali come parte dell'host proxy con il formato seguente: utente:password@proxy_host.
La porta_proxy è la porta di rete a cui il proxy risponde al traffico di rete.

Installare IoT Edge tramite un proxy

A prescindere che il dispositivo IoT Edge venga eseguito in Windows o Linux, è necessario accedere ai pacchetti di installazione tramite il server proxy. A seconda del sistema operativo, seguire la procedura per installare il runtime di IoT Edge tramite un server proxy.

Dispositivi Linux

Se si installa il runtime IoT Edge in un dispositivo Linux, configurare la gestione di pacchetti per il passaggio attraverso il server proxy per accedere al pacchetto di installazione. Ad esempio, Configurare apt-get per usare un proxy http. Dopo aver configurato la gestione pacchetti, seguire le istruzioni riportate in Installare il runtime di Azure IoT Edge come di consueto.

Dispositivi Windows che usano IoT Edge per Linux in Windows

Se si installa il runtime di IoT Edge usando IoT Edge per Linux in Windows, IoT Edge viene installato per impostazione predefinita nella macchina virtuale Linux. Non è necessario installare o aggiornare altri passaggi.

Dispositivi Windows che usano contenitori Windows

Se si installa il runtime IoT Edge in un dispositivo Windows, è necessario passare due volte attraverso il server proxy. La prima connessione scarica il file di script del programma di installazione e la seconda connessione avviene durante l'installazione per scaricare i componenti necessari. È possibile configurare le informazioni proxy nelle impostazioni di Windows o includere le informazioni proxy direttamente nei comandi PowerShell.

La procedura seguente illustra un esempio di un'installazione di Windows usando l'argomento -proxy:

Il comando Invoke-WebRequest richiede informazioni proxy per accedere allo script del programma di installazione. Il comando Deploy-IoTEdge, quindi, richiede le informazioni proxy per scaricare i file di installazione.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
```
Il comando Initialize-IoTEdge non deve passare attraverso il server proxy, quindi il secondo passaggio richiede solo informazioni proxy per Invoke-WebRequest.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
```

Se le credenziali per il server proxy sono complesse e non è possibile includerle nell'URL, usare il parametro -ProxyCredential in -InvokeWebRequestParameters. ad esempio:

$proxyCredential = (Get-Credential).GetNetworkCredential()
. {Invoke-WebRequest -proxy <proxy URL> -ProxyCredential $proxyCredential -useb aka.ms/iotedge-win} | Invoke-Expression; `
Deploy-IoTEdge -InvokeWebRequestParameters @{ '-Proxy' = '<proxy URL>'; '-ProxyCredential' = $proxyCredential }

Per altre informazioni sui parametri del proxy, vedere Invoke-WebRequest.

Configurare IoT Edge e Moby

IoT Edge si basa su due daemon in esecuzione nel dispositivo IoT Edge. Il daemon Moby effettua richieste Web per eseguire il pull di immagini di contenitori dai registri contenitori. Il daemon IoT Edge esegue richieste Web per comunicare con l'hub IoT.

È necessario configurare i daemon Moby e IoT Edge per usare il server proxy per le funzionalità dei dispositivi in corso. Questo passaggio viene eseguito nel dispositivo IoT Edge durante la configurazione iniziale del dispositivo.

Daemon Moby

Siccome Moby è basato su Docker, fare riferimento alla documentazione di Docker per configurare il daemon Moby con le variabili di ambiente. La maggior parte dei registri contenitori (compresi DockerHub e registri contenitori Azure) supporta le richieste HTTPS, per cui il parametro da impostare è HTTPS_PROXY. Se si esegue il pull di immagini da un registro che non supporta il protocollo TLS (Transport Layer Security), sarà necessario impostare il parametro HTTP_PROXY.

Scegliere l'articolo pertinente al proprio sistema operativo del dispositivo IoT Edge:

Configurare il daemon Docker in Linux Il daemon Moby nei dispositivi Linux mantiene il nome Docker.
Configurare il daemon Docker in Windows Il daemon Moby nei dispositivi Windows è denominato iotedge-moby. I nomi sono diversi perché è possibile eseguire sia Docker Desktop che Moby in parallelo in un dispositivo Windows.

Daemon IoT Edge

Il daemon IoT Edge è simile al daemon Moby. Usare la procedura seguente per impostare una variabile di ambiente per il servizio, in base al sistema operativo usato.

Il daemon IoT Edge usa sempre HTTPS per inviare richieste all'hub IoT.

Linux

Aprire un editor nel terminale per configurare il daemon IoT Edge.

sudo systemctl edit aziot-edged

Immettere il testo seguente, sostituendo <URL proxy> con la porta e l'indirizzo del server proxy. Quindi, salvare e chiudere.

[Service]
Environment="https_proxy=<proxy URL>"

A partire dalla versione 1.2, IoT Edge usa il servizio di gestione identità IoT per gestire il provisioning dei dispositivi con l'hub IoT o il servizio Device Provisioning in hub IoT. Aprire un editor nel terminale per configurare il daemon del servizio identità IoT.

sudo systemctl edit aziot-identityd

Immettere il testo seguente, sostituendo <URL proxy> con la porta e l'indirizzo del server proxy. Quindi, salvare e chiudere.

[Service]
Environment="https_proxy=<proxy URL>"

Aggiornare Service Manager per scegliere la nuova configurazione.

sudo systemctl daemon-reload

Riavviare il servizio di sistema IoT Edge per applicare le modifiche a entrambi i daemon.

sudo iotedge system restart

Accertarsi che siano presenti le variabili di ambiente e la nuova configurazione.

systemctl show --property=Environment aziot-edged
systemctl show --property=Environment aziot-identityd

Windows con l’uso di IoT Edge per Linux in Windows

Accedere a IoT Edge per Linux nella macchina virtuale Windows:

Connect-EflowVm

Seguire la stessa procedura della sezione Linux di questo articolo per configurare il daemon IoT Edge.

Windows con l’uso di contenitori Windows

Aprire una finestra di PowerShell come amministratore ed eseguire il comando seguente per modificare il registro con la nuova variabile di ambiente. Sostituire <URL proxy> con la porta e l'indirizzo del server proxy.

reg add HKLM\SYSTEM\CurrentControlSet\Services\iotedge /v Environment /t REG_MULTI_SZ /d https_proxy=<proxy URL>

Riavviare IoT Edge per rendere effettive le modifiche apportate.

Restart-Service iotedge

Configurare l'agente IoT Edge

L'agente IoT Edge è il primo modulo che viene avviato in un dispositivo IoT Edge. Questo modulo viene avviato per la prima volta in base alle informazioni nel file di configurazione di IoT Edge. L'agente IoT Edge, quindi, si connette all'hub IoT per recuperare i manifesti della distribuzione. Il manifesto dichiara quali altri moduli devono essere distribuiti dal dispositivo.

Questo passaggio viene eseguito una volta nel dispositivo IoT Edge durante la configurazione iniziale del dispositivo.

Aprire il file di configurazione nel dispositivo IoT Edge: /etc/aziot/config.toml. L’accesso al file di configurazione richiede privileg amministrativi. Nei sistemi Linux, usare il comando sudo prima di aprire il file nell'editor di testo preferito.
Nel file di configurazione, individuare la sezione [agent] che contiene tutte le informazioni di configurazione per il modulo edgeAgent da usare all'avvio. Accertarsi che la sezione [agent] non contenga commenti. Se la sezione [agent] manca, aggiungerla a config.toml. La definizione dell'agente IoT Edge include una sottoscrizione [agent.env] dove è possibile aggiungere variabili di ambiente.

Aggiungere il parametro https_proxy alla sezione delle variabili di ambiente e impostare l'URL proxy come valore.

[agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

Per impostazione predefinita, il runtime IoT Edge usa AMQP per comunicare con l'hub IoT. Alcuni server proxy bloccano le porte AMQP. In tal caso, sarà anche necessario configurare edgeAgent per usare AMQP su WebSocket. Rimuovere i commenti dal parametro UpstreamProtocol.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```

Aggiungere il parametro https_proxy alla sezione delle variabili di ambiente e impostare l'URL proxy come valore.

[agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

Per impostazione predefinita, il runtime IoT Edge usa AMQP per comunicare con l'hub IoT. Alcuni server proxy bloccano le porte AMQP. In tal caso, sarà anche necessario configurare edgeAgent per usare AMQP su WebSocket. Rimuovere i commenti dal parametro UpstreamProtocol.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
Salvare le modifiche e chiudere l'editor. Applicare le modifiche più recenti.
```
sudo iotedge config apply
```
Accertarsi che le impostazioni proxy vengano propagate usando docker inspect edgeAgent nella sezione Env. In caso contrario, è necessario creare nuovamente il contenitore.
```
sudo docker rm -f edgeAgent
```
Il runtime di IoT Edge deve creare nuovamente edgeAgent entro un minuto. Quando il contenitore edgeAgent è di nuovo in esecuzione, usare il comando docker inspect edgeAgent per accertarsi che le impostazioni proxy corrispondano al file di configurazione.

Configurare i manifesti della distribuzione

Dopo aver configurato il dispositivo IoT Edge per l'uso con il server proxy, dichiarare le variabili di ambiente HTTPS_PROXY nei manifesti della distribuzione futuri. È possibile modificare i manifesti della distribuzione usando la procedura guidata del portale di Azure o modificando un file JSON del manifesto della distribuzione.

Configurare sempre i due moduli di runtime, edgeAgent ed edgeHub, per comunicare attraverso il server proxy affinché possano mantenere una connessione con l'hub IoT. Se si rimuovono le informazioni proxy dal modulo edgeAgent, l'unico modo per ristabilire la connessione consiste nella modifica del file di configurazione nel dispositivo, come descritto nella sezione precedente.

Oltre ai moduli edgeAgent ed edgeHub, altri moduli potrebbero richiedere la configurazione del proxy. I moduli che devono accedere alle risorse di Azure oltre all'hub IoT, ad esempio l'archiviazione BLOB, devono avere la variabile HTTPS_PROXY specificata nel file manifesto della distribuzione.

La procedura seguente è applicabile per tutta la durata del dispositivo IoT Edge.

Azure portal

Quando si usa la procedura guidata Imposta moduli per creare distribuzioni per dispositivi IoT Edge, ogni modulo ha una sezione Variabili di ambiente dove è possibile configurare le connessioni al server proxy.

Per configurare i moduli dell'agente IoT Edge e dell'hub IoT Edge, selezionare Impostazioni di runtime nel primo passaggio della procedura guidata.

Screenshot che illustra come configurare le impostazioni avanzate del runtime di IoT Edge.

Aggiungere la variabile di ambiente https_proxy alledefinizioni delle impostazioni del runtime sia del modulo dell’hub di IoT Edge e sia dell'agente IoT Edge. Se si include la variabile di ambiente UpstreamProtocol nel file di configurazione nel dispositivo IoT Edge, aggiungerla anche alla definizione del modulo dell'agente IoT Edge.

Tutti gli altri moduli che vengono aggiunti a un manifesto della distribuzione seguono lo stesso criterio. Selezionare Applica per salvare le modifiche.

File JSON del manifesto della distribuzione

Se le distribuzioni per i dispositivi IoT Edge vengono create usando i modelli in Visual Studio Code o creando manualmente i file JSON, è possibile aggiungere le variabili di ambiente direttamente a ogni definizione del modulo. Se non sono state aggiunte nel portale di Azure, aggiungerle qui al file manifesto JSON. Sostituire <proxy URL> con il proprio valore.

Usare il formato JSON seguente:

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    }
}

Con le variabili di ambiente incluse la definizione del modulo sarà simile a quella illustrata nell'esempio di edgeHub seguente:

"edgeHub": {
    "type": "docker",
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
        "createOptions": "{}"
    },
    "env": {
        "https_proxy": {
            "value": "http://proxy.example.com:3128"
        }
    },
    "status": "running",
    "restartPolicy": "always"
}

Se nel file config.yaml è stata inclusa la variabile di ambiente UpstreamProtocol nel dispositivo IoT Edge, aggiungerla anche alla definizione del modulo dell'agente IoT Edge.

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    },
    "UpstreamProtocol": {
        "value": "AmqpWs"
    }
}

Uso dei proxy di ispezione del traffico

Alcuni proxy come Zscaler possono ispezionare il traffico crittografato TLS. Durante l'ispezione del traffico TLS, il certificato restituito dal proxy non è il certificato del server di destinazione, ma è il certificato firmato dal certificato radice del proxy. Per impostazione predefinita, i moduli IoT Edge (inclusi edgeAgent ed edgeHub) non considerano attendibile il certificato del proxy e l'handshake TLS non riesce.

Per risolvere l'handshake non riuscito, configurare sia il sistema operativo che i moduli IoT Edge per considerare attendibile il certificato radice del proxy con i passaggi seguenti.

Configurare il certificato proxy nell'archivio certificati radice trusted del sistema operativo host. Per altre informazioni sull'installazione di un certificato client, vedere Installare una CA radice nell’archivio certificati del sistema operativo.
Configurare il dispositivo IoT Edge per comunicare tramite un server proxy facendo riferimento al certificato nel bundle di attendibilità. Per altre informazioni su come configurare il bundle di attendibilità, vedere Gestire una CA radice attendibile (bundle di attendibilità).

Per configurare il supporto del proxy di ispezione del traffico per i contenitori non gestiti da IoT Edge, contattare il provider proxy.

Nomi di dominio completi (FQDN) di destinazioni con cui IoT Edge comunica

Se il firewall del proxy richiede di aggiungere tutti gli FQDN all'elenco di elementi consentiti per la connettività Internet, esaminare l'elenco da Consentire connessioni da dispositivi IoT Edge per determinare quali FQDN aggiungere.

Passaggi successivi

Altre informazioni sui ruoli del runtime IoT Edge.

Risolvere gli errori di installazione e configurazione con Problemi comuni e soluzioni per Azure IoT Edge

Condividi tramite