Teilen über


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

Gilt für: yes icon IoT Edge 1.1

Wichtig

IoT Edge 1.1: Datum für das Supportende war der 13. Dezember 2022. Informationen zur Unterstützung für dieses Produkt, diesen Dienst, diese Technologie oder diese API finden Sie in der Microsoft Lifecycle-Richtlinie. Weitere Informationen zum Aktualisieren auf die neueste Version von IoT Edge finden Sie unter Update 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:

  1. 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. Dieselben Verbindungen sind ebenfalls erforderlich, wenn Sie IoT Edge-Runtime aktualisieren.

  2. 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.

  3. 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 dem 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.

  4. 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 durch den Proxyserver mit IoT Hub verbunden ist, 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 die Anweisungen unter Installieren oder Deinstallieren von Azure IoT Edge-Runtime wie gewohnt.

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. Es sind keine zusätzlichen Installations- oder Aktualisierungsschritte erforderlich.

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:

  1. 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>
    
  2. 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 Parameter -ProxyCredential innerhalb von -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. Weitere Informationen zu Windows-Installationsparametern finden Sie unter PowerShell-Skripts für IoT Edge unter Windows.

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:

IoT Edge-Daemon

Der IoT Edge-Daemon wird in ähnlicher Weise wie der Moby-Daemon konfiguriert. 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 iotedge

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 neue Konfiguration für IoT Edge zu übernehmen.

sudo systemctl daemon-reload

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

sudo systemctl restart iotedge

Stellen Sie sicher, dass die Umgebungsvariable erstellt wurde und die neue Konfiguration geladen wurde.

systemctl show --property=Environment iotedge

Windows mit IoT Edge für Linux unter Windows

Melden Sie sich auf dem virtuellen Windows-Computer bei IoT Edge für Linux an:

Connect-EflowVm

Führen Sie dieselben Schritte wie im vorstehenden Linux-Abschnitt 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. Es wird zum ersten Mal basierend auf den Informationen in der IoT Edge-Konfigurationsdatei gestartet. Der IoT Edge-Agent stellt anschließend eine Verbindung mit IoT Hub her, um Bereitstellungsmanifeste abzurufen, die deklarieren, welche weiteren Module auf dem Gerät bereitgestellt werden sollen.

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

  1. Öffnen Sie die Datei „config.yaml“ auf Ihrem IoT Edge-Gerät. In Linux-Systemen befindet sich diese Datei unter /etc/iotedge/config.yaml. In Windows-Systemen befindet sich diese Datei unter C:\ProgramData\iotedge\config.yaml. Die Konfigurationsdatei ist geschützt. Sie benötigen also Administratorrechte, um darauf zuzugreifen. Auf Linux-Systemen verwenden Sie den Befehl sudo, bevor Sie die Datei in Ihrem bevorzugten Text-Editor öffnen. Unter Windows öffnen Sie einen Text-Editor wie Editor als Administrator und öffnen dann die Datei.

  2. Suchen Sie in der Datei „config.yaml“ nach dem Abschnitt Edge Agent module spec. Die IoT Edge-Agent-Definition enthält einen env-Parameter, dem Sie Umgebungsvariablen hinzufügen können.

  3. Entfernen Sie die geschweiften Klammern, die Platzhalter für den env-Parameter darstellen, und fügen Sie die neue Variable in einer neuen Zeile hinzu. Denken Sie daran, dass Einzüge in YAML zwei Leerzeichen sind.

    https_proxy: "<proxy URL>"
    
  4. 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. Fügen Sie eine zweite Umgebungsvariable hinzu.

    UpstreamProtocol: "AmqpWs"
    

    edgeAgent-Definition mit Umgebungsvariablen

  5. Speichern Sie die Änderungen an „config.yaml“, und schließen Sie den Editor. Starten Sie IoT Edge neu, damit die Änderungen wirksam werden.

    • Linux und IoT Edge für Linux unter Windows:

      sudo systemctl restart iotedge
      
    • Windows mit Windows-Containern:

      Restart-Service iotedge
      
  1. 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.4"
    
    [agent.env]
    # "RuntimeLogLevel" = "debug"
    # "UpstreamProtocol" = "AmqpWs"
    "https_proxy" = "<proxy URL>"
    
  2. 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.4"
    
    [agent.env]
    # "RuntimeLogLevel" = "debug"
    "UpstreamProtocol" = "AmqpWs"
    "https_proxy" = "<proxy URL>"
    
  3. Speichern Sie die Änderungen, und schließen Sie den Editor. Wenden Sie Ihre neuesten Änderungen an.

    sudo iotedge config apply
    
  4. Stellen Sie mithilfe von docker inspect edgeAgent im Abschnitt Env sicher, dass Ihre Proxyeinstellungen weitergegeben werden. Wenn nicht, muss der Container neu erstellt werden.

    sudo docker rm -f edgeAgent
    
  5. Die IoT Edge-Runtime sollte edgeAgent innerhalb einer Minute neu erstellen. Wenn der Container edgeAgent wieder ausgeführt wird, verwenden Sie docker inspect edgeAgent, und vergewissern Sie sich, dass die Proxyeinstellungen mit der Konfigurationsdatei übereinstimmen.

Konfigurieren von Bereitstellungsmanifesten

Nachdem Ihr IoT Edge-Gerät für die Verwendung Ihres Proxyservers konfiguriert wurde, müssen Sie die Umgebungsvariable „HTTPS_PROXY“ auch in allen zukünftigen Bereitstellungsmanifesten deklarieren. 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.

Erweiterte Einstellungen für die Edge-Laufzeit konfigurieren

Fügen Sie die Umgebungsvariable https_proxy den Definitionen der IoT Edge-Agent- und IoT Edge-Hub-Module 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.

Festlegen der https_proxy-Umgebungsvariable

Alle anderen Module, die Sie einem Bereitstellungsmanifest hinzufügen, folgen dem gleichen Muster.

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.

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.1",
        "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.

Zur Behebung dieses Problems muss das Stammzertifikat des Proxys sowohl für das Betriebssystem als auch für IoT Edge-Module vertrauenswürdig sein.

  1. 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.

  2. 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.