De API-proxymodule configureren voor uw gatewayhiërarchiescenario

  • Artikel

Van toepassing op:IoT Edge 1.5-vinkje IoT Edge 1.5 Vinkje voor IoT Edge 1.4 IoT Edge 1.4

Belangrijk

IoT Edge 1.5 LTS en IoT Edge 1.4 LTS worden ondersteund releases. IoT Edge 1.4 LTS eindigt op 12 november 2024. Raadpleeg IoT Edge bijwerken als u een eerdere versie hebt.

In dit artikel worden de configuratieopties voor de API-proxymodule beschreven, zodat u de module kunt aanpassen ter ondersteuning van uw gatewayhiërarchievereisten.

De API-proxymodule vereenvoudigt de communicatie voor IoT Edge-apparaten wanneer meerdere services worden geïmplementeerd die allemaal ondersteuning bieden voor het HTTPS-protocol en verbinding maken met poort 443. Dit is met name relevant voor hiërarchische implementaties van IoT Edge-apparaten in op ISA-95 gebaseerde netwerkisolatiearchitecturen, zoals die worden beschreven in Network isolate downstream-apparaten , omdat de clients op de downstreamapparaten geen rechtstreeks verbinding kunnen maken met de cloud.

Als u bijvoorbeeld downstream IoT Edge-apparaten wilt toestaan docker-installatiekopieën op te halen, moet u een Docker-registermodule implementeren. Als u het uploaden van blobs wilt toestaan, moet u een Azure Blob Storage-module implementeren op hetzelfde IoT Edge-apparaat. Beide services gebruiken HTTPS voor communicatie. De API-proxy maakt dergelijke implementaties mogelijk op een IoT Edge-apparaat. In plaats van elke service wordt de API-proxymodule gekoppeld aan poort 443 op het hostapparaat en wordt de aanvraag gerouteerd naar de juiste servicemodule die op dat apparaat wordt uitgevoerd volgens de door de gebruiker configureerbare regels. De afzonderlijke services zijn nog steeds verantwoordelijk voor het verwerken van de aanvragen, waaronder het verifiëren en autoriseren van de clients.

Zonder de API-proxy moet elke servicemodule verbinding maken met een afzonderlijke poort op het hostapparaat. Hiervoor is een tijdrovende en foutgevoelige configuratiewijziging vereist op elk onderliggend apparaat dat verbinding maakt met het bovenliggende IoT Edge-apparaat.

Notitie

Een downstreamapparaat verzendt gegevens rechtstreeks naar internet of naar gatewayapparaten (ioT Edge ingeschakeld of niet). Een onderliggend apparaat kan een downstreamapparaat of een gatewayapparaat in een geneste topologie zijn.

De proxymodule implementeren

De API-proxymodule is beschikbaar via het Microsoft Container Registry (MCR): mcr.microsoft.com/azureiotedge-api-proxy:1.1.

U kunt de API-proxymodule ook rechtstreeks implementeren vanuit de Azure Marketplace: IoT Edge-API-proxy.

Inzicht in de proxymodule

De API-proxymodule maakt gebruik van een omgekeerde nginx-proxy om gegevens via netwerklagen te routeren. Een proxy is ingesloten in de module, wat betekent dat de module-installatiekopieën de proxyconfiguratie moeten ondersteunen. Als de proxy bijvoorbeeld luistert op een bepaalde poort, moet de module die poort openen.

De proxy begint met een standaardconfiguratiebestand dat is ingesloten in de module. U kunt een nieuwe configuratie doorgeven aan de module vanuit de cloud met behulp van de moduledubbel. Daarnaast kunt u omgevingsvariabelen gebruiken om configuratie-instellingen in of uit te schakelen tijdens de implementatie.

Dit artikel richt zich eerst op het standaardconfiguratiebestand en het gebruik van omgevingsvariabelen om de instellingen in te schakelen. Vervolgens bespreken we het aanpassen van het configuratiebestand aan het einde.

Standaardconfiguratie

De API-proxymodule wordt geleverd met een standaardconfiguratie die algemene scenario's ondersteunt en aanpassingen mogelijk maakt. U kunt de standaardconfiguratie beheren via omgevingsvariabelen van de module.

Op dit moment zijn de standaardomgevingsvariabelen:

Omgevingsvariabele Beschrijving
PROXY_CONFIG_ENV_VAR_LIST Vermeld alle variabelen die u wilt bijwerken in een door komma's gescheiden lijst. Met deze stap voorkomt u dat per ongeluk de verkeerde configuratie-instellingen worden gewijzigd.
NGINX_DEFAULT_TLS Hiermee geeft u de lijst met TLS-protocollen moet worden ingeschakeld. Zie de ssl_protocols van NGINX.

De standaardwaarde is TLSv1.2.
NGINX_DEFAULT_PORT Hiermee wijzigt u de poort waarnaar de nginx-proxy luistert. Als u deze omgevingsvariabele bijwerkt, moet u de poort beschikbaar maken in de dockerfile van de module en de poortbinding declareren in het implementatiemanifest. Zie Proxypoort beschikbaar maken voor meer informatie.

De standaardwaarde is 443.

Wanneer deze wordt geïmplementeerd vanuit Azure Marketplace, wordt de standaardpoort bijgewerkt naar 8000, om conflicten met de EdgeHub-module te voorkomen. Zie Open poorten minimaliseren voor meer informatie.
DOCKER_REQUEST_ROUTE_ADDRESS Adres voor het routeren van Docker-aanvragen. Wijzig deze variabele op het apparaat in de bovenste laag zodat deze verwijst naar de registermodule.

De standaardwaarde is de bovenliggende hostnaam.
BLOB_UPLOAD_ROUTE_ADDRESS Adres voor het routeren van blobregisteraanvragen. Wijzig deze variabele op het apparaat in de bovenste laag zodat deze verwijst naar de blobopslagmodule.

De standaardwaarde is de bovenliggende hostnaam.

Open poorten minimaliseren

Om het aantal geopende poorten te minimaliseren, moet de API-proxymodule al het HTTPS-verkeer (poort 443) doorsturen, inclusief verkeer dat gericht is op de edgeHub-module. De API-proxymodule is standaard geconfigureerd om alle edgeHub-verkeer op poort 443 opnieuw te routeren.

Gebruik de volgende stappen om uw implementatie te configureren om open poorten te minimaliseren:

  1. Werk de edgeHub-module-instellingen bij om niet te binden op poort 443, anders zijn er poortbindingsconflicten. De EdgeHub-module verbindt standaard op poorten 443, 5671 en 8883. Verwijder de poort 443-binding en laat de andere twee binding staan:

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

  2. Configureer de API-proxymodule om verbinding te maken op poort 443.

    1. Stel de waarde van de omgevingsvariabele NGINX_DEFAULT_PORT in op 443.

    2. Werk de opties voor het maken van containers bij om verbinding te maken op poort 443.

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

Als u open poorten niet hoeft te minimaliseren, kunt u de EdgeHub-module poort 443 laten gebruiken en de API-proxymodule configureren om op een andere poort te luisteren. De API-proxymodule kan bijvoorbeeld luisteren op poort 8000 door de waarde van de omgevingsvariabele NGINX_DEFAULT_PORT in te 8000 stellen op en een poortbinding te maken voor poort 8000.

Downloaden van containerinstallatiekopieën inschakelen

Een veelvoorkomend gebruiksvoorbeeld voor de API-proxymodule is het inschakelen van IoT Edge-apparaten in lagere lagen om containerinstallatiekopieën op te halen. In dit scenario wordt de Docker-registermodule gebruikt om containerinstallatiekopieën op te halen uit de cloud en deze in de cache op te slaan op de bovenste laag. De API-proxy stuurt alle HTTPS-aanvragen door om een containerinstallatiekopieën te downloaden van de lagere lagen die worden geleverd door de registermodule in de bovenste laag.

Voor dit scenario moeten downstream IoT Edge-apparaten verwijzen naar de domeinnaam $upstream , gevolgd door het poortnummer van de API-proxymodule in plaats van het containerregister van een installatiekopieën. Voorbeeld: $upstream:8000/azureiotedge-api-proxy:1.1.

Deze use case wordt gedemonstreerd in de zelfstudie Een hiërarchie van IoT Edge-apparaten maken met behulp van gateways.

Configureer de volgende modules op de bovenste laag:

  • Een Docker-registermodule
    • Configureer de module met een gedenkwaardige naam, zoals register , en stel een poort beschikbaar in de module om aanvragen te ontvangen.
    • Configureer de module om toe te wijzen aan uw containerregister.
  • Een API-proxymodule

    • Configureer de volgende omgevingsvariabelen:

      Naam Weergegeven als
      DOCKER_REQUEST_ROUTE_ADDRESS De naam van de registermodule en de poort openen. Bijvoorbeeld: registry:5000.
      NGINX_DEFAULT_PORT De poort waarop de nginx-proxy luistert voor aanvragen van downstreamapparaten. Bijvoorbeeld: 8000.

    • Configureer de volgende createOptions:

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

Configureer de volgende module op een lagere laag voor dit scenario:

  • API-proxymodule. De API-proxymodule is vereist op alle apparaten met een lagere laag, met uitzondering van het apparaat met de onderste laag.

    • Configureer de volgende omgevingsvariabelen:

      Naam Weergegeven als
      NGINX_DEFAULT_PORT De poort waarop de nginx-proxy luistert voor aanvragen van downstreamapparaten. Bijvoorbeeld: 8000.

    • Configureer de volgende createOptions:

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

Proxypoort beschikbaar maken

Poort 8000 wordt standaard weergegeven vanuit de docker-installatiekopieën. Als er een andere nginx-proxypoort wordt gebruikt, voegt u de sectie ExposedPorts toe die de poort declareren in het implementatiemanifest. Als u bijvoorbeeld de nginx-proxypoort wijzigt in 8001, voegt u het volgende toe aan het implementatiemanifest:

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

Blob-upload inschakelen

Een ander gebruiksvoorbeeld voor de API-proxymodule is om IoT Edge-apparaten in lagere lagen in staat te stellen blobs te uploaden. Met deze use case kunt u problemen oplossen op apparaten met een lagere laag, zoals het uploaden van modulelogboeken of het uploaden van de ondersteuningsbundel.

In dit scenario wordt de Azure Blob Storage-module in IoT Edge op de bovenste laag gebruikt om het maken en uploaden van blobs af te handelen. In een genest scenario worden maximaal vijf lagen ondersteund. De Module Azure Blob Storage in IoT Edge is vereist op het apparaat in de bovenste laag en optioneel voor apparaten met een lagere laag. Zie het Azure IoT Edge voor industriële IoT-voorbeeld voor een voorbeeldimplementatie met meerdere lagen.

Configureer de volgende modules op de bovenste laag:

  • Een Azure Blob Storage-module in IoT Edge.
  • Een API-proxymodule

    • Configureer de volgende omgevingsvariabelen:

      Naam Weergegeven als
      BLOB_UPLOAD_ROUTE_ADDRESS De naam van de blob storage-module en open de poort. Bijvoorbeeld: azureblobstorageoniotedge:11002.
      NGINX_DEFAULT_PORT De poort waarop de nginx-proxy luistert voor aanvragen van downstreamapparaten. Bijvoorbeeld: 8000.

    • Configureer de volgende createOptions:

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

Configureer de volgende module op een lagere laag voor dit scenario:

  • Een API-proxymodule

    • Configureer de volgende omgevingsvariabelen:

      Naam Weergegeven als
      NGINX_DEFAULT_PORT De poort waarop de nginx-proxy luistert voor aanvragen van downstreamapparaten. Bijvoorbeeld: 8000.

    • Configureer de volgende createOptions:

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

Gebruik de volgende stappen om de ondersteuningsbundel of het logboekbestand te uploaden naar de blobopslagmodule op de bovenste laag:

  1. Maak een blobcontainer met behulp van Azure Storage Explorer of de REST API's. Zie Gegevens opslaan aan de rand met Azure Blob Storage in IoT Edge voor meer informatie.

  2. Vraag een logboek- of ondersteuningsbundelupload aan volgens de stappen in Logboeken ophalen uit IoT Edge-implementaties, maar gebruik de domeinnaam $upstream en de open proxypoort in plaats van het adres van de blob-opslagmodule. Voorbeeld:

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

De proxyconfiguratie bewerken

Een standaardconfiguratiebestand is ingesloten in de API-proxymodule, maar u kunt een nieuwe configuratie doorgeven aan de module via de cloud met behulp van de moduledubbel.

Wanneer u uw eigen configuratie schrijft, kunt u de omgeving nog steeds gebruiken om instellingen per implementatie aan te passen. Gebruik de volgende syntaxis:

  • Gebruik ${MY_ENVIRONMENT_VARIABLE} dit om de waarde van een omgevingsvariabele op te halen.

  • Gebruik voorwaardelijke instructies om instellingen in of uit te schakelen op basis van de waarde van een omgevingsvariabele:

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

Wanneer de API-proxymodule een proxyconfiguratie parseert, vervangt deze eerst alle omgevingsvariabelen die worden vermeld in de PROXY_CONFIG_ENV_VAR_LIST door hen opgegeven waarden met vervanging. Vervolgens wordt alles tussen een #if_tag en #endif_tag paar vervangen. De module biedt vervolgens de geparseerde configuratie aan de omgekeerde nginx-proxy.

Als u de proxyconfiguratie dynamisch wilt bijwerken, gebruikt u de volgende stappen:

  1. Schrijf uw configuratiebestand. U kunt deze standaardsjabloon gebruiken als referentie: nginx_default_config.conf

  2. Kopieer de tekst van het configuratiebestand en converteer het naar base64.

  3. Plak het gecodeerde configuratiebestand als de waarde van de proxy_config gewenste eigenschap in de moduledubbel.

    Schermopname van het plakken van een gecodeerd configuratiebestand als waarde van proxy_config eigenschap.

Volgende stappen

Gebruik de API-proxymodule om een downstream IoT Edge-apparaat te Verbinding maken naar een Azure IoT Edge-gateway.