Konfigurieren des API-Proxymoduls für Ihr Gatewayhierarchieszenario (Vorschau)

  • Artikel

Gilt für:IoT Edge 1.4 checkmark IoT Edge 1.4

Wichtig

IoT Edge Version 1.4 wird unterstützt. Wenn Sie ein früheres Release verwenden, finden Sie weitere Informationen unter Aktualisieren von IoT Edge.

In diesem Artikel werden die Konfigurationsoptionen für das API-Proxymodul beschrieben, damit Sie es zur Unterstützung der Anforderungen Ihrer Gatewayhierarchie anpassen können.

Das API-Proxymodul vereinfacht die Kommunikation für IoT Edge-Geräte, wenn mehrere Dienste bereitgestellt werden, die alle das HTTPS-Protokoll unterstützen und an Port 443 gebunden werden. Dies ist besonders relevant für hierarchische Bereitstellungen von IoT Edge-Geräten in ISA-95-basierten netzwerkisoliert Architekturen wie die in Network isolate downstream devices beschriebenen, da die Clients auf den downstream-Geräten keine direkte Verbindung mit der Cloud herstellen können.

Um z. B. nachgeschaltete IoT Edge-Geräte das Abrufen von Docker-Images zu ermöglichen, muss ein Docker-Registrierungsmodul bereitgestellt werden. Um das Hochladen von Blobs zu ermöglichen, muss ein Azure Blob Storage-Modul auf demselben IoT Edge-Gerät bereitgestellt werden. Diese beiden Dienste verwenden HTTPS für die Kommunikation. Der API-Proxy aktiviert solche Bereitstellungen auf einem IoT Edge-Gerät. Statt jedes Diensts wird das API-Proxymodul an Port 443 auf dem Hostgerät gebunden und leitet die Anforderung – entsprechend vom Benutzer konfigurierbaren Regeln – an das richtige Dienstmodul weiter, das auf diesem Gerät ausgeführt wird. Die einzelnen Dienste sind weiterhin für die Verarbeitung der Anforderungen zuständig, einschließlich Authentifizierung und Autorisierung der Clients.

Ohne den API-Proxy müsste jedes Dienstmodul an einen separaten Port auf dem Hostgerät gebunden werden. Dies erfordert eine mühsame und fehleranfällige Konfigurationsänderung auf jedem untergeordneten Gerät, das eine Verbindung mit dem übergeordneten IoT Edge-Gerät herstellt.

Hinweis

Ein nachgeschaltetes Gerät gibt Daten direkt an das Internet oder an Gatewaygeräte (IoT Edge-fähig oder nicht) aus. Ein untergeordnetes Gerät kann ein nachgeschaltetes Gerät oder ein Gatewaygerät in einer geschachtelten Topologie sein.

Bereitstellen des Proxymoduls

Das API-Proxymodul ist über Microsoft Container Registry (MCR) verfügbar: mcr.microsoft.com/azureiotedge-api-proxy:1.1.

Sie können das API-Proxymodul auch direkt aus dem Azure Marketplace bereitstellen: IoT Edge-API-Proxy.

Grundlegendes zum Proxymodul

Das API-Proxymodul nutzt einen nginx-Reverseproxy zum Weiterleiten von Daten über Netzwerkebenen. Ein Proxy ist in das Modul eingebettet, was bedeutet, dass das Modulimage die Proxykonfiguration unterstützen muss. Wenn der Proxy z. B. an einem bestimmten Port lauscht, muss das Modul diesen Port geöffnet haben.

Der Proxy beginnt mit einer in das Modul eingebetteten Standardkonfigurationsdatei. Sie können mithilfe des Modulzwillings über die Cloud eine neue Konfiguration an das Modul übergeben. Darüber hinaus können Sie Umgebungsvariablen verwenden, um Konfigurationseinstellungen zum Zeitpunkt der Bereitstellung zu aktivieren oder zu deaktivieren.

In diesem Artikel konzentrieren wir uns zunächst auf die Standardkonfigurationsdatei und auf die Verwendung von Umgebungsvariablen zum Aktivieren der Einstellungen. Und danach erläutern wir, wie die Konfigurationsdatei angepasst werden kann.

Standardkonfiguration

Das API-Proxymodul wird mit einer Standardkonfiguration bereitgestellt, die gängige Szenarien unterstützt und angepasst werden kann. Sie können die Standardkonfiguration über die Umgebungsvariablen des Moduls steuern.

Derzeit umfassen die Standardumgebungsvariablen Folgendes:

Umgebungsvariable Beschreibung
PROXY_CONFIG_ENV_VAR_LIST Listet alle Variablen auf, die Sie in einer durch Trennzeichen getrennten Liste aktualisieren möchten. Durch diesen Schritt wird verhindert, dass versehentlich die falschen Konfigurationseinstellungen geändert werden.
NGINX_DEFAULT_TLS Gibt die Liste der zu aktivierenden TLS-Protokolle an. Siehe ssl_protocols von NGINX.

Stnadardwert ist „TLSv1.2“.
NGINX_DEFAULT_PORT Ändert den Port, an dem der nginx-Proxy lauscht. Wenn Sie diese Umgebungsvariable aktualisieren, müssen Sie den Port in der Modul dockerfile verfügbar machen und die Portbindung im Bereitstellungsmanifest deklarieren. Weitere Informationen finden Sie unter Verfügbarmachen des Proxyports.

Der Standardport ist 443.

Wenn die Bereitstellung über Azure Marketplace erfolgt, wird der Standardport auf 8000 aktualisiert, um Konflikte mit dem edgeHub-Modul zu vermeiden. Weitere Informationen finden Sie unter Minimieren offener Ports.
DOCKER_REQUEST_ROUTE_ADDRESS Adresse zum Weiterleiten von Docker-Anforderungen. Ändern Sie diese Variable auf dem Gerät der obersten Ebene so, dass sie auf das Registrierungsmodul verweist.

Standardmäßig wird der übergeordnete Hostname verwendet.
BLOB_UPLOAD_ROUTE_ADDRESS Adresse zum Weiterleiten von Blobregistrierungsanforderungen. Ändern Sie diese Variable auf dem Gerät der obersten Ebene so, dass sie auf das Blobspeichermodul verweist.

Standardmäßig wird der übergeordnete Hostname verwendet.

Minimieren offener Ports

Um die Anzahl offener Ports zu minimieren, sollte das API-Proxymodul den gesamten HTTPS-Datenverkehr (Port 443) einschließlich des Datenverkehrs für das edgeHub-Modul weiterleiten. Das API-Proxymodul ist standardmäßig so konfiguriert, dass der gesamte edgeHub-Datenverkehr an Port 443 umgeleitet wird.

Führen Sie die folgenden Schritte aus, um Ihre Bereitstellung so zu konfigurieren, dass die Anzahl offener Ports minimiert wird:

  1. Aktualisieren Sie die Einstellungen des edgeHub-Moduls so, dass keine Bindung an Port 443 erfolgt. Andernfalls treten Portbindungskonflikte auf. Standardmäßig bindet das edgeHub-Modul an die Ports 443, 5671 und 8883. Löschen Sie die Bindung an Port 443, und lassen Sie die anderen beiden bestehen:

    {
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}

  2. Konfigurieren Sie das API-Proxymodul für die Bindung an Port 443.

    1. Legen Sie den Wert der Umgebungsvariable NGINX_DEFAULT_PORT auf 443 fest.

    2. Aktualisieren Sie die Optionen für die Containererstellung so, dass die Bindung an Port 443 erfolgt.

      {
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}

Wenn Sie die Anzahl offener Ports nicht minimieren müssen, können Sie zulassen, dass das edgeHub-Modul Port 443 verwendet, und konfigurieren Sie das API-Proxymodul so, dass es an einem anderen Port lauscht. Beispielsweise kann das API-Proxymodul an Port 8000 lauschen, indem der Wert der Umgebungsvariable NGINX_DEFAULT_PORT auf 8000 festgelegt und eine Portbindung für Port 8000 erstellt wird.

Ermöglichen des Herunterladens von Containerimages

Ein häufiger Anwendungsfall für das API-Proxymodul besteht darin, IoT Edge-Geräten niedrigerer Ebenen das Pullen von Containerimages zu ermöglichen. In diesem Szenario wird das Docker-Registrierungsmodul verwendet, um Containerimages aus der Cloud abzurufen und auf der obersten Ebene zwischenzuspeichern. Der API-Proxy leitet alle HTTPS-Anforderungen zum Herunterladen eines Containerimages aus den unteren Ebenen weiter, um durch das Registrierungsmodul auf der obersten Ebene bedient zu werden.

Dieses Szenario erfordert, dass nachgeschaltete IoT Edge-Geräte auf den Domänennamen $upstream gefolgt von der Portnummer des API-Proxymoduls anstelle der Containerregistrierung eines Images verweisen. Beispiel: $upstream:8000/azureiotedge-api-proxy:1.1

Dieser Anwendungsfall wird im Tutorial Erstellen einer Hierarchie von IoT Edge-Geräten mit Gateways veranschaulicht.

Konfigurieren Sie die folgenden Module auf der obersten Ebene:

  • Ein Docker-Registrierungsmodul
    • Konfigurieren Sie das Modul mit einem einprägsamen Namen wie Registrierung, und machen Sie für den Empfang von Anforderungen einen Port im Modul verfügbar.
    • Konfigurieren Sie das Modul für die Zuordnung zu Ihrer Containerregistrierung.
  • Ein API-Proxymodul

    • Konfigurieren Sie die folgenden Umgebungsvariablen:

      Name Wert
      DOCKER_REQUEST_ROUTE_ADDRESS Der Name des Registrierungsmoduls und der offene Port. Beispiel: registry:5000.
      NGINX_DEFAULT_PORT Der Port, an dem der nginx-Proxy nach Anforderungen von nachgeschalteten Geräten lauscht. Beispiel: 8000.

    • Konfigurieren Sie die folgenden Erstellungsoptionen:

      {
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Konfigurieren Sie das folgende Modul auf allen unteren Ebenen für dieses Szenario:

  • API-Proxymodul. Das API-Proxymodul ist auf allen Geräten mit niedrigerer Ebene erforderlich, mit Ausnahme des Gerätes der unteren Ebene.

    • Konfigurieren Sie die folgenden Umgebungsvariablen:

      Name Wert
      NGINX_DEFAULT_PORT Der Port, an dem der nginx-Proxy nach Anforderungen von nachgeschalteten Geräten lauscht. Beispiel: 8000.

    • Konfigurieren Sie die folgenden Erstellungsoptionen:

      {
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Verfügbarmachen des Proxyports

Port 8000 wird standardmäßig über das Docker-Image verfügbar gemacht. Wenn ein anderer nginx-Proxyport verwendet wird, fügen Sie den Abschnitt "ExposedPorts " hinzu, der den Port im Bereitstellungsmanifest deklariert. Wenn Sie beispielsweise den nginx-Proxyport in 8001 ändern, fügen Sie dem Bereitstellungsmanifest Folgendes hinzu:

{
   "ExposedPorts": {
      "8001/tcp": {}
   },
   "HostConfig": {
      "PortBindings": {
            "8001/tcp": [
               {
                  "HostPort": "8001"
               }
            ]
      }
   }
}

Ermöglichen des Hochladens von Blobs

Ein weiterer Anwendungsfall für das API-Proxymodul besteht darin, IoT Edge-Geräten niedrigerer Ebenen das Hochladen von Blobs zu ermöglichen. Dieser Anwendungsfall ermöglicht die Problembehandlung auf Geräten niedrigerer Ebenen, beispielsweise das Hochladen von Modulprotokollen oder das Hochladen des Supportbundles.

In diesem Szenario wird das Modul Azure Blob Storage on IoT Edge auf der obersten Ebene verwendet, um das Erstellen und Hochladen von Blobs zu verarbeiten. In einem geschachtelten Szenario werden bis zu fünf Ebenen unterstützt. Das Azure Blob Storage im IoT Edge-Modul ist auf dem Gerät der obersten Ebene und optional für Geräte mit niedrigerer Ebene erforderlich. Ein Beispiel für eine Mehrschichtbereitstellung finden Sie im Azure IoT Edge for Industrial IoT-Beispiel .

Konfigurieren Sie die folgenden Module auf der obersten Ebene:

  • Ein „Azure Blob Storage on IoT Edge“-Modul.
  • Ein API-Proxymodul

    • Konfigurieren Sie die folgenden Umgebungsvariablen:

      Name Wert
      BLOB_UPLOAD_ROUTE_ADDRESS Der Name des Blob Storage-Moduls und der offene Port. Beispiel: azureblobstorageoniotedge:11002.
      NGINX_DEFAULT_PORT Der Port, an dem der nginx-Proxy nach Anforderungen von nachgeschalteten Geräten lauscht. Beispiel: 8000.

    • Konfigurieren Sie die folgenden Erstellungsoptionen:

      {
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Konfigurieren Sie das folgende Modul auf allen unteren Ebenen für dieses Szenario:

  • Ein API-Proxymodul

    • Konfigurieren Sie die folgenden Umgebungsvariablen:

      Name Wert
      NGINX_DEFAULT_PORT Der Port, an dem der nginx-Proxy nach Anforderungen von nachgeschalteten Geräten lauscht. Beispiel: 8000.

    • Konfigurieren Sie die folgenden Erstellungsoptionen:

      {
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}

Führen Sie die folgenden Schritte aus, um das Supportbundle oder die Protokolldatei in das Blob Storage-Modul auf der obersten Ebene hochzuladen:

  1. Erstellen Sie einen Blobcontainer. Verwenden Sie dazu entweder Azure Storage-Explorer oder die REST-APIs. Weitere Informationen finden Sie unter Speichern von Daten im Edgebereich mit Azure Blob Storage in IoT Edge.

  2. Senden Sie eine Anforderung zum Hochladen eines Protokolls oder Supportbundles gemäß den Schritten im Artikel Abrufen von Protokollen aus IoT Edge-Bereitstellungen, aber verwenden Sie dabei den Domänennamen $upstream und den offenen Proxyport anstelle der Adresse des Blob Storage-Moduls. Beispiel:

    {
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}

Bearbeiten der Proxykonfiguration

In das API-Proxymodul ist eine Standardkonfigurationsdatei eingebettet, Sie können jedoch mithilfe des Modulzwillings über die Cloud eine neue Konfiguration an das Modul übergeben.

Wenn Sie Ihre eigene Konfiguration schreiben, können Sie trotzdem Umgebungsvariablen verwenden, um die Einstellungen pro Bereitstellung anzupassen. Verwenden Sie die folgende Syntax:

  • Verwenden Sie ${MY_ENVIRONMENT_VARIABLE}, um den Wert einer Umgebungsvariable abzurufen.

  • Verwenden Sie bedingte Anweisungen, um Einstellungen basierend auf dem Wert einer Umgebungsvariable zu aktivieren oder zu deaktivieren:

    #if_tag ${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 1
#endif_tag ${MY_ENVIRONMENT_VARIABLE}

#if_tag !${MY_ENVIRONMENT_VARIABLE}
     statement to execute if environment variable evaluates to 0
#endif_tag !${MY_ENVIRONMENT_VARIABLE}

Wenn das API-Proxymodul eine Proxykonfiguration analysiert, ersetzt es zuerst alle in der PROXY_CONFIG_ENV_VAR_LIST aufgeführten Umgebungsvariablen durch ihre bereitgestellten Werte mittels Substitution. Dann wird alles zwischen einem #if_tag-#endif_tag-Paar ersetzt. Anschließend stellt das Modul die analysierte Konfiguration für den nginx-Reverseproxy bereit.

Führen Sie die folgenden Schritte aus, um die Proxykonfiguration dynamisch zu aktualisieren:

  1. Schreiben Sie Ihre Konfigurationsdatei. Sie können die folgende Standardvorlage als Referenz verwenden: nginx_default_config.conf

  2. Kopieren Sie den Text der Konfigurationsdatei, und konvertieren Sie ihn in Base64.

  3. Fügen Sie die codierte Konfigurationsdatei als Wert der gewünschten proxy_config-Eigenschaft in den Modulzwilling ein.

    Screenshot that shows how to paste encoded config file as value of proxy_config property.

Nächste Schritte

Verwenden Sie das API-Proxymodul zum Verbinden eines nachgeschalteten IoT Edge-Geräts mit einem Azure IoT Edge-Gateway.