Configurare un dispositivo IoT Edge per comunicare tramite un server proxy

Articolo
04/11/2024

Si applica a: IoT Edge 1.4

Importante

IoT Edge 1.4 è la versione supportata. 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 è stato 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 anche influire sui singoli moduli IoT Edge se effettuano richieste HTTP o HTTPS che non sono state instradate tramite l'hub 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 offre anche un'opzione di installazione offline.

Questo passaggio è un processo monouso per configurare il dispositivo IoT Edge quando viene configurato per la prima volta. 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 è responsabile delle comunicazioni con hub IoT. Il runtime del contenitore è responsabile della gestione dei contenitori, quindi comunica con i registri contenitori. Entrambi questi componenti devono effettuare richieste Web tramite il server proxy.

Questo passaggio è un processo monouso per configurare il dispositivo IoT Edge quando viene configurato per la prima volta.
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 recupera quindi il manifesto della distribuzione da 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 a hub IoT. Dopo la connessione iniziale, è possibile configurare il modulo edgeAgent in modalità remota.

Questo passaggio è un processo monouso per configurare il dispositivo IoT Edge quando viene configurato per la prima volta.
Per tutte le distribuzioni di moduli futuri, impostare le variabili di ambiente per qualsiasi modulo che comunica tramite il proxy

Dopo aver configurato e connesso un dispositivo IoT Edge a hub IoT tramite il server proxy, è necessario mantenere la connessione in tutte le distribuzioni future del modulo.

Questo passaggio è un processo in corso 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ò usare entrambi i protocolli, a seconda delle impostazioni del registro contenitori, ma i contenitori del daemon e del runtime di IoT Edge devono sempre usare HTTP per connettersi 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: user: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

Indipendentemente dal fatto 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 di IoT Edge in un dispositivo Windows, è necessario passare attraverso il server proxy due volte. La prima connessione scarica il file di script del programma di installazione e la seconda è durante l'installazione per scaricare i componenti necessari. È possibile configurare le informazioni proxy nelle impostazioni di Windows o includere le informazioni sul proxy direttamente nei comandi di PowerShell.

I passaggi seguenti illustrano un esempio di 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 richiede quindi le informazioni sul 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 sono presenti credenziali complesse per il server proxy che non è possibile includere nell'URL, usare il -ProxyCredential parametro all'interno -InvokeWebRequestParametersdi . 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 delle immagini del contenitore 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

Poiché 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 applicabile al 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 a hub IoT.

Linux

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

sudo systemctl edit aziot-edged

Immettere il testo seguente, sostituendo <l'URL> proxy con l'indirizzo e la porta 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 delle identità IoT per gestire il provisioning dei dispositivi con hub IoT o hub IoT servizio Device Provisioning. Aprire un editor nel terminale per configurare il daemon del servizio di gestione delle identità IoT.

sudo systemctl edit aziot-identityd

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

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

Aggiornare gestione servizi per selezionare le nuove configurazioni.

sudo systemctl daemon-reload

Riavviare i servizi di sistema IoT Edge per rendere effettive le modifiche apportate a entrambi i daemon.

sudo iotedge system restart

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

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

Windows che usa IoT Edge per Linux in Windows

Accedere alla macchina virtuale IoT Edge per Linux in Windows:

Connect-EflowVm

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

Windows che usa i contenitori di Windows

Aprire una finestra di PowerShell come amministratore ed eseguire il comando seguente per modificare il registro con la nuova variabile di ambiente. Sostituire <l'URL proxy con l'indirizzo> e la porta 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 si connette quindi a hub IoT per recuperare i manifesti della distribuzione. Il manifesto dichiara quali altri moduli devono essere distribuiti dal dispositivo.

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

Aprire il file di configurazione nel dispositivo IoT Edge: /etc/aziot/config.toml. Per accedere al file di configurazione sono necessari privilegi amministrativi. Nei sistemi Linux usare il sudo comando prima di aprire il file nell'editor di testo preferito.
Nel file di configurazione trovare la [agent] sezione contenente tutte le informazioni di configurazione per il modulo edgeAgent da usare all'avvio. Verificare che la [agent] sezione sia senza commenti. Se la [agent] sezione non è presente, aggiungerla a config.toml. La definizione dell'agente IoT Edge include una [agent.env] sottosezione in cui è possibile aggiungere variabili di ambiente.

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

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

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

[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 il commento dal UpstreamProtocol parametro .
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.4"

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

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

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

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

[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 il commento dal UpstreamProtocol parametro .
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.4"

[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
```
Verificare che le impostazioni proxy vengano propagate usando docker inspect edgeAgent nella Env sezione . In caso contrario, è necessario ricreare il contenitore.
```
sudo docker rm -f edgeAgent
```
Il runtime di IoT Edge deve essere ricreato edgeAgent entro un minuto. Quando il contenitore è di nuovo in esecuzione, usare il edgeAgentdocker inspect edgeAgent comando per verificare 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 la variabile di ambiente HTTPS_PROXY nei manifesti di distribuzione futuri. È possibile modificare i manifesti di distribuzione usando la procedura guidata 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 del proxy dal modulo edgeAgent, l'unico modo per ristabilire la connessione consiste nel modificare il file di configurazione nel dispositivo, come descritto nella sezione precedente.

Oltre ai moduli edgeAgent e edgeHub, altri moduli potrebbero richiedere la configurazione del proxy. I moduli che devono accedere alle risorse di Azure oltre a 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 i dispositivi IoT Edge, ogni modulo ha una sezione Variabili di ambiente in cui è possibile configurare le connessioni server proxy.

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

Screenshot of how to configure advanced Edge Runtime settings.

Aggiungere la variabile di ambiente https_proxy alle definizioni dei moduli sia dell'agente IoT Edge sia dell'hub IoT Edge. Se è stata inclusa la variabile di ambiente UpstreamProtocol nel file di configurazione nel dispositivo IoT Edge, aggiungerla anche alla definizione del modulo agente IoT Edge.

Screenshot of how to set the https_proxy environment variable.

Tutti gli altri moduli che vengono aggiunti a un manifesto della distribuzione seguono lo stesso criterio. Seleziona 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 stati aggiunti nel portale di Azure, aggiungerli 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.4",
        "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 controllo del traffico

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

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 attendibile del sistema operativo host. Per altre informazioni su come installare un certificato radice, vedere Installare la 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 un'autorità di certificazione 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 i nomi di dominio completi all'elenco di indirizzi consentiti per la connettività Internet, esaminare l'elenco da Consenti connessioni dai 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