Konfigurieren des API-Proxymoduls für Ihr Gatewayhierarchieszenario (Vorschau)
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.
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 in hierarchischen Bereitstellungen von IoT Edge-Geräten in ISA-95-basierten, vom Netzwerk isolierten Architekturen wie die in Isolieren von nachgeschalteten Geräten im Netzwerk beschriebenen, weil die Clients auf den nachgeschalteten Geräten keine direkte Verbindung mit der Cloud herstellen können.
Um beispielsweise nachgeschalteten IoT Edge-Geräten das Pullen 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 die Microsoft Container Registry (MCR) verfügbar. Der Image-URI lautet mcr.microsoft.com/azureiotedge-api-proxy:latest. Sie können das Modul über das Azure-Portal oder die Azure-Befehlszeilenschnittstelle bereitstellen.
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 zu aktivierende Liste der 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 Dockerfile-Datei des Moduls 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:
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" } ] } } }Konfigurieren Sie das API-Proxymodul für die Bindung an Port 443.
Legen Sie den Wert der Umgebungsvariable NGINX_DEFAULT_PORT auf
443fest.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_ADDRESSDer Name des Registrierungsmoduls und der offene Port. Beispiel: registry:5000.NGINX_DEFAULT_PORTDer 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 einer niedrigeren Ebene erforderlich, außer auf dem Gerät der untersten Ebene.
Konfigurieren Sie die folgenden Umgebungsvariablen:
Name Wert NGINX_DEFAULT_PORTDer 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, in dem der Port im Bereitstellungsmanifest deklariert wird. 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 niedrigerer Ebenen erforderlich. Ein Beispiel für eine Bereitstellung mit mehreren Ebnen finden Sie im Beispiel Azure IoT Edge für Industrial IoT.
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_ADDRESSDer Name des Blob Storage-Moduls und der offene Port. Beispiel: azureblobstorageoniotedge:11002.NGINX_DEFAULT_PORTDer 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_PORTDer 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:
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.
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
$upstreamund den offenen Proxyport anstelle der Adresse des Blob Storage-Moduls. Zum 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:
Schreiben Sie Ihre Konfigurationsdatei. Sie können die folgende Standardvorlage als Referenz verwenden: nginx_default_config.conf
Kopieren Sie den Text der Konfigurationsdatei, und konvertieren Sie ihn in Base64.
Fügen Sie die codierte Konfigurationsdatei als Wert der gewünschten
proxy_config-Eigenschaft in den Modulzwilling ein.
Nächste Schritte
Verwenden Sie das API-Proxymodul zum Verbinden eines nachgeschalteten IoT Edge-Geräts mit einem Azure IoT Edge-Gateway.