Configurare un dispositivo IoT Edge per comunicare tramite un server proxy

Articolo
07/26/2022

Si applica a: IoT Edge 1.1

Importante

La data di fine del supporto di IoT Edge 1.1 è stata il 13 dicembre 2022. Controlla il ciclo di vita dei prodotti Microsoft per ottenere informazioni sul modo in cui viene supportato questo prodotto, servizio, tecnologia o API. Per altre informazioni sull'aggiornamento alla versione più recente di IoT Edge, 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 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 indirizzate 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. Le 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. Per consentire all'agente IoT Edge di stabilire la connessione iniziale a hub IoT, configurare manualmente le variabili di ambiente del modulo edgeAgent nel dispositivo stesso. 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 il 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 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 sono necessari altri passaggi di installazione o aggiornamento.

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 si hanno credenziali complesse per il server proxy che non è possibile includere nell'URL, usare il parametro -ProxyCredential all'interno di -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. Per altre informazioni sui parametri di installazione di Windows, vedere Script di PowerShell per IoT Edge in Windows.

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.

Sia moby che i daemon IoT Edge devono essere configurati 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 è configurato in modo analogo 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 iotedge

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 in modo da scegliere la nuova configurazione per IoT Edge.

sudo systemctl daemon-reload

Riavviare IoT Edge per rendere effettive le modifiche apportate.

sudo systemctl restart iotedge

Verificare che la variabile di ambiente sia stata creata e che la nuova configurazione sia stata caricata.

systemctl show --property=Environment iotedge

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

Accedere alla macchina virtuale IoT Edge per Linux in Windows:

Connect-EflowVm

Seguire gli stessi passaggi della sezione Linux precedente 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. Viene avviata per la prima volta in base alle informazioni nel file di configurazione di IoT Edge. L'agente IoT Edge si connette quindi all'hub IoT per recuperare i manifesti della distribuzione, che dichiarano quali altri moduli devono essere distribuiti nel dispositivo.

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

Aprire il file config.yaml nel dispositivo IoT Edge. Nei sistemi Linux questo file si trova in /etc/iotedge/config.yaml. Nei sistemi Windows questo file si trova in C:\ProgramData\iotedge\config.yaml. Il file di configurazione è protetto, pertanto sono necessari i privilegi amministrativi per accedervi. Nei sistemi Linux, usare il comando sudo prima di aprire il file nell'editor di testo preferito. In Windows aprire un editor di testo come Blocco note come amministratore e quindi aprire il file.
Nel file config.yaml trovare la sezione Edge Agent module spec. La definizione dell'agente IoT Edge include un parametro env in cui è possibile aggiungere le variabili di ambiente.
Rimuovere le parentesi graffe che sono un segnaposto per il parametro env e aggiungere la nuova variabile in una nuova riga. Tenere presente che i rientri in YAML sono rappresentati da due spazi.
```
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. Aggiungere una seconda variabile di ambiente.
```
UpstreamProtocol: "AmqpWs"
```
Salvare le modifiche apportate a config.yaml e chiudere l'editor. Riavviare IoT Edge per rendere effettive le modifiche apportate.
- Linux e IoT Edge per Linux in Windows:
```
sudo systemctl restart iotedge
```
- Windows con i contenitori di Windows:
```
Restart-Service iotedge
```

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.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 i commenti dal parametro UpstreamProtocol.
```
[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
```
Accertarsi che le impostazioni proxy vengano propagate usando docker inspect edgeAgent nella sezione Env. In caso contrario, il contenitore deve essere ricreato.
```
sudo docker rm -f edgeAgent
```
Il runtime di IoT Edge deve creare nuovamente edgeAgent entro un minuto. Quando edgeAgent il contenitore viene eseguito di nuovo docker inspect edgeAgent e verificare che le impostazioni proxy corrispondano al file di configurazione.

Configurare i manifesti della distribuzione

Dopo aver configurato il dispositivo IoT Edge per funzionare con il server proxy, è necessario continuare a dichiarare la variabile di ambiente HTTPS_PROXY nei manifesti di 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.

Configura impostazioni avanzate per il runtime di IoT Edge

Aggiungere la variabile di ambiente https_proxy alle definizioni dei moduli sia dell'agente IoT Edge sia dell'hub 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.

Impostare la variabile di ambiente https_proxy

Tutti gli altri moduli che vengono aggiunti a un manifesto della distribuzione seguono lo stesso criterio.

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.

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.1",
        "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, il certificato del proxy non è considerato attendibile dai moduli IoT Edge (inclusi edgeAgent e edgeHub) e l'handshake TLS ha esito negativo.

Per risolvere questo problema, il certificato radice del proxy deve essere considerato attendibile sia dal sistema operativo che dai moduli IoT Edge.

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 proxy dispone di un firewall che richiede di consentire l'elenco di tutti i nomi di dominio completi per la connettività Internet, esaminare l'elenco da Consenti connessioni dai dispositivi IoT Edge per determinare quali nomi di dominio completi 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