Konfigurace modulu proxy rozhraní API pro scénář hierarchie brány

  • Článek

Platí pro:Značka zaškrtnutí IoT Edge 1.5 IoT Edge 1.5 Značka zaškrtnutí IoT Edge 1.4 IoT Edge 1.4

Důležité

Podporované verze ioT Edge 1.5 LTS a IoT Edge 1.4 LTS. IoT Edge 1.4 LTS je konec životnosti 12. listopadu 2024. Pokud používáte starší verzi, podívejte se na článek Aktualizace IoT Edge.

Tento článek vás provede možnostmi konfigurace pro modul proxy rozhraní API, abyste mohli modul přizpůsobit tak, aby podporoval požadavky na hierarchii brány.

Modul proxy rozhraní API zjednodušuje komunikaci pro zařízení IoT Edge, když je nasazeno více služeb, které podporují protokol HTTPS a jsou svázané s portem 443. To je zvlášť důležité v hierarchických nasazeních zařízení IoT Edge v architekturách izolovaných sítí založených na ISA-95, jako jsou ty, které jsou popsané v tématu Síťová izolace podřízených zařízení , protože klienti na podřízených zařízeních se nemůžou připojit přímo ke cloudu.

Pokud například chcete, aby podřízená zařízení IoT Edge mohla načítat image Dockeru, vyžaduje nasazení modulu registru Dockeru. Pokud chcete povolit nahrávání objektů blob, vyžaduje nasazení modulu Azure Blob Storage na stejném zařízení IoT Edge. Obě tyto služby používají pro komunikaci protokol HTTPS. Proxy rozhraní API umožňuje taková nasazení na zařízení IoT Edge. Místo každé služby vytvoří modul proxy rozhraní API vazbu na port 443 na hostitelském zařízení a směruje požadavek na správný modul služby spuštěný na daném zařízení podle uživatelsky konfigurovatelných pravidel. Jednotlivé služby jsou stále zodpovědné za zpracování požadavků, včetně ověřování a autorizace klientů.

Bez proxy serveru rozhraní API by každý modul služby musel svázat s samostatným portem na hostitelském zařízení, což vyžaduje zdlouhavou změnu konfigurace náchylné k chybám na každém podřízené zařízení, které se připojuje k nadřazené zařízení IoT Edge.

Poznámka:

Podřízené zařízení vysílá data přímo do internetu nebo do zařízení brány (nebo ne). Podřízené zařízení může být podřízené zařízení nebo zařízení brány v vnořené topologii.

Nasazení modulu proxy

Modul proxy rozhraní API je k dispozici ve službě Microsoft Container Registry (MCR): mcr.microsoft.com/azureiotedge-api-proxy:1.1.

Modul proxy serveru rozhraní API můžete také nasadit přímo z Azure Marketplace: Proxy rozhraní API Služby IoT Edge.

Vysvětlení modulu proxy

Modul proxy rozhraní API využívá reverzní proxy server nginx ke směrování dat přes síťové vrstvy. Proxy server je vložený do modulu, což znamená, že image modulu musí podporovat konfiguraci proxy serveru. Pokud například proxy server naslouchá na určitém portu, musí mít modul otevřený tento port.

Proxy server začíná výchozím konfiguračním souborem vloženým do modulu. Pomocí dvojčete modulu můžete modulu předat novou konfiguraci z cloudu. Kromě toho můžete pomocí proměnných prostředí zapnout nebo vypnout nastavení konfigurace v době nasazení.

Tento článek se nejprve zaměřuje na výchozí konfigurační soubor a na to, jak pomocí proměnných prostředí povolit jeho nastavení. Pak probereme přizpůsobení konfiguračního souboru na konci.

Výchozí konfigurace

Modul proxy rozhraní API se dodává s výchozí konfigurací, která podporuje běžné scénáře a umožňuje přizpůsobení. Výchozí konfiguraci můžete řídit prostřednictvím proměnných prostředí modulu.

Výchozí proměnné prostředí v současné době zahrnují:

Proměnná prostředí Popis
PROXY_CONFIG_ENV_VAR_LIST Zobrazte seznam všech proměnných, které chcete aktualizovat v seznamu odděleném čárkami. Tento krok zabraňuje náhodné úpravě nesprávného nastavení konfigurace.
NGINX_DEFAULT_TLS Určuje seznam protokolů TLS, které se mají povolit. Viz ssl_protocols NGINX.

Výchozí hodnota je TLSv1.2.
NGINX_DEFAULT_PORT Změní port, na který proxy server nginx naslouchá. Pokud tuto proměnnou prostředí aktualizujete, musíte vystavit port v souboru dockerfile modulu a deklarovat vazbu portu v manifestu nasazení. Další informace najdete v tématu Zveřejnění portu proxy serveru.

Výchozí hodnota je 443.

Po nasazení z Azure Marketplace se výchozí port aktualizuje na 8000, aby se zabránilo konfliktům s modulem EdgeHub. Další informace najdete v tématu Minimalizace otevřených portů.
DOCKER_REQUEST_ROUTE_ADDRESS Adresa pro směrování požadavků Dockeru Upravte tuto proměnnou v zařízení nejvyšší vrstvy tak, aby odkazovat na modul registru.

Výchozí hodnota je nadřazený název hostitele.
BLOB_UPLOAD_ROUTE_ADDRESS Adresa pro směrování požadavků registru objektů blob. Upravte tuto proměnnou v zařízení nejvyšší vrstvy tak, aby odkazovat na modul úložiště objektů blob.

Výchozí hodnota je nadřazený název hostitele.

Minimalizace otevřených portů

Aby se minimalizoval počet otevřených portů, měl by modul proxy rozhraní API předávat veškerý provoz HTTPS (port 443), včetně provozu, který cílí na modul EdgeHub. Modul proxy rozhraní API je standardně nakonfigurovaný tak, aby znovu směroval veškerý provoz edgeHubu na portu 443.

Pomocí následujících kroků nakonfigurujte nasazení tak, aby se minimalizovaly otevřené porty:

  1. Aktualizujte nastavení modulu EdgeHub tak, aby se neváže na portu 443, jinak dojde ke konfliktům vazeb portů. Ve výchozím nastavení se modul EdgeHub sváže na portech 443, 5671 a 8883. Odstraňte vazbu portu 443 a nechte ostatní dva na místě:

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

  2. Nakonfigurujte modul proxy rozhraní API tak, aby se svážel na portu 443.

    1. Nastavte hodnotu proměnné prostředí NGINX_DEFAULT_PORT na 443hodnotu .

    2. Aktualizujte možnosti vytvoření kontejneru tak, aby se svážely na portu 443.

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

Pokud nepotřebujete minimalizovat otevřené porty, můžete nechat modul EdgeHub používat port 443 a nakonfigurovat modul proxy rozhraní API tak, aby naslouchal na jiném portu. Například modul proxy rozhraní API může naslouchat na portu 8000 nastavením hodnoty proměnné prostředí NGINX_DEFAULT_PORT na 8000 port 8000 a vytvořením vazby portu pro port 8000.

Povolení stahování imagí kontejneru

Běžným případem použití modulu proxy rozhraní API je povolení vyžádání imagí kontejnerů zařízením IoT Edge v nižších vrstvách. Tento scénář používá modul registru Dockeru k načtení imagí kontejnerů z cloudu a jejich ukládání do mezipaměti v horní vrstvě. Proxy server rozhraní API předává všechny požadavky HTTPS na stažení image kontejneru z nižších vrstev, které bude obsluhovat modul registru v horní vrstvě.

Tento scénář vyžaduje, aby podřízená zařízení IoT Edge odkazovali na název $upstream domény následovaný číslem portu modulu proxy rozhraní API místo registru kontejneru image. Například: $upstream:8000/azureiotedge-api-proxy:1.1.

Tento případ použití je ukázaný v kurzu Vytvoření hierarchie zařízení IoT Edge pomocí bran.

Na nejvyšší vrstvě nakonfigurujte následující moduly:

  • Modul registru Dockeru
    • Nakonfigurujte modul s zapamatovatelným názvem, jako je registr , a zpřístupňte port v modulu pro příjem požadavků.
    • Nakonfigurujte modul pro mapování na registr kontejneru.
  • Modul proxy rozhraní API

    • Nakonfigurujte následující proměnné prostředí:

      Jméno Hodnota
      DOCKER_REQUEST_ROUTE_ADDRESS Název modulu registru a otevření portu. Například registry:5000.
      NGINX_DEFAULT_PORT Port, na který proxy server nginx naslouchá žádostem z podřízených zařízení. Například 8000.

    • Nakonfigurujte následující možnosti createOptions:

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

Pro tento scénář nakonfigurujte následující modul na libovolné nižší vrstvě :

  • Modul proxy rozhraní API. Modul proxy rozhraní API se vyžaduje na všech zařízeních nižší vrstvy s výjimkou zařízení nejnižší vrstvy.

    • Nakonfigurujte následující proměnné prostředí:

      Jméno Hodnota
      NGINX_DEFAULT_PORT Port, na který proxy server nginx naslouchá žádostem z podřízených zařízení. Například 8000.

    • Nakonfigurujte následující možnosti createOptions:

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

Zveřejnění portu proxy serveru

Port 8000 je ve výchozím nastavení zpřístupněný z image Dockeru. Pokud se použije jiný port proxy serveru nginx, přidejte část ExposedPorts deklarující port v manifestu nasazení. Pokud například změníte port proxy serveru nginx na 8001, přidejte do manifestu nasazení následující kód:

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

Povolení nahrávání objektů blob

Dalším případem použití modulu proxy rozhraní API je povolení, aby zařízení IoT Edge v nižších vrstvách nahrála objekty blob. Tento případ použití umožňuje řešení potíží na zařízeních s nižší vrstvou, jako je nahrání protokolů modulů nebo nahrání sady podpory.

Tento scénář používá modul Azure Blob Storage ve službě IoT Edge v horní vrstvě ke zpracování vytváření a nahrávání objektů blob. Ve vnořeném scénáři se podporuje až pět vrstev. Modul Azure Blob Storage ve službě IoT Edge se vyžaduje na zařízení nejvyšší vrstvy a volitelné pro zařízení s nižší vrstvou. Ukázkové nasazení ve více vrstvách najdete v ukázce Azure IoT Edge pro průmyslové IoT .

Na nejvyšší vrstvě nakonfigurujte následující moduly:

  • Modul Azure Blob Storage ve službě IoT Edge
  • Modul proxy rozhraní API

    • Nakonfigurujte následující proměnné prostředí:

      Jméno Hodnota
      BLOB_UPLOAD_ROUTE_ADDRESS Název modulu úložiště objektů blob a otevřený port. Například azureblobstorageoniotedge:11002.
      NGINX_DEFAULT_PORT Port, na který proxy server nginx naslouchá žádostem z podřízených zařízení. Například 8000.

    • Nakonfigurujte následující možnosti createOptions:

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

Pro tento scénář nakonfigurujte následující modul na libovolné nižší vrstvě :

  • Modul proxy rozhraní API

    • Nakonfigurujte následující proměnné prostředí:

      Jméno Hodnota
      NGINX_DEFAULT_PORT Port, na který proxy server nginx naslouchá žádostem z podřízených zařízení. Například 8000.

    • Nakonfigurujte následující možnosti createOptions:

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

Pomocí následujících kroků nahrajte balíček podpory nebo soubor protokolu do modulu úložiště objektů blob umístěného v horní vrstvě:

  1. Vytvořte kontejner objektů blob pomocí Průzkumník služby Azure Storage nebo rozhraní REST API. Další informace najdete v tématu Ukládání dat na hraničních zařízeních pomocí služby Azure Blob Storage ve službě IoT Edge.

  2. Požádejte o nahrání protokolu nebo sady podpory podle kroků v části Načtení protokolů z nasazení IoT Edge, ale místo adresy modulu úložiště objektů blob použijte název $upstream domény a otevřený port proxy serveru. Příklad:

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

Úprava konfigurace proxy serveru

Výchozí konfigurační soubor je vložený do modulu proxy rozhraní API, ale pomocí dvojčete modulu můžete modulu předat novou konfiguraci prostřednictvím cloudu.

Při psaní vlastní konfigurace můžete prostředí použít k úpravě nastavení pro každé nasazení. Použijte následující syntax:

  • Slouží ${MY_ENVIRONMENT_VARIABLE} k načtení hodnoty proměnné prostředí.

  • Pomocí podmíněných příkazů můžete zapnout nebo vypnout nastavení na základě hodnoty proměnné prostředí:

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

Když modul proxy serveru rozhraní API parsuje konfiguraci proxy serveru, nejprve nahradí všechny proměnné prostředí uvedené v PROXY_CONFIG_ENV_VAR_LIST zadané hodnotě pomocí nahrazení. Pak se vše mezi párem #if_tag a #endif_tag párem nahradí. Modul pak poskytuje analyzovanou konfiguraci reverzního proxy serveru nginx.

Pokud chcete konfiguraci proxy serveru aktualizovat dynamicky, postupujte následovně:

  1. Zapište konfigurační soubor. Tuto výchozí šablonu můžete použít jako referenci: nginx_default_config.conf

  2. Zkopírujte text konfiguračního souboru a převeďte ho na base64.

  3. Vložte zakódovaný konfigurační soubor jako hodnotu proxy_config požadované vlastnosti ve dvojčeti modulu.

    Snímek obrazovky znázorňující, jak vložit kódovaný konfigurační soubor jako hodnotu vlastnosti proxy_config

Další kroky

Použijte modul proxy rozhraní API k Připojení podřízeného zařízení IoT Edge k bráně Azure IoT Edge.