Een IoT Edge-apparaat configureren om te communiceren via een proxyserver

Artikel
04/11/2024

Van toepassing op: IoT Edge 1.5 IoT Edge 1.4

Belangrijk

IoT Edge 1.5 LTS en IoT Edge 1.4 LTS worden ondersteund releases. IoT Edge 1.4 LTS eindigt op 12 november 2024. Raadpleeg IoT Edge bijwerken als u een eerdere versie hebt.

IoT Edge-apparaten verzenden HTTPS-aanvragen om te communiceren met IoT Hub. Als u uw apparaat hebt verbonden met een netwerk dat gebruikmaakt van een proxyserver, moet u de IoT Edge-runtime configureren om via de server te communiceren. Proxyservers kunnen ook van invloed zijn op afzonderlijke IoT Edge-modules als ze HTTP- of HTTPS-aanvragen indienen die u niet hebt gerouteerd via de IoT Edge-hub.

In dit artikel worden de volgende vier stappen beschreven voor het configureren en beheren van een IoT Edge-apparaat achter een proxyserver:

De IoT Edge-runtime installeren op uw apparaat

Met de IoT Edge-installatiescripts worden pakketten en bestanden opgehaald van internet, zodat uw apparaat via de proxyserver moet communiceren om deze aanvragen te kunnen indienen. Voor Windows-apparaten biedt het installatiescript ook een offline-installatieoptie.

Deze stap is een eenmalig proces voor het configureren van het IoT Edge-apparaat wanneer u het voor het eerst instelt. U hebt ook dezelfde verbindingen nodig wanneer u de IoT Edge-runtime bijwerkt.
IoT Edge en de containerruntime op uw apparaat configureren

IoT Edge is verantwoordelijk voor communicatie met IoT Hub. De containerruntime is verantwoordelijk voor containerbeheer, dus communiceert met containerregisters. Beide onderdelen moeten webaanvragen doen via de proxyserver.

Deze stap is een eenmalig proces voor het configureren van het IoT Edge-apparaat wanneer u het voor het eerst instelt.
De eigenschappen van de IoT Edge-agent configureren in het configuratiebestand op uw apparaat

De IoT Edge-daemon start in eerste instantie de edgeAgent-module. Vervolgens haalt de edgeAgent-module het implementatiemanifest op uit IoT Hub en start u alle andere modules. Configureer de omgevingsvariabelen van de EdgeAgent-module handmatig op het apparaat zelf, zodat de IoT Edge-agent de eerste verbinding met IoT Hub kan maken. Na de eerste verbinding kunt u de edgeAgent-module extern configureren.

Deze stap is een eenmalig proces voor het configureren van het IoT Edge-apparaat wanneer u het voor het eerst instelt.
Voor alle toekomstige module-implementaties stelt u omgevingsvariabelen in voor elke module die via de proxy communiceert

Zodra u een IoT Edge-apparaat hebt ingesteld en verbonden met IoT Hub via de proxyserver, moet u de verbinding in alle toekomstige module-implementaties onderhouden.

Deze stap is een doorlopend proces dat op afstand wordt uitgevoerd, zodat elke nieuwe module of implementatie-update de mogelijkheid van het apparaat behoudt om te communiceren via de proxyserver.

Uw proxy-URL kennen

Voordat u begint met een van de stappen in dit artikel, moet u uw proxy-URL kennen.

Proxy-URL's hebben de volgende indeling: protocol://proxy_host:proxy_port.

Het protocol is HTTP of HTTPS. De Docker-daemon kan beide protocollen gebruiken, afhankelijk van uw containerregisterinstellingen, maar de IoT Edge-daemon en runtimecontainers moeten altijd HTTP gebruiken om verbinding te maken met de proxy.
De proxy_host is een adres voor de proxyserver. Als voor uw proxyserver verificatie is vereist, kunt u uw referenties opgeven als onderdeel van de proxyhost met de volgende indeling: user:password@proxy_host.
De proxy_port is de netwerkpoort waarop de proxy reageert op netwerkverkeer.

IoT Edge installeren via een proxy

Of uw IoT Edge-apparaat nu wordt uitgevoerd in Windows of Linux, u moet toegang krijgen tot de installatiepakketten via de proxyserver. Afhankelijk van uw besturingssysteem volgt u de stappen voor het installeren van de IoT Edge-runtime via een proxyserver.

Linux-apparaten

Als u de IoT Edge-runtime op een Linux-apparaat installeert, configureert u pakketbeheer om uw proxyserver te doorlopen voor toegang tot het installatiepakket. Stel bijvoorbeeld apt-get in voor het gebruik van een http-proxy. Zodra u pakketbeheer hebt geconfigureerd, volgt u de instructies in Azure IoT Edge-runtime installeren zoals gebruikelijk.

Windows-apparaten met IoT Edge voor Linux in Windows

Als u de IoT Edge-runtime installeert met behulp van IoT Edge voor Linux in Windows, wordt IoT Edge standaard geïnstalleerd op uw virtuele Linux-machine. U hoeft geen andere stappen te installeren of bij te werken.

Windows-apparaten met Windows-containers

Als u de IoT Edge-runtime op een Windows-apparaat installeert, moet u de proxyserver twee keer doorlopen. De eerste verbinding downloadt het scriptbestand van het installatieprogramma en de tweede verbinding is tijdens de installatie om de benodigde onderdelen te downloaden. U kunt proxygegevens configureren in Windows-instellingen of uw proxygegevens rechtstreeks opnemen in de PowerShell-opdrachten.

In de volgende stappen ziet u een voorbeeld van een Windows-installatie met behulp van het -proxy argument:

De opdracht Invoke-WebRequest heeft proxygegevens nodig voor toegang tot het installatiescript. Vervolgens heeft de opdracht Deploy-IoTEdge de proxygegevens nodig om de installatiebestanden te downloaden.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
```
De opdracht Initialize-IoTEdge hoeft niet door de proxyserver te gaan, dus de tweede stap vereist alleen proxygegevens voor Invoke-WebRequest.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
```

Als u ingewikkelde referenties hebt voor de proxyserver die u niet in de URL kunt opnemen, gebruikt u de -ProxyCredential parameter binnen -InvokeWebRequestParameters. Voorbeeld:

$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 }

Zie Invoke-WebRequest voor meer informatie over proxyparameters.

IoT Edge en Moby configureren

IoT Edge is afhankelijk van twee daemons die worden uitgevoerd op het IoT Edge-apparaat. De Moby-daemon doet webaanvragen voor het ophalen van containerinstallatiekopieën uit containerregisters. De IoT Edge-daemon voert webaanvragen uit om te communiceren met IoT Hub.

U moet zowel de Moby- als de IoT Edge-daemons configureren om de proxyserver te gebruiken voor doorlopende apparaatfunctionaliteit. Deze stap vindt plaats op het IoT Edge-apparaat tijdens de eerste installatie van het apparaat.

Moby-daemon

Aangezien Moby is gebouwd op Docker, raadpleegt u de Docker-documentatie om de Moby-daemon te configureren met omgevingsvariabelen. De meeste containerregisters (inclusief DockerHub en Azure Container Registries) ondersteunen HTTPS-aanvragen, dus de parameter die u moet instellen, is HTTPS_PROXY. Als u installatiekopieën ophaalt uit een register dat geen tls (Transport Layer Security) ondersteunt, moet u de parameter HTTP_PROXY instellen.

Kies het artikel dat van toepassing is op het besturingssysteem van uw IoT Edge-apparaat:

Configureer Docker-daemon in Linux The Moby-daemon op Linux-apparaten en houd de naam Docker bij.
Docker-daemon configureren in Windows The Moby-daemon op Windows-apparaten wordt iotedge-moby genoemd. De namen verschillen omdat het mogelijk is om docker Desktop en Moby parallel uit te voeren op een Windows-apparaat.

IoT Edge-daemon

De IoT Edge-daemon is vergelijkbaar met de Moby-daemon. Gebruik de volgende stappen om een omgevingsvariabele in te stellen voor de service, op basis van uw besturingssysteem.

De IoT Edge-daemon gebruikt altijd HTTPS om aanvragen naar IoT Hub te verzenden.

Linux

Open een editor in de terminal om de IoT Edge-daemon te configureren.

sudo systemctl edit aziot-edged

Voer de volgende tekst in en vervang de proxy-URL> door <het adres en de poort van uw proxyserver. Sla het bestand vervolgens op en sluit deze af.

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

Vanaf versie 1.2 maakt IoT Edge gebruik van de IoT-identiteitsservice voor het afhandelen van apparaatinrichting met IoT Hub of IoT Hub Device Provisioning Service. Open een editor in de terminal om de IoT Identity Service-daemon te configureren.

sudo systemctl edit aziot-identityd

Voer de volgende tekst in en vervang de proxy-URL> door <het adres en de poort van uw proxyserver. Sla het bestand vervolgens op en sluit deze af.

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

Vernieuw de Service Manager om de nieuwe configuraties op te halen.

sudo systemctl daemon-reload

Start de IoT Edge-systeemservices opnieuw om de wijzigingen in beide daemons van kracht te laten worden.

sudo iotedge system restart

Controleer of uw omgevingsvariabelen en de nieuwe configuratie aanwezig zijn.

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

Windows met IoT Edge voor Linux in Windows

Meld u aan bij uw IoT Edge voor Linux op een virtuele Windows-machine:

Connect-EflowVm

Volg dezelfde stappen als de Linux-sectie van dit artikel om de IoT Edge-daemon te configureren.

Windows met Windows-containers

Open een PowerShell-venster als beheerder en voer de volgende opdracht uit om het register te bewerken met de nieuwe omgevingsvariabele. Vervang <de proxy-URL> door het adres en de poort van uw proxyserver.

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

Start IoT Edge opnieuw om de wijzigingen van kracht te laten worden.

Restart-Service iotedge

De IoT Edge-agent configureren

De IoT Edge-agent is de eerste module die moet worden gestart op elk IoT Edge-apparaat. Deze module wordt voor het eerst gestart op basis van informatie in het IoT Edge-configuratiebestand. De IoT Edge-agent maakt vervolgens verbinding met IoT Hub om implementatiemanifesten op te halen. Het manifest declareert welke andere modules het apparaat moet implementeren.

Deze stap vindt eenmaal plaats op het IoT Edge-apparaat tijdens de eerste installatie van het apparaat.

Open het configuratiebestand op uw IoT Edge-apparaat: /etc/aziot/config.toml. U hebt beheerdersbevoegdheden nodig voor toegang tot het configuratiebestand. Gebruik op Linux-systemen de sudo opdracht voordat u het bestand opent in de teksteditor van uw voorkeur.
Zoek in het configuratiebestand de [agent] sectie, die alle configuratiegegevens bevat voor de edgeAgent-module die bij het opstarten kan worden gebruikt. Controleer of de [agent] sectie zonder opmerkingen is. Als de sectie ontbreekt, voegt u deze [agent] toe aan de config.tomlsectie. De Definitie van de IoT Edge-agent bevat een [agent.env] subsectie waarin u omgevingsvariabelen kunt toevoegen.

Voeg de parameter https_proxy toe aan de sectie omgevingsvariabelen en stel de proxy-URL in als waarde.

[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>"

De IoT Edge-runtime maakt standaard gebruik van AMQP om te communiceren met IoT Hub. Sommige proxyservers blokkeren AMQP-poorten. Als dat het geval is, moet u ook edgeAgent configureren voor het gebruik van AMQP via WebSocket. Verwijder de opmerkingen bij de UpstreamProtocol parameter.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

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

Voeg de parameter https_proxy toe aan de sectie omgevingsvariabelen en stel de proxy-URL in als waarde.

[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>"

De IoT Edge-runtime maakt standaard gebruik van AMQP om te communiceren met IoT Hub. Sommige proxyservers blokkeren AMQP-poorten. Als dat het geval is, moet u ook edgeAgent configureren voor het gebruik van AMQP via WebSocket. Verwijder de opmerkingen bij de UpstreamProtocol parameter.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
Sla de wijzigingen op en sluit de editor. Pas de meest recente wijzigingen toe.
```
sudo iotedge config apply
```
Controleer of uw proxy-instellingen worden doorgegeven met behulp van docker inspect edgeAgent de Env sectie. Zo niet, dan moet u de container opnieuw maken.
```
sudo docker rm -f edgeAgent
```
De IoT Edge-runtime moet binnen een minuut opnieuw worden gemaakt edgeAgent . Zodra de edgeAgent container opnieuw wordt uitgevoerd, gebruikt u de docker inspect edgeAgent opdracht om te controleren of de proxy-instellingen overeenkomen met het configuratiebestand.

Implementatiemanifesten configureren

Zodra u uw IoT Edge-apparaat hebt geconfigureerd voor gebruik met uw proxyserver, declareert u de HTTPS_PROXY omgevingsvariabele in toekomstige implementatiemanifesten. U kunt implementatiemanifesten bewerken met behulp van de wizard Azure Portal of door een JSON-bestand voor het implementatiemanifest te bewerken.

Configureer altijd de twee runtimemodules edgeAgent en edgeHub om te communiceren via de proxyserver, zodat ze een verbinding met IoT Hub kunnen onderhouden. Als u de proxygegevens uit de edgeAgent-module verwijdert, kunt u de verbinding alleen herstellen door het configuratiebestand op het apparaat te bewerken, zoals beschreven in de vorige sectie.

Naast de edgeAgent- en EdgeHub-modules hebben andere modules mogelijk de proxyconfiguratie nodig. Modules die toegang moeten hebben tot Azure-resources, naast IoT Hub, zoals blobopslag, moeten beschikken over de HTTPS_PROXY variabele die is opgegeven in het distributiemanifestbestand.

De volgende procedure is van toepassing gedurende de levensduur van het IoT Edge-apparaat.

Azure Portal

Wanneer u de wizard Modules instellen gebruikt om implementaties te maken voor IoT Edge-apparaten, heeft elke module een sectie Omgevingsvariabelen waarin u proxyserververbindingen kunt configureren.

Als u de IoT Edge-agent- en IoT Edge-hubmodules wilt configureren, selecteert u Runtime-Instellingen in de eerste stap van de wizard.

Schermopname van het configureren van geavanceerde Edge Runtime-instellingen.

Voeg de omgevingsvariabele https_proxy toe aan zowel de IoT Edge-agent als de runtime-instellingendefinities van de IoT Edge-hubmodule . Als u de omgevingsvariabele UpstreamProtocol hebt opgenomen in het configuratiebestand op uw IoT Edge-apparaat, voegt u deze ook toe aan de definitie van de IoT Edge-agentmodule.

Alle andere modules die u aan een implementatiemanifest toevoegt, volgen hetzelfde patroon. Selecteer Toepassen om uw wijzigingen op te slaan.

Manifestbestanden voor JSON-implementatie

Als u implementaties voor IoT Edge-apparaten maakt met behulp van de sjablonen in Visual Studio Code of door handmatig JSON-bestanden te maken, kunt u de omgevingsvariabelen rechtstreeks toevoegen aan elke moduledefinitie. Als u ze niet hebt toegevoegd in Azure Portal, voegt u deze hier toe aan uw JSON-manifestbestand. Vervang door <proxy URL> uw eigen waarde.

Gebruik de volgende JSON-indeling:

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

Nu de omgevingsvariabelen zijn opgenomen, moet uw moduledefinitie eruitzien zoals in het volgende edgeHub-voorbeeld:

"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"
}

Als u de omgevingsvariabele UpstreamProtocol hebt opgenomen in het bestand confige.yaml op uw IoT Edge-apparaat, voegt u deze ook toe aan de definitie van de IoT Edge-agentmodule.

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

Werken met traffic-inspecterende proxy's

Sommige proxy's zoals Zscaler kunnen TLS-versleuteld verkeer inspecteren. Tijdens inspectie van TLS-verkeer is het certificaat dat door de proxy wordt geretourneerd niet het certificaat van de doelserver, maar in plaats daarvan is het certificaat ondertekend door het eigen basiscertificaat van de proxy. Standaard vertrouwen IoT Edge-modules (inclusief edgeAgent en edgeHub) het certificaat van deze proxy niet en mislukt de TLS-handshake.

Als u de mislukte handshake wilt oplossen, configureert u zowel het besturingssysteem als de IoT Edge-modules om het basiscertificaat van de proxy te vertrouwen met de volgende stappen.

Configureer het proxycertificaat in het vertrouwde basiscertificaatarchief van uw hostbesturingssysteem. Zie Basis-CA installeren in het certificaatarchief van het besturingssysteem voor meer informatie over het installeren van een basiscertificaat.
Configureer uw IoT Edge-apparaat om te communiceren via een proxyserver door te verwijzen naar het certificaat in de vertrouwensbundel. Zie Vertrouwde basis-CA (vertrouwensbundel) beheren voor meer informatie over het configureren van de vertrouwensbundel.

Neem contact op met uw proxyprovider om proxyondersteuning voor verkeersinspectie te configureren voor containers die niet worden beheerd door IoT Edge.

FQDN's (Fully Qualified Domain Names) van bestemmingen waarmee IoT Edge communiceert

Als de firewall van uw proxy vereist dat u alle FQDN's toevoegt aan uw acceptatielijst voor internetverbinding, raadpleegt u de lijst van Toegestane verbindingen van IoT Edge-apparaten om te bepalen welke FQDN's moeten worden toegevoegd.

Volgende stappen

Meer informatie over de rollen van de IoT Edge-runtime.

Installatie- en configuratiefouten oplossen met veelvoorkomende problemen en oplossingen voor Azure IoT Edge