Udostępnij za pośrednictwem

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

  • Artykuł

Dotyczy: Znacznik wyboru usługi IoT Edge 1.5 IoT Edge 1.5 Znacznik wyboru usługi IoT Edge 1.4 IoT Edge 1.4

Ważne

Obsługiwane są wersje usługi IoT Edge 1.5 LTS i IoT Edge 1.4 LTS. Usługa IoT Edge 1.4 LTS kończy się 12 listopada 2024 r. Jeśli korzystasz z wcześniejszej wersji, zobacz aktualizację Azure IoT Edge.

W tym artykule przedstawiono opcje konfiguracji modułu serwera proxy interfejsu API, dzięki czemu można dostosować moduł do obsługi wymagań hierarchii bramy.

Moduł serwera proxy interfejsu API upraszcza komunikację dla urządzeń usługi IoT Edge, gdy wdrożono wiele usług, które obsługują protokół HTTPS i wiążą się z portem 443. Jest to szczególnie istotne w hierarchicznych wdrożeniach urządzeń usługi IoT Edge w architekturach izolowanych sieci opartych na architekturze ISA-95, takich jak te opisane w temacie Network isolate downstream devices (Izolowanie sieci urządzeń podrzędnych), ponieważ klienci na urządzeniach podrzędnych nie mogą łączyć się bezpośrednio z chmurą.

Aby na przykład umożliwić podrzędnym urządzeniom usługi IoT Edge ściąganie obrazów platformy Docker, wymaga wdrożenia modułu rejestru platformy Docker. Aby umożliwić przekazywanie obiektów blob, wymagane jest wdrożenie modułu usługi Azure Blob Storage na tym samym urządzeniu usługi IoT Edge. Obie te usługi używają protokołu HTTPS do komunikacji. Serwer proxy interfejsu API umożliwia takie wdrożenia na urządzeniu usługi IoT Edge. Zamiast każdej usługi moduł serwera proxy interfejsu API jest powiązany z portem 443 na urządzeniu hosta i kieruje żądanie do poprawnego modułu usługi uruchomionego na tym urządzeniu zgodnie z regułami konfigurowalnymi przez użytkownika. Poszczególne usługi są nadal odpowiedzialne za obsługę żądań, w tym uwierzytelnianie i autoryzowanie klientów.

Bez serwera proxy interfejsu API każdy moduł usługi musiałby powiązać z oddzielnym portem na urządzeniu hosta, co wymaga żmudnej i podatnej na błędy zmiany konfiguracji na każdym urządzeniu podrzędnym, które łączy się z nadrzędnym urządzeniem usługi IoT Edge.

Uwaga

Urządzenie podrzędne emituje dane bezpośrednio do Internetu lub do urządzeń bramy (usługa IoT Edge jest włączona lub nie). Urządzenie podrzędne może być urządzeniem podrzędnym 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. Moduł można wdrożyć przy użyciu witryny Azure Portal lub interfejsu wiersza polecenia platformy Azure.

Omówienie modułu proxy

Moduł serwera proxy interfejsu API wykorzystuje zwrotny serwer proxy nginx do kierowania danych za pośrednictwem warstw sieciowych. Serwer proxy jest osadzony w module, co oznacza, że 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. Nową konfigurację można przekazać do modułu z chmury przy użyciu bliźniaczej reprezentacji modułu. Ponadto można użyć zmiennych środowiskowych, aby włączyć lub wyłączyć ustawienia konfiguracji w czasie wdrażania.

Ten artykuł koncentruje się najpierw na domyślnym pliku konfiguracji i sposobie używania zmiennych środowiskowych w celu włączenia jego ustawień. Następnie omówimy dostosowywanie pliku konfiguracji na końcu.

Konfiguracja domyślna

Moduł serwera proxy interfejsu API zawiera konfigurację domyślną, która obsługuje typowe scenariusze i umożliwia dostosowanie. Konfigurację domyślną można kontrolować 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 mają być aktualizowane na liście rozdzielanej przecinkami. Ten krok uniemożliwia przypadkowe zmodyfikowanie nieprawidłowych ustawień konfiguracji.
NGINX_DEFAULT_TLS Określa listę protokołów TLS, które mają być włączone. Zobacz ssl_protocols NGINX.

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ą, musisz uwidocznić port w pliku dockerfile modułu i zadeklarować 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 witryny Azure Marketplace domyślny port zostanie zaktualizowany do 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 kierowania żądań rejestru obiektów blob. Zmodyfikuj tę zmienną na urządzeniu warstwy górnej, aby wskazać moduł magazynu obiektów blob.

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

Minimalizuj otwarte porty

Aby zminimalizować liczbę otwartych portów, moduł serwera proxy interfejsu API powinien przekazywać cały ruch HTTPS (port 443), w tym ruch kierowany do modułu edgeHub. Moduł serwera proxy interfejsu API jest domyślnie skonfigurowany do ponownego kierowania całego ruchu brzegowego w usłudze 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 tak, aby nie były powiązane 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ł serwera proxy interfejsu API do powiązania na porcie 443.

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

    2. Zaktualizuj opcje tworzenia kontenera, aby powiązać na porcie 443.

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

Jeśli nie musisz minimalizować otwartych portów, możesz zezwolić modułowi edgeHub na używanie portu 443 i konfigurowanie modułu serwera proxy interfejsu API do nasłuchiwania na innym porcie. Na przykład moduł serwera proxy interfejsu API może nasłuchiwać na porcie 8000, ustawiając wartość zmiennej 8000 środowiskowej NGINX_DEFAULT_PORT na i tworząc powiązanie portu dla portu 8000.

Włączanie pobierania obrazu kontenera

Typowym przypadkiem użycia modułu serwera proxy interfejsu API jest włączenie urządzeń usługi IoT Edge w niższych warstwach w celu ściągania 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, które mają być obsługiwane przez moduł rejestru w górnej warstwie.

Ten scenariusz wymaga, aby podrzędne urządzenia usługi IoT Edge wskazywały nazwę $upstream domeny, a następnie numer portu modułu serwera 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 Tworzenie hierarchii urządzeń usługi 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 uwidacznia port w module w celu odbierania żądań.
    • Skonfiguruj moduł do mapowania na rejestr kontenerów.
  • Moduł serwera proxy interfejsu API

    • Skonfiguruj następujące zmienne środowiskowe:

      Nazwa/nazwisko Wartość
      DOCKER_REQUEST_ROUTE_ADDRESS Nazwa modułu rejestru i otwórz 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 createOptions:

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

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

  • Moduł serwera proxy interfejsu 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 createOptions:

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

Uwidacznianie portu serwera proxy

Port 8000 jest domyślnie udostępniany z obrazu platformy Docker. Jeśli jest używany inny port serwera proxy nginx, dodaj sekcję ExposedPorts deklarując 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łączanie przekazywania obiektów blob

Innym przypadkiem użycia modułu serwera proxy interfejsu API jest włączenie urządzeń usługi IoT Edge w niższych warstwach w celu przekazywania obiektów blob. Ten przypadek użycia umożliwia rozwiązywanie problemów na urządzeniach niższej warstwy, takich jak przekazywanie dzienników modułów lub przekazywanie pakietu pomocy technicznej.

W tym scenariuszu usługa Azure Blob Storage w usłudze IoT Edge w górnej warstwie obsługuje tworzenie i przekazywanie obiektów blob. W scenariuszu zagnieżdżonym obsługiwane są maksymalnie pięć warstw. Moduł Azure Blob Storage w usłudze IoT Edge jest wymagany na urządzeniu warstwy górnej i opcjonalny dla urządzeń niższej warstwy. Przykładowe wdrożenie wielowarstwowe można znaleźć w przykładzie usługi Azure IoT Edge for Industrial IoT .

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

  • Moduł usługi Azure Blob Storage w usłudze IoT Edge.
  • Moduł serwera proxy interfejsu API

    • Skonfiguruj następujące zmienne środowiskowe:

      Nazwa/nazwisko Wartość
      BLOB_UPLOAD_ROUTE_ADDRESS Nazwa modułu usługi Blob Storage i otwórz 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 createOptions:

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

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

  • Moduł serwera proxy interfejsu 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 createOptions:

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

Wykonaj następujące kroki, aby przekazać pakiet pomocy technicznej lub plik dziennika do modułu magazynu obiektów blob znajdujących się w górnej warstwie:

  1. Utwórz kontener obiektów blob przy użyciu Eksplorator usługi Azure Storage lub interfejsów API REST. Aby uzyskać więcej informacji, zobacz Przechowywanie danych na urządzeniach brzegowych za pomocą usługi Azure Blob Storage w usłudze IoT Edge.

  2. Zażądaj przekazania dziennika lub pakietu pomocy technicznej zgodnie z instrukcjami w temacie Pobieranie dzienników z wdrożeń usługi IoT Edge, ale użyj nazwy $upstream domeny i otwartego portu serwera 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źniaczej reprezentacji modułu.

Podczas pisania własnej konfiguracji można nadal używać środowiska do dostosowywania ustawień na wdrożenie. Użyj następującej składni:

  • Użyj ${MY_ENVIRONMENT_VARIABLE} polecenia , aby pobrać 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 interfejsu API analizuje konfigurację serwera proxy, najpierw zastępuje wszystkie zmienne środowiskowe wymienione w PROXY_CONFIG_ENV_VAR_LIST podanych wartościach przy użyciu podstawienia. Następnie wszystkie elementy między parą a #if_tag #endif_tag są zastępowane. 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. Możesz użyć 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 w bliźniaczej reprezentacji modułu.

    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 usługi IoT Edge z bramą usługi Azure IoT Edge.