Konfigurera API-proxymodulen för ditt gatewayhierarkiscenario

Artikel
05/02/2024

Gäller för: IoT Edge 1.5 IoT Edge 1.4

Viktigt!

IoT Edge 1.5 LTS och IoT Edge 1.4 LTS stöds. IoT Edge 1.4 LTS upphör den 12 november 2024. Om du har en tidigare version läser du Uppdatera IoT Edge.

Den här artikeln går igenom konfigurationsalternativen för API-proxymodulen, så att du kan anpassa modulen för att stödja dina krav på gatewayhierarki.

API-proxymodulen förenklar kommunikationen för IoT Edge-enheter när flera tjänster distribueras som alla stöder HTTPS-protokoll och binder till port 443. Detta är särskilt relevant i hierarkiska distributioner av IoT Edge-enheter i ISA-95-baserade nätverksisolerade arkitekturer som de som beskrivs i Nätverk isolerar underordnade enheter eftersom klienterna på de underordnade enheterna inte kan ansluta direkt till molnet.

Om du till exempel vill tillåta att underordnade IoT Edge-enheter hämtar Docker-avbildningar måste du distribuera en Docker-registermodul. För att tillåta uppladdning av blobar måste du distribuera en Azure Blob Storage-modul på samma IoT Edge-enhet. Båda dessa tjänster använder HTTPS för kommunikation. API-proxyn aktiverar sådana distributioner på en IoT Edge-enhet. I stället för varje tjänst binder API-proxymodulen till port 443 på värdenheten och dirigerar begäran till rätt tjänstmodul som körs på enheten enligt användarkonfigurerbara regler. De enskilda tjänsterna ansvarar fortfarande för att hantera begäranden, inklusive att autentisera och auktorisera klienterna.

Utan API-proxyn skulle varje tjänstmodul behöva binda till en separat port på värdenheten, vilket kräver en omständlig och felbenägen konfigurationsändring på varje underordnad enhet som ansluter till den överordnade IoT Edge-enheten.

Kommentar

En nedströmsenhet genererar data direkt till Internet eller till gatewayenheter (IoT Edge-aktiverade eller inte). En underordnad enhet kan vara en underordnad enhet eller en gatewayenhet i en kapslad topologi.

Distribuera proxymodulen

API-proxymodulen är tillgänglig från Microsoft Container Registry (MCR): mcr.microsoft.com/azureiotedge-api-proxy:1.1.

Du kan också distribuera API-proxymodulen direkt från Azure Marketplace: IoT Edge API Proxy.

Förstå proxymodulen

API-proxymodulen använder en omvänd nginx-proxy för att dirigera data genom nätverkslager. En proxy är inbäddad i modulen, vilket innebär att modulbilden måste ha stöd för proxykonfigurationen. Om proxyn till exempel lyssnar på en viss port måste modulen ha porten öppen.

Proxyn börjar med en standardkonfigurationsfil som är inbäddad i modulen. Du kan skicka en ny konfiguration till modulen från molnet med hjälp av dess modultvilling. Dessutom kan du använda miljövariabler för att aktivera eller inaktivera konfigurationsinställningar vid distributionstillfället.

Den här artikeln fokuserar först på standardkonfigurationsfilen och hur du använder miljövariabler för att aktivera dess inställningar. Sedan diskuterar vi att anpassa konfigurationsfilen i slutet.

Standardkonfiguration

API-proxymodulen levereras med en standardkonfiguration som stöder vanliga scenarier och möjliggör anpassning. Du kan styra standardkonfigurationen via modulens miljövariabler.

För närvarande omfattar standardmiljövariablerna:

Miljövariabel	beskrivning
`PROXY_CONFIG_ENV_VAR_LIST`	Visa en lista över alla variabler som du tänker uppdatera i en kommaavgränsad lista. Det här steget förhindrar att fel konfigurationsinställningar ändras av misstag.
`NGINX_DEFAULT_TLS`	Anger listan över TLS-protokoll som ska aktiveras. Se NGINX ssl_protocols. Standardvärdet är "TLSv1.2".
`NGINX_DEFAULT_PORT`	Ändrar den port som nginx-proxyn lyssnar på. Om du uppdaterar den här miljövariabeln måste du exponera porten i modulen dockerfile och deklarera portbindningen i distributionsmanifestet. Mer information finns i Exponera proxyport. Standardvärdet är 443. När den distribueras från Azure Marketplace uppdateras standardporten till 8000 för att förhindra konflikter med edgeHub-modulen. Mer information finns i Minimera öppna portar.
`DOCKER_REQUEST_ROUTE_ADDRESS`	Adress för att dirigera Docker-begäranden. Ändra den här variabeln på den översta lagerenheten så att den pekar på registermodulen. Standardvärdet är det överordnade värdnamnet.
`BLOB_UPLOAD_ROUTE_ADDRESS`	Adress för att dirigera blobregisterbegäranden. Ändra den här variabeln på den översta lagerenheten så att den pekar på bloblagringsmodulen. Standardvärdet är det överordnade värdnamnet.

Minimera öppna portar

För att minimera antalet öppna portar bör API-proxymodulen vidarebefordra all HTTPS-trafik (port 443), inklusive trafik som riktar sig mot edgeHub-modulen. API-proxymodulen konfigureras som standard för att dirigera om all edgeHub-trafik på port 443.

Använd följande steg för att konfigurera distributionen för att minimera öppna portar:

Uppdatera inställningarna för edgeHub-modulen så att de inte binder på port 443, annars blir det portbindningskonflikter. Som standard binder edgeHub-modulen på portarna 443, 5671 och 8883. Ta bort port 443-bindningen och låt de andra två vara kvar:
```
{
  "HostConfig": {
    "PortBindings": {
      "5671/tcp": [
        {
          "HostPort": "5671"
        }
      ],
      "8883/tcp": [
        {
          "HostPort": "8883"
        }
      ]
    }
  }
}
```
Konfigurera API-proxymodulen så att den binder på port 443.
1. Ange värdet för miljövariabeln NGINX_DEFAULT_PORT till 443.
2. Uppdatera alternativen för att skapa containern för att binda på port 443.
```
{
  "HostConfig": {
    "PortBindings": {
      "443/tcp": [
        {
          "HostPort": "443"
        }
      ]
    }
  }
}
```

Om du inte behöver minimera öppna portar kan du låta edgeHub-modulen använda port 443 och konfigurera API-proxymodulen så att den lyssnar på en annan port. API-proxymodulen kan till exempel lyssna på port 8000 genom att 8000 ange värdet för NGINX_DEFAULT_PORT miljövariabel till och skapa en portbindning för port 8000.

Aktivera nedladdning av containeravbildning

Ett vanligt användningsfall för API-proxymodulen är att aktivera IoT Edge-enheter i lägre lager för att hämta containeravbildningar. Det här scenariot använder Docker-registermodulen för att hämta containeravbildningar från molnet och cachelagrar dem på det översta lagret. API-proxyn vidarebefordrar alla HTTPS-begäranden om att ladda ned en containeravbildning från de lägre skikten som ska hanteras av registermodulen i det översta lagret.

Det här scenariot kräver att underordnade IoT Edge-enheter pekar på domännamnet $upstream följt av portnumret för API Proxy-modulen i stället för containerregistret för en avbildning. Exempel: $upstream:8000/azureiotedge-api-proxy:1.1.

Det här användningsfallet visas i självstudien Skapa en hierarki med IoT Edge-enheter med hjälp av gatewayer.

Konfigurera följande moduler på det översta lagret:

En Docker-registermodul
- Konfigurera modulen med ett minnesvärt namn som registret och exponera en port i modulen för att ta emot begäranden.
- Konfigurera modulen så att den mappas till containerregistret.

En API-proxymodul

Konfigurera följande miljövariabler:

Name	Värde
`DOCKER_REQUEST_ROUTE_ADDRESS`	Namnet på registermodulen och den öppna porten. Exempel: `registry:5000`
`NGINX_DEFAULT_PORT`	Porten som nginx-proxyn lyssnar på efter begäranden från underordnade enheter. Exempel: `8000`

Konfigurera följande createOptions:

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

Konfigurera följande modul på ett lägre lager för det här scenariot:

API-proxymodul. API-proxymodulen krävs på alla enheter på lägre nivå förutom enheten på det nedre lagret.
- Konfigurera följande miljövariabler:
  
  Name Värde
  
  NGINX_DEFAULT_PORT Porten som nginx-proxyn lyssnar på efter begäranden från underordnade enheter. Exempel: 8000
- Konfigurera följande createOptions:
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

Name	Värde
`NGINX_DEFAULT_PORT`	Porten som nginx-proxyn lyssnar på efter begäranden från underordnade enheter. Exempel: `8000`

Exponera proxyport

Port 8000 exponeras som standard från docker-avbildningen. Om en annan nginx-proxyport används lägger du till avsnittet ExposedPorts som deklarerar porten i distributionsmanifestet. Om du till exempel ändrar nginx-proxyporten till 8001 lägger du till följande i distributionsmanifestet:

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

Aktivera blobuppladdning

Ett annat användningsfall för API-proxymodulen är att aktivera IoT Edge-enheter i lägre lager för att ladda upp blobar. I det här användningsfallet kan du felsöka funktioner på enheter på lägre nivå som att ladda upp modulloggar eller ladda upp supportpaketet.

Det här scenariot använder Azure Blob Storage på IoT Edge-modulen på det översta lagret för att hantera skapande och uppladdning av blobar. I ett kapslat scenario stöds upp till fem lager. Azure Blob Storage på IoT Edge-modulen krävs på den översta lagerenheten och valfritt för enheter med lägre lager. En exempeldistribution med flera lager finns i Azure IoT Edge for Industrial IoT-exemplet .

Konfigurera följande moduler på det översta lagret:

En Azure Blob Storage på IoT Edge-modul.

En API-proxymodul

Konfigurera följande miljövariabler:

Name	Värde
`BLOB_UPLOAD_ROUTE_ADDRESS`	Namnet på bloblagringsmodulen och den öppna porten. Exempel: `azureblobstorageoniotedge:11002`
`NGINX_DEFAULT_PORT`	Porten som nginx-proxyn lyssnar på efter begäranden från underordnade enheter. Exempel: `8000`

Konfigurera följande createOptions:

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

Konfigurera följande modul på ett lägre lager för det här scenariot:

En API-proxymodul
- Konfigurera följande miljövariabler:
  
  Name Värde
  
  NGINX_DEFAULT_PORT Porten som nginx-proxyn lyssnar på efter begäranden från underordnade enheter. Exempel: 8000
- Konfigurera följande createOptions:
```
{
   "HostConfig": {
      "PortBindings": {
         "8000/tcp": [
            {
               "HostPort": "8000"
            }
         ]
      }
   }
}
```

Name	Värde
`NGINX_DEFAULT_PORT`	Porten som nginx-proxyn lyssnar på efter begäranden från underordnade enheter. Exempel: `8000`

Använd följande steg för att ladda upp supportpaketet eller loggfilen till bloblagringsmodulen som finns på det översta lagret:

Skapa en blobcontainer med antingen Azure Storage Explorer eller REST-API:er. Mer information finns i Lagra data vid gränsen med Azure Blob Storage på IoT Edge.
Begär en logg- eller supportpaketuppladdning enligt stegen i Hämta loggar från IoT Edge-distributioner, men använd domännamnet $upstream och den öppna proxyporten i stället för bloblagringsmoduladressen. Till exempel:
```
{
   "schemaVersion": "1.0",
   "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
   "since": "2d",
   "until": "1d",
   "edgeRuntimeOnly": false
}
```

Redigera proxykonfigurationen

En standardkonfigurationsfil är inbäddad i API-proxymodulen, men du kan skicka en ny konfiguration till modulen via molnet med hjälp av modultvillingen.

När du skriver en egen konfiguration kan du fortfarande använda miljön för att justera inställningarna per distribution. Använd följande syntax:

Använd ${MY_ENVIRONMENT_VARIABLE} för att hämta värdet för en miljövariabel.

Använd villkorsstyrda instruktioner för att aktivera eller inaktivera inställningar baserat på värdet för en miljövariabel:

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

När API-proxymodulen parsar en proxykonfiguration ersätter den först alla miljövariabler som anges i PROXY_CONFIG_ENV_VAR_LIST med de angivna värdena med ersättning. Sedan ersätts allt mellan ett #if_tag par och #endif_tag ett par. Modulen tillhandahåller sedan den parsade konfigurationen till den omvända nginx-proxyn.

Om du vill uppdatera proxykonfigurationen dynamiskt använder du följande steg:

Skriv konfigurationsfilen. Du kan använda den här standardmallen som referens: nginx_default_config.conf
Kopiera texten i konfigurationsfilen och konvertera den till base64.
Klistra in den kodade konfigurationsfilen som värdet för den proxy_config önskade egenskapen i modultvillingen.

Nästa steg

Använd API-proxymodulen för att Anslut en nedströms IoT Edge-enhet till en Azure IoT Edge-gateway.

Dela via