Share via

Az API-proxymodul konfigurálása az átjáróhierarchia forgatókönyvéhez

  • Cikk

A következőkre vonatkozik:IoT Edge 1.5 pipa IoT Edge 1.5 IoT Edge 1.4 pipa IoT Edge 1.4

Fontos

Az IoT Edge 1.5 LTS és az IoT Edge 1.4 LTS támogatott kiadások. Az IoT Edge 1.4 LTS 2024. november 12-én megszűnik. Ha egy korábbi kiadáson dolgozik, olvassa el az IoT Edge frissítése című témakört.

Ez a cikk bemutatja az API-proxymodul konfigurációs beállításait, így testre szabhatja a modult az átjáróhierarchia követelményeinek megfelelően.

Az API-proxymodul leegyszerűsíti az IoT Edge-eszközök közötti kommunikációt, ha több olyan szolgáltatás van üzembe helyezve, amelyek mindegyike támogatja a HTTPS protokollt, és a 443-es porthoz kapcsolódik. Ez különösen fontos az IoT Edge-eszközök hierarchikus üzemelő példányaiban ISA-95-alapú, hálózat által izolált architektúrákban, például a Hálózateloszlott alsóbb rétegbeli eszközökben, mivel az alsóbb rétegbeli eszközök ügyfelei nem tudnak közvetlenül csatlakozni a felhőhöz.

Ha például engedélyezni szeretné az alsóbb rétegbeli IoT Edge-eszközök számára a Docker-rendszerképek lekérését, egy Docker-beállításjegyzék-modul üzembe helyezésére van szükség. A blobok feltöltésének engedélyezéséhez üzembe kell helyeznie egy Azure Blob Storage-modult ugyanazon az IoT Edge-eszközön. Mindkét szolgáltatás HTTPS-t használ a kommunikációhoz. Az API-proxy engedélyezi az ilyen üzembe helyezéseket egy IoT Edge-eszközön. Az API-proxymodul minden szolgáltatás helyett a gazdaeszköz 443-es portjához csatlakozik, és a kérést a felhasználó által konfigurálható szabályok szerint az eszközön futó megfelelő szolgáltatásmodulhoz irányítja. Az egyes szolgáltatások továbbra is felelősek a kérések kezeléséért, beleértve az ügyfelek hitelesítését és engedélyezését.

Az API-proxy nélkül minden szolgáltatásmodulnak külön porthoz kellene kapcsolódnia a gazdaeszközön, ami a szülő IoT Edge-eszközhöz csatlakozó minden gyermekeszközön fárasztó és hibalehetőséget igénylő konfigurációs módosítást igényel.

Feljegyzés

Az alsóbb rétegbeli eszközök közvetlenül az internetre vagy átjáróeszközökre bocsátanak ki adatokat (IoT Edge-kompatibilis vagy nem). A gyermekeszköz lehet alsóbb rétegbeli eszköz vagy átjáróeszköz beágyazott topológiában.

A proxymodul üzembe helyezése

Az API-proxymodul a Microsoft Container Registry (MCR) szolgáltatásból érhető el: mcr.microsoft.com/azureiotedge-api-proxy:1.1.

Az API-proxymodult közvetlenül az Azure Marketplace-ről is üzembe helyezheti: IoT Edge API-proxy.

A proxymodul ismertetése

Az API-proxymodul egy nginx fordított proxy használatával irányítja át az adatokat a hálózati rétegeken. A modulban proxy van beágyazva, ami azt jelenti, hogy a modul lemezképének támogatnia kell a proxykonfigurációt. Ha például a proxy egy adott portot figyel, akkor a modulnak nyitva kell lennie.

A proxy a modulba beágyazott alapértelmezett konfigurációs fájllal kezdődik. A modul ikermoduljával új konfigurációt adhat át a felhőből a modulnak. Emellett környezeti változókkal be- és kikapcsolhatja a konfigurációs beállításokat az üzembe helyezéskor.

Ez a cikk először az alapértelmezett konfigurációs fájlra és a környezeti változók használatára összpontosít a beállítások engedélyezéséhez. Ezután a konfigurációs fájl testreszabását tárgyaljuk a végén.

Alapértelmezett konfiguráció

Az API proxymodul egy alapértelmezett konfigurációval rendelkezik, amely támogatja a gyakori forgatókönyveket, és lehetővé teszi a testreszabást. Az alapértelmezett konfigurációt a modul környezeti változóival szabályozhatja.

Jelenleg az alapértelmezett környezeti változók a következők:

Környezeti változó Leírás
PROXY_CONFIG_ENV_VAR_LIST Listázhatja az összes frissítendő változót egy vesszővel tagolt listában. Ez a lépés megakadályozza a helytelen konfigurációs beállítások véletlen módosítását.
NGINX_DEFAULT_TLS Megadja az engedélyezendő TLS-protokollok listáját. Lásd az NGINX ssl_protocols.

Az alapértelmezett érték a "TLSv1.2".
NGINX_DEFAULT_PORT Módosítja azt a portot, amelyet az nginx-proxy figyel. Ha frissíti ezt a környezeti változót, közzé kell tennie a portot a modul dockerfile-jában, és deklarálnia kell a portkötést az üzembehelyezési jegyzékben. További információ: Proxyportok megjelenítése.

Az alapértelmezett érték 443.

Az Azure Marketplace-ről történő üzembe helyezéskor az alapértelmezett port 8000-re frissül, hogy megakadályozza az edgeHub-modullal való ütközéseket. További információ: Nyitott portok kis méretűre állítása.
DOCKER_REQUEST_ROUTE_ADDRESS Docker-kérelmek átirányításának címe. Módosítsa ezt a változót a felső rétegbeli eszközön, hogy a beállításjegyzék-modulra mutasson.

Alapértelmezés szerint a szülő gazdagép neve.
BLOB_UPLOAD_ROUTE_ADDRESS Blob beállításjegyzék-kérelmek átirányításának címe. Módosítsa ezt a változót a felső rétegbeli eszközön, hogy a blobtároló modulra mutasson.

Alapértelmezés szerint a szülő gazdagép neve.

Nyitott portok kis méretűre állítása

A nyitott portok számának minimalizálása érdekében az API-proxymodulnak továbbítania kell az összes HTTPS-forgalmat (443-es port), beleértve az edgeHub-modult célzó forgalmat is. Az API proxymodul alapértelmezés szerint úgy van konfigurálva, hogy a 443-as porton az összes edgeHub-forgalmat átirányítsa.

A következő lépésekkel konfigurálhatja az üzembe helyezést a nyitott portok minimalizálása érdekében:

  1. Frissítse az edgeHub-modul beállításait úgy, hogy ne legyenek kötések a 443-as porton, ellenkező esetben portkötési ütközések lépnek fel. Alapértelmezés szerint az edgeHub-modul a 443-as, az 5671-ös és a 8883-as porton köt. Törölje a 443-es port kötését, és hagyja a másik kettőt a helyén:

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

  2. Konfigurálja az API proxymodult a 443-as porton való kötéshez.

    1. Állítsa a NGINX_DEFAULT_PORT környezeti változó értékét a következőre 443: .

    2. Frissítse a tároló létrehozási beállításait a 443-as porton való kötéshez.

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

Ha nem kell minimalizálnia a nyitott portokat, engedélyezheti, hogy az edgeHub-modul a 443-at használja, és konfigurálja az API-proxymodult egy másik port figyelésére. Az API-proxymodul például a 8000-es porton figyelheti a NGINX_DEFAULT_PORT környezeti változó 8000 értékét, és létrehoz egy portkötést a 8000-es porthoz.

Tárolórendszerkép letöltésének engedélyezése

Az API-proxymodul gyakori használati esete, ha engedélyezi az alsó rétegekben lévő IoT Edge-eszközök számára a tárolólemezképek lekérését. Ez a forgatókönyv a Docker regisztrációs modullal kéri le a tárolólemezképeket a felhőből, és gyorsítótárazza őket a legfelső rétegben. Az API-proxy továbbít minden HTTPS-kérést, hogy letöltsön egy tárolólemezképet az alsó rétegekből, amelyeket a beállításjegyzék-modul a felső rétegben fog kiszolgálni.

Ez a forgatókönyv megköveteli, hogy az alsóbb rétegbeli IoT Edge-eszközök a rendszerkép tárolóregisztrációs adatbázisa helyett a tartománynévre $upstream , majd az API Proxy modul portszámára mutasson. Például: $upstream:8000/azureiotedge-api-proxy:1.1

Ezt a használati esetet mutatja be az oktatóanyag IoT Edge-eszközök hierarchiájának létrehozása átjárókkal.

Konfigurálja a következő modulokat a felső rétegben:

  • Docker-beállításjegyzék-modul
    • Konfigurálja a modult egy olyan emlékezetes névvel, mint a beállításjegyzék , és tegyen közzé egy portot a modulban a kérések fogadásához.
    • Konfigurálja a modult a tárolóregisztrációs adatbázishoz való leképezéshez.
  • API-proxymodul

    • Konfigurálja a következő környezeti változókat:

      Név szerint Érték
      DOCKER_REQUEST_ROUTE_ADDRESS A beállításjegyzék-modul neve és a megnyitott port. Például: registry:5000.
      NGINX_DEFAULT_PORT Az a port, amelyen az nginx-proxy figyeli az alsóbb rétegbeli eszközöktől érkező kéréseket. Például: 8000.

    • Konfigurálja a következő createOptionst:

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

Konfigurálja a következő modult a forgatókönyv bármely alsó rétegén :

  • API-proxymodul. Az API-proxymodul az alsó rétegbeli eszköz kivételével minden alsó rétegbeli eszközön kötelező.

    • Konfigurálja a következő környezeti változókat:

      Név szerint Érték
      NGINX_DEFAULT_PORT Az a port, amelyen az nginx-proxy figyeli az alsóbb rétegbeli eszközöktől érkező kéréseket. Például: 8000.

    • Konfigurálja a következő createOptionst:

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

Proxyport elérhetővé helyezése

A 8000-s port alapértelmezés szerint ki van téve a Docker-rendszerképből. Ha másik nginx proxyportot használ, adja hozzá az ExposedPorts szakaszt, amely deklarálja a portot az üzembehelyezési jegyzékben. Ha például az nginx proxyportot 8001-re módosítja, adja hozzá a következőket az üzembehelyezési jegyzékhez:

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

Blobfeltöltés engedélyezése

Az API-proxymodul másik használati esete, hogy engedélyezi az alsó rétegekben lévő IoT Edge-eszközöket a blobok feltöltéséhez. Ez a használati eset lehetővé teszi az alacsonyabb rétegű eszközök hibaelhárítási funkcióit, például a modulnaplók feltöltését vagy a támogatási csomag feltöltését.

Ez a forgatókönyv a legfelső réteg IoT Edge-alapú Azure Blob Storage-moduljának használatával kezeli a blobok létrehozását és feltöltését. Beágyazott forgatókönyv esetén legfeljebb öt réteg támogatott. Az IoT Edge-en futó Azure Blob Storage modul szükséges a felső rétegbeli eszközön, és nem kötelező az alsó rétegbeli eszközökhöz. A többrétegű üzembe helyezés mintájához tekintse meg az Azure IoT Edge for Industrial IoT-mintát .

Konfigurálja a következő modulokat a felső rétegben:

  • Azure Blob Storage az IoT Edge-en modul.
  • API-proxymodul

    • Konfigurálja a következő környezeti változókat:

      Név szerint Érték
      BLOB_UPLOAD_ROUTE_ADDRESS A blobtároló modul neve és a nyitott port. Például: azureblobstorageoniotedge:11002.
      NGINX_DEFAULT_PORT Az a port, amelyen az nginx-proxy figyeli az alsóbb rétegbeli eszközöktől érkező kéréseket. Például: 8000.

    • Konfigurálja a következő createOptionst:

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

Konfigurálja a következő modult a forgatókönyv bármely alsó rétegén :

  • API-proxymodul

    • Konfigurálja a következő környezeti változókat:

      Név szerint Érték
      NGINX_DEFAULT_PORT Az a port, amelyen az nginx-proxy figyeli az alsóbb rétegbeli eszközöktől érkező kéréseket. Például: 8000.

    • Konfigurálja a következő createOptionst:

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

Az alábbi lépésekkel töltse fel a támogatási csomagot vagy a naplófájlt a legfelső rétegben található Blob Storage-modulba:

  1. Hozzon létre egy blobtárolót az Azure Storage Explorer vagy a REST API-k használatával. További információ: Adatok tárolása a peremhálózaton az Azure Blob Storage-ban az IoT Edge-en.

  2. Napló vagy támogatási csomag feltöltésének kérése az IoT Edge-környezetekből származó naplók lekérése lépésekkel, de használja a tartománynevet $upstream és a nyílt proxyportot a Blob Storage-modul címe helyett. Példa:

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

A proxykonfiguráció szerkesztése

Az API-proxymodulba egy alapértelmezett konfigurációs fájl van beágyazva, de a modul ikermoduljával új konfigurációt adhat át a modulnak a felhőn keresztül.

Amikor saját konfigurációt ír, a környezettel továbbra is módosíthatja az üzemelő példányonkénti beállításokat. Alkalmazza a következő szintaxist:

  • Egy környezeti változó értékének lekérésére használható ${MY_ENVIRONMENT_VARIABLE} .

  • Feltételes utasítások használatával be- vagy kikapcsolhatja a beállításokat egy környezeti változó értéke alapján:

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

Amikor az API proxymodul egy proxykonfigurációt elemez, először lecseréli a benne felsorolt összes környezeti változót a PROXY_CONFIG_ENV_VAR_LIST megadott értékekre helyettesítéssel. Ezután minden egy és #endif_tag pár #if_tag között lecserélődik. A modul ezután biztosítja az elemzett konfigurációt az nginx fordított proxyhoz.

A proxykonfiguráció dinamikus frissítéséhez kövesse az alábbi lépéseket:

  1. Írja meg a konfigurációs fájlt. Ezt az alapértelmezett sablont hivatkozásként használhatja: nginx_default_config.conf

  2. Másolja ki a konfigurációs fájl szövegét, és konvertálja base64 formátumba.

  3. Illessze be a kódolt konfigurációs fájlt a modul ikerpéldányában a proxy_config kívánt tulajdonság értékeként.

    Képernyőkép a kódolt konfigurációs fájl beillesztéséről proxy_config tulajdonság értékeként.

Következő lépések

Az API-proxymodullal Csatlakozás egy alsóbb rétegbeli IoT Edge-eszközt egy Azure IoT Edge-átjáróba.