Konfigurieren eines IoT Edge-Geräts für die Kommunikation über einen Proxyserver

Artikel
04/11/2024

Gilt für: IoT Edge 1.5 IoT Edge 1.4

Wichtig

IoT Edge 1.5 LTS und IoT Edge 1.4 LTS sind unterstützte Releases. Das Ende der Lebensdauer von IoT Edge 1.4 LTS wird am 12. November 2024 erreicht. Wenn Sie ein früheres Release verwenden, finden Sie weitere Informationen unter Aktualisieren von IoT Edge.

IoT Edge-Geräte senden HTTPS-Anforderungen, um mit IoT Hub zu kommunizieren. Wenn Ihr Gerät mit einem Netzwerk verbunden ist, das einen Proxyserver verwendet, müssen Sie die IoT Edge-Runtime für die Kommunikation über den Server konfigurieren. Proxyserver können auch einzelne IoT Edge-Module beeinflussen, wenn sie HTTP- oder HTTPS-Anforderungen senden, die nicht über den IoT Edge-Hub weitergeleitet werden.

Dieser Artikel geht die folgenden vier Schritte zum Konfigurieren und anschließenden Verwalten eines IoT Edge-Geräts durch, das sich hinter einem Proxyserver befindet:

Installieren Sie die IoT Edge-Runtime auf Ihrem Gerät.

Die IoT Edge-Installationsskripts pullen Pakete und Dateien aus dem Internet, weshalb Ihr Gerät über den Proxyserver kommunizieren können muss, um diese Anforderungen auszuführen. Windows-Geräten bietet das Installationsskript außerdem eine Option für die Offlineinstallation.

Dieser Schritt ist ein einmaliger Prozess zum Konfigurieren des IoT Edge-Geräts, wenn Sie es zum ersten Mal einrichten. Sie benötigen dieselben Verbindungen auch, wenn Sie die IoT Edge-Runtime aktualisieren.
Konfigurieren von IoT Edge und der Containerruntime auf Ihrem Gerät

IoT Edge ist für die Kommunikation mit IoT Hub zuständig. Die Containerruntime ist für die Containerverwaltung zuständig, kommuniziert also mit Containerregistrierungen. Beide Komponenten müssen Webanforderungen über den Proxyserver senden.

Dieser Schritt ist ein einmaliger Prozess zum Konfigurieren des IoT Edge-Geräts, wenn Sie es zum ersten Mal einrichten.
Konfigurieren der IoT Edge-Agenteigenschaften in der Konfigurationsdatei auf Ihrem Gerät

Der IoT Edge-Daemon startet zunächst das edgeAgent-Modul. Dann ruft das edgeAgent-Modul das Bereitstellungsmanifest aus IoT Hub ab und startet alle anderen Module. Damit der IoT Edge-Agent die anfängliche Verbindung mit IoT Hub herstellen kann, konfigurieren Sie die Umgebungsvariablen des edgeAgent-Moduls manuell auf dem Gerät selbst. Nach der ersten Verbindung können Sie das edgeAgent-Modul remote konfigurieren.

Dieser Schritt ist ein einmaliger Prozess zum Konfigurieren des IoT Edge-Geräts, wenn Sie es zum ersten Mal einrichten.
Legen Sie für alle zukünftigen Modulbereitstellungen Umgebungsvariablen für jedes Modul fest, das über den Proxy kommuniziert.

Nachdem Ihr IoT Edge-Gerät eingerichtet und über den Proxyserver mit IoT Hub verbunden wurde, müssen Sie die Verbindung in allen zukünftigen Modulbereitstellungen beibehalten.

Dieser Schritt ist ein fortlaufender Prozess, der remote ausgeführt wird, sodass jedes neue Modul oder Bereitstellungsupdate die Fähigkeit des Geräts beibehält, über den Proxyserver zu kommunizieren.

Ermitteln der Webproxy-URL

Bevor Sie mit einem der Schritte in diesem Artikel beginnen, müssen Sie Ihre Proxy-URL kennen.

Proxy-URLs haben das folgende Format: Protokoll://Proxyhost:Proxyport.

Das Protokoll ist entweder HTTP oder HTTPS. Der Docker-Daemon kann abhängig von den Einstellungen Ihrer Containerregistrierung beide Protokolle verwenden, aber für den IoT Edge-Daemon und die Runtimecontainer sollte für Verbindungen mit dem Proxy immer HTTP verwendet werden.
Der Proxyhost ist eine Adresse für den Proxyserver. Wenn Ihr Proxyserver eine Authentifizierung erfordert, können Sie Ihre Anmeldeinformationen als Teil von „Proxyhost“ mit dem folgenden Format eingeben: Benutzer:Kennwort@Proxyhost.
Der Proxyport ist der Netzwerkport, an dem der Proxy auf Netzwerkdatenverkehr antwortet.

Installieren von IoT Edge über einen Proxy

Ob Ihr IoT Edge-Gerät unter Windows oder Linux ausgeführt wird, Sie müssen über den Proxyserver auf die Installationspakete zugreifen. Befolgen Sie in Abhängigkeit von Ihrem Betriebssystem die Schritte zum Installieren der IoT Edge-Runtime durch einen Proxyserver.

Linux-Geräte

Wenn Sie IoT Edge-Runtime auf einem Linux-Gerät installieren, konfigurieren Sie den Paket-Manager so, dass er über den Proxyserver auf das Installationspaket zugreift. Beispiel: Richten Sie „apt-get“ zur Verwendung eines http-Proxys ein. Nachdem Sie Ihren Paket-Manager konfiguriert haben, befolgen Sie wie gewohnt die Anweisungen unter Installieren von Azure IoT Edge-Runtime.

Windows-Geräte mit IoT Edge für Linux unter Windows

Wenn Sie die IoT Edge Runtime mit IoT Edge für Linux unter Windows installieren, wird IoT Edge auf Ihrem virtuellen Linux-Computer standardmäßig installiert. Sie müssen keine weiteren Komponenten installieren oder aktualisieren.

Windows-Geräte mit Windows-Containern

Wenn Sie IoT Edge-Runtime auf einem Windows-Gerät installieren, müssen Sie den Proxyserver zwei Mal durchlaufen. Mit der ersten Verbindung wird die Installationsskriptdatei heruntergeladen, und die zweite Verbindung erfolgt während der Installation, um die erforderlichen Komponenten herunterzuladen. Sie können Proxyinformationen in den Windows-Einstellungen konfigurieren oder Ihre Proxyinformationen direkt in die PowerShell-Befehle aufnehmen.

Die folgenden Schritte zeigen ein Beispiel für eine Windows-Installation mithilfe des -proxy-Arguments:

Der Befehl Invoke-WebRequest benötigt Proxyinformationen, um auf das Installationsprogrammskript zuzugreifen. Anschließend benötigt der Befehl Deploy-IoTEdge die Proxyinformationen, um die Installationsdateien herunterzuladen.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
```
Der Befehl Initialize-IoTEdge muss nicht über den Proxyserver gehen, daher benötigt der zweite Schritt nur Proxyinformationen für Invoke-WebRequest.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
```

Wenn Sie komplexe Anmeldeinformationen für den Proxyserver verwenden, die nicht in die URL eingeschlossen werden können, verwenden Sie den -ProxyCredential-Parameter in -InvokeWebRequestParameters. Beispiel:

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

Weitere Informationen zu Proxyparametern finden Sie unter Invoke-WebRequest.

Konfigurieren von IoT Edge und Moby

IoT Edge basiert auf zwei Daemons, die auf dem IoT Edge-Gerät ausgeführt werden. Der Moby-Daemon ruft mit Webanforderungen Containerimages aus Containerregistrierungen ab. Der IoT Edge-Daemon kommuniziert über Webanforderungen mit IoT Hub.

Sowohl der Moby- als auch der IoT Edge-Daemon muss für die Verwendung des Proxyservers konfiguriert sein, damit das Gerät fortwährend funktionieren kann. Dieser Schritt erfolgt auf dem IoT Edge-Gerät während der anfänglichen Geräteeinrichtung.

Moby-Daemon

Da Moby auf Docker basiert, finden Sie in der Docker-Dokumentation Informationen, wie der Moby-Daemon mit Umgebungsvariablen konfiguriert wird. Die meisten Containerregistrierungen (einschließlich DockerHub und Azure Container Registry-Instanzen) unterstützen HTTPS-Anforderungen, daher sollten Sie den Parameter HTTPS_PROXY festlegen. Wenn Sie Images aus einer Registrierung abrufen, die Transport Layer Security (TLS) nicht unterstützt, sollten Sie den Parameter HTTP_PROXY festlegen.

Wählen Sie den Artikel aus, der für Ihr IoT Edge-Gerätebetriebssystem gilt:

Konfigurieren des Docker-Daemons unter Linux Der Moby-Daemon auf Linux-Geräten behält den Namen „Docker“.
Konfigurieren des Docker-Daemons unter Windows Der Moby-Daemon auf Windows-Geräten wird als „iotedge-moby“ bezeichnet. Die Namen sind verschieden, da es möglich ist, Docker Desktop und Moby gleichzeitig auf einem Windows-Gerät auszuführen.

IoT Edge-Daemon

Der IoT Edge-Daemon ähnelt dem Moby-Daemon. Verwenden Sie je nach Betriebssystem die folgenden Schritte, um eine Umgebungsvariable für den Dienst festzulegen.

Der IoT Edge-Daemon verwendet immer HTTPS, um Anforderungen an IoT Hub zu senden.

Linux

Öffnen Sie einen Editor im Terminal, um den IoT Edge-Daemon zu konfigurieren.

sudo systemctl edit aziot-edged

Geben Sie den folgenden Text ein, und ersetzen Sie dabei <proxy URL> durch die Adresse und den Port Ihres Proxyservers. Wählen Sie dann „Speichern“ und „Beenden“ aus.

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

Ab Version 1.2 verwendet IoT Edge den IoT-Identitätsdienst zur Durchführung der Gerätebereitstellung mit IoT Hub oder dem IoT Hub-Gerätebereitstellungsdienst (IoT Hub Device Provisioning Service). Öffnen Sie einen Editor im Terminal, um den IoT-Daemon für den Identitätsdienst-zu konfigurieren.

sudo systemctl edit aziot-identityd

Geben Sie den folgenden Text ein, und ersetzen Sie dabei <proxy URL> durch die Adresse und den Port Ihres Proxyservers. Wählen Sie dann „Speichern“ und „Beenden“ aus.

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

Aktualisieren Sie den Dienst-Manager, um die neuen Konfigurationen zu übernehmen.

sudo systemctl daemon-reload

Starten Sie die IoT Edge-Systemdienste neu, damit die Änderungen an beiden Daemons wirksam werden.

sudo iotedge system restart

Überprüfen Sie, ob die Umgebungsvariablen und die neue Konfiguration vorhanden sind.

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

Windows mit IoT Edge für Linux unter Windows

Melden Sie sich auf der IoT Edge für Linux unter Windows-VM an:

Connect-EflowVm

Führen Sie dieselben Schritte wie im Linux-Abschnitt dieses Artikels aus, um den IoT Edge-Daemon zu konfigurieren.

Windows mit Windows-Containern

Öffnen Sie ein PowerShell-Fenster als Administrator, und führen Sie den folgenden Befehl zum Bearbeiten der Registrierung mit der neuen Umgebungsvariable aus. Ersetzen Sie <proxy URL> durch die Adresse und den Port Ihres Proxyservers.

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

Starten Sie IoT Edge neu, damit die Änderungen wirksam werden.

Restart-Service iotedge

Konfigurieren des IoT Edge-Agent

Der IoT Edge-Agent ist das erste Modul, das auf einem IoT Edge-Gerät gestartet wird. Dieses Modul wird zum ersten Mal basierend auf den Informationen in der IoT Edge-Konfigurationsdatei gestartet. Der IoT Edge-Agent stellt dann eine Verbindung mit IoT Hub her, um Bereitstellungsmanifeste abzurufen. Das Manifest deklariert, welche weiteren Module das Gerät bereitstellen soll.

Dieser Schritt erfolgt einmalig auf dem IoT Edge-Gerät während der anfänglichen Geräteeinrichtung.

Öffnen Sie auf Ihrem IoT Edge-Gerät die Konfigurationsdatei /etc/aziot/config.toml. Sie benötigen Administratorrechte, um auf die Konfigurationsdatei zuzugreifen. Auf Linux-Systemen verwenden Sie den Befehl sudo, bevor Sie die Datei in Ihrem bevorzugten Text-Editor öffnen.
Suchen Sie in der Konfigurationsdatei den Abschnitt [agent] mit allen Konfigurationsinformationen für das edgeAgent-Modul, das beim Start verwendet werden soll. Vergewissern Sie sich, dass der Abschnitt [agent] keine Kommentare enthält. Wenn der Abschnitt [agent] fehlt, fügen Sie ihn in der Datei config.toml hinzu. Die IoT Edge-Agentdefinition enthält einen [agent.env]-Unterabschnitt, in dem Sie Umgebungsvariablen hinzufügen können.

Fügen Sie im Abschnitt mit den Umgebungsvariablen den Parameter https_proxy hinzu, und legen Sie Ihre Proxy-URL als Wert fest.

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

Die IoT Edge-Runtime verwendet standardmäßig AMQP für die Kommunikation mit IoT Hub. Einige Proxyserver blockieren AMQP-Ports. Wenn dies der Fall ist, müssen Sie „edgeAgent“ auch so konfigurieren, dass AMQP über WebSocket verwendet wird. Heben Sie die Auskommentierung des Parameters UpstreamProtocol auf.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

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

Fügen Sie im Abschnitt mit den Umgebungsvariablen den Parameter https_proxy hinzu, und legen Sie Ihre Proxy-URL als Wert fest.

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

Die IoT Edge-Runtime verwendet standardmäßig AMQP für die Kommunikation mit IoT Hub. Einige Proxyserver blockieren AMQP-Ports. Wenn dies der Fall ist, müssen Sie „edgeAgent“ auch so konfigurieren, dass AMQP über WebSocket verwendet wird. Heben Sie die Auskommentierung des Parameters UpstreamProtocol auf.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
Speichern Sie die Änderungen, und schließen Sie den Editor. Wenden Sie Ihre neuesten Änderungen an.
```
sudo iotedge config apply
```
Stellen Sie mithilfe von docker inspect edgeAgent im Abschnitt Env sicher, dass Ihre Proxyeinstellungen weitergegeben werden. Andernfalls müssen Sie den Container neu erstellen.
```
sudo docker rm -f edgeAgent
```
Die IoT Edge-Runtime sollte edgeAgent innerhalb einer Minute neu erstellen. Wenn der Container edgeAgent wieder ausgeführt wird, verwenden Sie den Befehl docker inspect edgeAgent, um zu überprüfen, ob die Proxyeinstellungen mit der Konfigurationsdatei übereinstimmen.

Konfigurieren von Bereitstellungsmanifesten

Nachdem Ihr IoT Edge-Gerät für die Verwendung Ihres Proxyservers konfiguriert wurde, deklarieren Sie die Umgebungsvariable „HTTPS_PROXY“ auch in allen zukünftigen Bereitstellungsmanifesten. Sie können Bereitstellungsmanifeste entweder mit dem Azure-Portal-Assistenten bearbeiten, oder indem Sie eine JSON-Bereitstellungsmanifestdatei bearbeiten.

Konfigurieren Sie die beiden Runtimemodule („edgeAgent“ und „edgeHub“) immer so, dass sie über den Proxyserver kommunizieren, damit sie eine Verbindung mit IoT Hub aufrechterhalten können. Wenn Sie die Proxyinformationen aus dem edgeAgent-Modul entfernen, können Sie die Verbindung nur durch Bearbeiten der Konfigurationsdatei auf dem Gerät wiederherstellen, wie im vorhergehenden Abschnitt beschrieben wird.

Zusätzlich zu den Modulen „edgeAgent“ und „edgeHub“ benötigen andere Module möglicherweise die Proxykonfiguration. Für Module, die neben dem IoT-Hub Zugriff auf Azure-Ressourcen wie Blob Storage erfordern, muss in der Bereitstellungsmanifestdatei die HTTPS_PROXY-Variable angegeben sein.

Das folgende Verfahren gilt für die gesamte Lebensdauer des IoT Edge-Geräts.

Azure-Portal

Wenn Sie den Assistenten Module festlegen zum Erstellen von Bereitstellungen für IoT Edge-Geräte verwenden, verfügt jedes Modul über einen Abschnitt Umgebungsvariablen, in dem Sie Proxyserververbindungen konfigurieren können.

Wählen Sie zum Konfigurieren der IoT Edge-Agent- und der IoT Edge-Hubmodule Laufzeiteinstellungen im ersten Schritt des Assistenten aus.

Screenshot der Konfiguration erweiterter Einstellungen für die Edge-Runtime

Fügen Sie die Umgebungsvariable https_proxy den Definitionen der Runtimeeinstellungen für IoT Edge-Agent und IoT Edge-Hub-Modul hinzu. Wenn Sie die Umgebungsvariable UpstreamProtocol in die Konfigurationsdatei auf Ihrem IoT Edge-Gerät eingefügt haben, fügen Sie sie auch der Definition des IoT Edge-Agentmoduls hinzu.

Alle anderen Module, die Sie einem Bereitstellungsmanifest hinzufügen, folgen dem gleichen Muster. Wählen Sie Übernehmen aus, um die Änderungen zu speichern.

JSON-Bereitstellungsmanifestdateien

Wenn Sie Bereitstellungen für IoT Edge-Geräte mithilfe von Vorlagen in Visual Studio Code oder durch das manuelle Erstellen von JSON-Dateien erstellen, können Sie die Umgebungsvariablen direkt jeder Moduldefinition hinzufügen. Wenn Sie sie nicht über das Azure-Portal hinzugefügt haben, fügen Sie sie hier Ihrer JSON-Manifestdatei hinzu. Ersetzen Sie <proxy URL> durch Ihren eigenen Wert.

Verwenden Sie das folgende JSON-Format:

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

Mit den Umgebungsvariablen sollte Ihre Moduldefinition wie das folgende edgeHub-Beispiel aussehen:

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

Wenn Sie die Umgebungsvariable UpstreamProtocol in die Datei „confige.yaml“ auf Ihrem IoT Edge-Gerät eingefügt haben, fügen Sie sie auch der IoT Edge-Agent-Moduldefinition hinzu.

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

Arbeiten mit Proxys für Datenverkehrsüberprüfung

Einige Proxys wie Zscaler können TLS-verschlüsselten Datenverkehr überprüfen. Während der Überprüfung des TLS-Datenverkehrs ist das vom Proxy zurückgegebene Zertifikat nicht das Zertifikat vom Zielserver, sondern das Zertifikat, das vom eigenen Stammzertifikat des Proxys signiert wurde. Standardmäßig ist das Zertifikat dieses Proxys für IoT Edge-Module (einschließlich edgeAgent und edgeHub) nicht vertrauenswürdig, und der TLS-Handshake schlägt fehl.

Um den fehlerhaften Handshake zu beheben, konfigurieren Sie sowohl das Betriebssystem als auch die IoT Edge-Module anhand der folgenden Schritte so, dass das Stammzertifikat des Proxys als vertrauenswürdig gilt.

Konfigurieren Sie das Proxyzertifikat im vertrauenswürdigen Stammzertifikatspeicher Ihres Hostbetriebssystems. Weitere Informationen zum Installieren eines Stammzertifikats finden Sie unter Installieren der Stammzertifizierungsstelle im Zertifikatspeicher des Betriebssystems.
Konfigurieren Sie Ihr IoT Edge-Gerät für die Kommunikation über einen Proxyserver, indem Sie auf das Zertifikat im Vertrauenspaket verweisen. Weitere Informationen zum Konfigurieren des Vertrauenspakets finden Sie unter Verwalten einer vertrauenswürdigen Stammzertifizierungsstelle (Vertrauenspaket).

Wenn Sie die Unterstützung des Proxys für Datenverkehrsüberprüfung bei Containern konfigurieren möchten, die nicht von IoT Edge verwaltet werden, wenden Sie sich an Ihren Proxyanbieter.

Vollqualifizierte Domänennamen (Fully Qualified Domain Names, FQDNs) von Zielen, mit denen IoT Edge kommuniziert

Wenn Ihr Proxy über eine Firewall verfügt, bei der alle FQDNs für die Internetkonnektivität auf eine Positivliste gesetzt werden müssen, überprüfen Sie die Liste unter Zulassen von Verbindungen von IoT Edge-Geräten, um zu bestimmen, welche FQDNs hinzugefügt werden sollen.

Nächste Schritte

Erfahren Sie mehr über die Rollen der IoT Edge-Runtime.

Behandeln Sie Installations- und Konfigurationsfehler mit Häufig auftretende Probleme und Lösungen für Azure IoT Edge.

Freigeben über