Udostępnij za pośrednictwem

Konfigurowanie modułu serwera proxy interfejsu API dla scenariusza hierarchii bramy

Applies to:IoT Edge 1.5 znacznik wyboru IoT Edge 1.5

Ważne

IoT Edge 1.5 LTS to wspierana wersja. IoT Edge 1.4 LTS osiągnął koniec życia 12 listopada 2024 r. Jeśli używasz wcześniejszej wersji, zobacz Update IoT Edge.

W tym artykule opisano opcje konfiguracji modułu proxy API, dzięki czemu można dostosować moduł do wymagań hierarchii bram.

Moduł proxy API upraszcza komunikację dla urządzeń IoT Edge, gdy z protokołu HTTPS korzysta wiele usług i są wiązani do portu 443. Ta konfiguracja jest szczególnie istotna w hierarchicznych wdrożeniach urządzeń IoT Edge w architekturach izolowanych sieci opartych na ISA-95, takich jak te opisane w Izolacja sieciowa urządzeń podrzędnych, ponieważ klienci urządzeń podrzędnych nie mogą łączyć się bezpośrednio z chmurą.

Na przykład umożliwienie urządzeniom podrzędnym IoT Edge ściągania obrazów platformy Docker wymaga wdrożenia modułu rejestru platformy Docker. Zezwolenie urządzeniom na przekazywanie obiektów blob wymaga wdrożenia modułu Azure Blob Storage na tym samym urządzeniu IoT Edge. Obie usługi używają protokołu HTTPS do komunikacji. Moduł proxy API umożliwia te wdrożenia na urządzeniu IoT Edge. Zamiast każdego powiązania usługi z portem 443 moduł serwera proxy interfejsu API jest powiązany z portem 443 na urządzeniu hosta i kieruje żądania do poprawnego modułu usługi uruchomionego na tym urządzeniu na podstawie reguł konfigurowalnych przez użytkownika. Poszczególne usługi są nadal odpowiedzialne za obsługę żądań, w tym uwierzytelnianie i autoryzowanie klientów.

Bez serwera proxy API każdy moduł usługi musi być przypisany do oddzielnego portu na urządzeniu hosta, co wymaga żmudnej i podatnej na błędy zmiany konfiguracji na każdym urządzeniu podrzędnym łączącym się z nadrzędnym urządzeniem IoT Edge.

Uwaga

Urządzenie podrzędne wysyła dane bezpośrednio do Internetu lub do urządzeń bramowych (z obsługą IoT Edge lub bez). Urządzenie podrzędne może być urządzeniem końcowym lub urządzeniem bramy w topologii zagnieżdżonej.

Wdrażanie modułu proxy

Moduł serwera proxy interfejsu API jest dostępny w usłudze Microsoft Container Registry (MCR), a identyfikator URI obrazu to mcr.microsoft.com/azureiotedge-api-proxy:latest. Wdróż moduł przy użyciu portalu Azure lub Azure CLI.

Omówienie modułu proxy

Moduł proxy API używa serwera proxy zwrotnego nginx do kierowania danych przez warstwy sieciowe. Moduł ma osadzony serwer proxy, więc obraz modułu musi obsługiwać konfigurację serwera proxy. Jeśli na przykład serwer proxy nasłuchuje na określonym porcie, moduł musi mieć otwarty ten port.

Serwer proxy rozpoczyna się od domyślnego pliku konfiguracji osadzonego w module. Przekaż nową konfigurację do modułu z chmury przy użyciu bliźniaka modułu. Możesz również użyć zmiennych środowiskowych, aby włączyć lub wyłączyć ustawienia konfiguracji w czasie wdrażania.

W tym artykule najpierw opisano domyślny plik konfiguracji i sposób używania zmiennych środowiskowych do włączania jego ustawień. Następnie wyjaśniono, jak dostosować plik konfiguracji.

Konfiguracja domyślna

Moduł serwera proxy interfejsu API zawiera domyślną konfigurację, która obsługuje typowe scenariusze i umożliwia jej dostosowanie. Kontrolowanie domyślnej konfiguracji za pomocą zmiennych środowiskowych modułu.

Obecnie domyślne zmienne środowiskowe obejmują:

Zmienna środowiskowa opis
PROXY_CONFIG_ENV_VAR_LIST Wyświetl listę wszystkich zmiennych, które chcesz zaktualizować na liście rozdzielanej przecinkami. Ten krok pomaga zapobiec przypadkowej zmianie nieprawidłowych ustawień konfiguracji.
NGINX_DEFAULT_TLS Ustawia listę protokołów TLS, które mają być włączone. Zobacz protokoły_ssl NGINX-a.

Wartość domyślna to "TLSv1.2".
NGINX_DEFAULT_PORT Zmienia port, na który nasłuchuje serwer proxy nginx. Jeśli zaktualizujesz tę zmienną środowiskową, uwidocznij port w pliku dockerfile modułu i zadeklaruj powiązanie portu w manifeście wdrożenia. Aby uzyskać więcej informacji, zobacz Uwidacznij port serwera proxy.

Wartość domyślna to 443.

Po wdrożeniu z Azure Marketplace domyślny port zmieni się na 8000, aby zapobiec konfliktom z modułem edgeHub. Aby uzyskać więcej informacji, zobacz Minimalizuj otwarte porty.
DOCKER_REQUEST_ROUTE_ADDRESS Adres do kierowania żądań platformy Docker. Zmodyfikuj tę zmienną na urządzeniu warstwy górnej, aby wskazać moduł rejestru.

Wartość domyślna to nadrzędna nazwa hosta.
BLOB_UPLOAD_ROUTE_ADDRESS Adres do trasowania żądań do rejestru obiektów blob. Zmodyfikuj tę zmienną na urządzeniu w górnej warstwie, aby wskazać moduł magazynu obiektów Blob.

Wartość domyślna to nadrzędna nazwa hosta.

Minimalizuj otwarte porty

Aby zminimalizować otwarte porty, ustaw moduł proxy interfejsu API na przekazywanie całego ruchu HTTPS (port 443), w tym ruchu dla modułu edgeHub. Domyślnie moduł proxy interfejsu API przekierowuje cały ruch EdgeHub na porcie 443.

Wykonaj następujące kroki, aby skonfigurować wdrożenie w celu zminimalizowania otwartych portów:

  1. Zaktualizuj ustawienia modułu edgeHub, aby nie wiązać się z portem 443. W przeciwnym razie wystąpią konflikty powiązań portów. Domyślnie moduł edgeHub wiąże się z portami 443, 5671 i 8883. Usuń powiązanie portu 443 i pozostaw pozostałe dwa:

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

  2. Skonfiguruj moduł proxy interfejsu API, aby łączył się na porcie 443.

    1. Ustaw wartość zmiennej środowiskowej NGINX_DEFAULT_PORT na 443.

    2. Zaktualizuj opcje tworzenia kontenera, aby powiązać z portem 443.

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

Jeśli nie musisz minimalizować otwartych portów, pozwól modułowi edgeHub korzystać z portu 443 i skonfiguruj moduł serwera proxy interfejsu API tak, aby nasłuchiwał na innym porcie. Na przykład skonfiguruj zmienną środowiskową NGINX_DEFAULT_PORT jako 8000, a następnie utwórz powiązanie dla portu 8000.

Włączanie pobierania obrazu kontenera

Typowym przypadkiem użycia modułu serwera proxy API jest umożliwienie urządzeniom IoT Edge w niższych warstwach pobierania obrazów kontenerów. W tym scenariuszu używany jest moduł rejestru platformy Docker do pobierania obrazów kontenerów z chmury i buforowania ich w górnej warstwie. Serwer proxy interfejsu API przekazuje wszystkie żądania HTTPS w celu pobrania obrazu kontenera z niższych warstw do modułu rejestru w górnej warstwie.

W tym scenariuszu urządzenia podrzędne IoT Edge wskazują nazwę domeny $upstream, a następnie numer portu modułu proxy interfejsu API zamiast rejestru kontenerów obrazu. Na przykład $upstream:8000/azureiotedge-api-proxy:1.1.

Ten przypadek użycia przedstawiono w samouczku Utwórz hierarchię urządzeń IoT Edge przy użyciu bram.

Skonfiguruj następujące moduły w górnej warstwie:

  • Moduł rejestru platformy Docker
    • Skonfiguruj moduł z pamiętną nazwą, taką jak rejestr, i udostępnij port w module, aby odbierać żądania.
    • Skonfiguruj moduł do mapowania na rejestr kontenerów.
  • Moduł proxy API

    • Skonfiguruj następujące zmienne środowiskowe:

      Nazwa/nazwisko Wartość
      DOCKER_REQUEST_ROUTE_ADDRESS Nazwa modułu rejestru i otwarty port. Na przykład registry:5000.
      NGINX_DEFAULT_PORT Port, na który nasłuchuje serwer proxy nginx dla żądań z urządzeń podrzędnych. Na przykład 8000.

    • Skonfiguruj następujące opcje tworzenia (createOptions):

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

Skonfiguruj następujący moduł w dowolnej niższej warstwie dla tego scenariusza:

  • Moduł proxy API Moduł proxy interfejsu API jest wymagany na wszystkich urządzeniach warstwy niższej z wyjątkiem urządzenia warstwy dolnej.

    • Skonfiguruj następujące zmienne środowiskowe:

      Nazwa/nazwisko Wartość
      NGINX_DEFAULT_PORT Port, na który nasłuchuje serwer proxy nginx dla żądań z urządzeń podrzędnych. Na przykład 8000.

    • Skonfiguruj następujące opcje tworzenia (createOptions):

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

Uwidacznianie portu serwera proxy

Port 8000 jest domyślnie udostępniany z obrazu Docker. Jeśli używasz innego portu serwera proxy nginx, dodaj sekcję ExposedPorts , aby zadeklarować port w manifeście wdrożenia. Jeśli na przykład zmienisz port serwera proxy nginx na 8001, dodaj następujący kod do manifestu wdrożenia:

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

Włącz przesyłanie obiektów blob

Inne zastosowanie modułu serwera proxy API to umożliwienie urządzeniom IoT Edge w niższych warstwach przesyłania obiektów blob. Ten przypadek użycia umożliwia rozwiązywanie problemów z urządzeniami niższej warstwy, na przykład poprzez wgrywanie dzienników modułów lub pakietu wsparcia.

W tym scenariuszu moduł Azure Blob Storage w IoT Edge w górnej warstwie jest używany do obsługi tworzenia i przesyłania obiektów blob. W scenariuszu zagnieżdżonym obsługiwanych jest maksymalnie pięć warstw. Moduł Azure Blob Storage w IoT Edge jest wymagany na urządzeniu warstwy górnej, ale jest opcjonalny dla urządzeń niższej warstwy. Aby zobaczyć przykładowe wdrożenie wielowarstwowe, zobacz Azure IoT Edge for Industrial IoT.

Skonfiguruj następujące moduły w górnej warstwie:

  • Moduł Azure Blob Storage na platformie IoT Edge.
  • Moduł proxy API

    • Skonfiguruj następujące zmienne środowiskowe:

      Nazwa/nazwisko Wartość
      BLOB_UPLOAD_ROUTE_ADDRESS Nazwa modułu usługi Blob Storage i otwarty port. Na przykład azureblobstorageoniotedge:11002.
      NGINX_DEFAULT_PORT Port, na który nasłuchuje serwer proxy nginx dla żądań z urządzeń podrzędnych. Na przykład 8000.

    • Skonfiguruj następujące opcje tworzenia (createOptions):

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

Skonfiguruj następujący moduł w dowolnej niższej warstwie dla tego scenariusza:

  • Moduł proxy API

    • Skonfiguruj następujące zmienne środowiskowe:

      Nazwa/nazwisko Wartość
      NGINX_DEFAULT_PORT Port, na który nasłuchuje serwer proxy nginx dla żądań z urządzeń podrzędnych. Na przykład 8000.

    • Skonfiguruj następujące opcje tworzenia (createOptions):

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

Wykonaj następujące kroki, aby załadować paczkę wsparcia lub plik dziennika do modułu magazynu blob w górnej warstwie:

  1. Utwórz kontener obiektów blob przy użyciu Azure Storage Explorer lub REST API. Aby uzyskać więcej informacji, zobacz dokumentację Azure Storage Explorer.

  2. Zażądaj przekazania dziennika lub pakietu wsparcia, wykonując kroki opisane w Pobierz dzienniki z wdrożeń IoT Edge, ale użyj nazwy domeny $upstream i otwartego portu proxy zamiast adresu modułu magazynu obiektów blob. Na przykład:

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

Edytowanie konfiguracji serwera proxy

Domyślny plik konfiguracji jest osadzony w module serwera proxy interfejsu API, ale możesz przekazać nową konfigurację do modułu za pośrednictwem chmury przy użyciu bliźniaczego modułu.

Podczas pisania własnej konfiguracji można nadal używać zmiennych środowiskowych do dostosowywania ustawień dla każdego wdrożenia. Użyj następującej składni:

  • Użyj ${MY_ENVIRONMENT_VARIABLE} polecenia , aby uzyskać wartość zmiennej środowiskowej.

  • Użyj instrukcji warunkowych, aby włączyć lub wyłączyć ustawienia na podstawie wartości zmiennej środowiskowej:

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

Gdy moduł serwera proxy API analizuje konfigurację proxy, najpierw zastępuje wszystkie zmienne środowiskowe wymienione w elemencie PROXY_CONFIG_ENV_VAR_LIST ich wartościami, używając podstawienia. Następnie zastępuje wszystkie elementy między parą znaczników #if_tag a #endif_tag. Następnie moduł udostępnia przeanalizowaną konfigurację zwrotnego serwera proxy nginx.

Aby dynamicznie zaktualizować konfigurację serwera proxy, wykonaj następujące kroki:

  1. Zapisz plik konfiguracji. Użyj tego szablonu domyślnego jako odwołania: nginx_default_config.conf.

  2. Skopiuj tekst pliku konfiguracji i przekonwertuj go na base64.

  3. Wklej zakodowany plik konfiguracji jako wartość proxy_config żądanej właściwości modułu bliźniaczego.

    Zrzut ekranu przedstawiający sposób wklejania zakodowanego pliku konfiguracji jako wartości właściwości proxy_config.

Następne kroki

Użyj modułu proxy interfejsu API, aby połączyć urządzenie podrzędne IoT Edge z bramą Azure IoT Edge.

  • Last updated on