Partager via

Configuration du module proxy d’API pour un scénario de hiérarchie de passerelle

  • Article

S’applique à : Coche IoT Edge 1.5 IoT Edge 1.5 Coche IoT Edge 1.4 IoT Edge 1.4

Important

IoT Edge 1.5 LTS et IoT Edge 1.4 LTS sont des versions prises en charge. IoT Edge 1.4 LTS sera en fin de vie le 12 novembre 2024. Si vous utilisez une version antérieure, consultez l’article Mettre à jour IoT Edge.

Cet article présente les options de configuration pour le module proxy d’API qui vous permettent de le personnaliser conformément aux exigences de votre hiérarchie de passerelle.

Le module proxy d’API simplifie la communication pour les appareils IoT Edge lorsque plusieurs services sont déployés et qu’ils prennent tous en charge le protocole HTTPS et sont liés au port 443. Cela est particulièrement utile dans les déploiements hiérarchiques des appareils IoT Edge dans des architectures isolées du réseau basées sur ISA-95, comme celles décrites dans Appareils en aval isolés du réseau, car les clients sur les appareils en aval ne peuvent pas se connecter directement au cloud.

Par exemple, pour permettre aux appareils IoT Edge en aval de tirer des images Docker, vous devez déployer un module de registre Docker. Pour autoriser le téléchargement d’objets blob, vous devez déployer un module de Stockage Blob Azure sur le même appareil IoT Edge. Ces deux services utilisent le protocole HTTPS pour la communication. Le proxy d’API active ces déploiements sur un appareil IoT Edge. Au lieu de chaque service, le module de proxy d’API est lié au port 443 sur l’appareil hôte et achemine la requête vers le module de service correct exécuté sur cet appareil par des règles configurables par l’utilisateur. Les services individuels sont toujours responsables du traitement des demandes, y compris l’authentification et l’autorisation des clients.

Sans le proxy d’API, chaque module de service doit être lié à un port distinct sur l’appareil hôte, ce qui nécessite une modification de configuration fastidieuse et sujette aux erreurs sur chaque appareil enfant qui se connecte à l’appareil IoT Edge parent.

Remarque

Un appareil en aval émet des données directement vers Internet ou vers des appareils de passerelle (IoT Edge activés ou non). Un appareil enfant peut être un appareil en aval ou un appareil de passerelle dans une topologie imbriquée.

Déploiement du module proxy

Le module proxy d’API est disponible dans le Registre de conteneurs Microsoft (MCR) et l’URI de l’image est mcr.microsoft.com/azureiotedge-api-proxy:latest. Vous pouvez déployer le module à l’aide du Portail Azure ou d’Azure CLI.

Présentation du module proxy

Le module proxy d’API utilise un proxy inverse nginx pour acheminer les données à travers les couches réseau. Un proxy est incorporé dans le module. Par conséquent, l’image de module doit prendre en charge la configuration du proxy. Par exemple, si le proxy écoute un certain port, ce dernier doit être ouvert sur le module.

Le proxy commence par un fichier de configuration par défaut incorporé dans le module. Vous pouvez transmettre une nouvelle configuration au module à partir du cloud à l’aide de son jumeau de module. Il est également possible d’utiliser des variables d’environnement pour activer ou désactiver les paramètres de configuration au moment du déploiement.

Cet article se concentre d’abord sur le fichier de configuration par défaut et sur l’activation de ses paramètres au moyen des variables d'environnement. La personnalisation du fichier de configuration sera abordée à la fin.

Configuration par défaut

Le module proxy d’API est fourni avec une configuration par défaut qui prend en charge les scénarios courants et accepte la personnalisation. Il est possible de contrôler la configuration par défaut au moyen des variables d’environnement du module.

Actuellement, les variables d’environnement par défaut sont les suivantes :

Variable d’environnement Description
PROXY_CONFIG_ENV_VAR_LIST Liste toutes les variables à mettre à jour dans une liste séparée par des virgules. Cette étape empêche de modifier accidentellement les mauvais paramètres de configuration.
NGINX_DEFAULT_TLS Spécifie la liste des protocoles TLS à activer. Consultez ssl_protocols de NGINX.

La valeur par défaut est « TLSv1.2 ».
NGINX_DEFAULT_PORT Modifie le port écouté par le proxy nginx. Si vous mettez à jour cette variable d’environnement, vous devez exposer le port dans le fichier dockerfile du module et déclarer la liaison de port dans le manifeste de déploiement. Pour plus d’informations, consultez Exposer un port proxy.

La valeur par défaut est 443.

En cas de déploiement à partir de la Place de marché Azure, le port par défaut devient 8000 pour empêcher les conflits avec le module edgeHub. Pour plus d’informations, consultez Réduction des ports ouverts.
DOCKER_REQUEST_ROUTE_ADDRESS Adresse à laquelle sont acheminées les demandes Docker. Modifiez cette variable sur l’appareil de la couche supérieure de sorte qu’elle pointe vers le module registre.

La valeur par défaut est le nom d’hôte parent.
BLOB_UPLOAD_ROUTE_ADDRESS Adresse à laquelle sont acheminées les demandes du registre blob. Modifiez cette variable sur l’appareil de la couche supérieure de sorte qu’elle pointe vers le Stockage Blob.

La valeur par défaut est le nom d’hôte parent.

Réduction des ports ouverts

Pour réduire le nombre de ports ouverts, le module proxy d’API doit relayer tout le trafic HTTPS (port 443), y compris le trafic ciblant le module edgeHub. Il est configuré par défaut pour réacheminer tout le trafic edgeHub sur le port 443.

Pour configurer votre déploiement de façon à réduire les ports ouverts, procédez comme suit :

  1. Mettez à jour les paramètres du module edgeHub pour qu’ils ne soient pas liés au port 443, afin d’éviter des conflits de liaison de port. Par défaut, ce module est lié aux ports 443, 5671 et 8883. Supprimez la liaison du port 443 et conservez les deux autres :

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

  2. Configurez le module proxy d’API de sorte qu’il soit lié au port 443.

    1. Donnez à la variable d’environnement NGINX_DEFAULT_PORT la valeur 443.

    2. Mettez à jour les options de création de conteneur de façon à effectuer une liaison au port 443.

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

Si vous n’avez pas besoin de réduire les ports ouverts, vous pouvez laisser le module edgeHub utiliser le port 443 et configurer le module proxy d’API de sorte qu’il écoute un autre port. Par exemple, le module proxy d’API peut écouter le port 8000. Pour cela, donnez à la variable d’environnement NGINX_DEFAULT_PORT la valeur 8000 et créez une liaison pour le port 8000.

Téléchargement des images conteneur

L’un des cas d’usage courants du module proxy d’API consiste à permettre aux appareils IoT Edge des couches inférieures de tirer (pull) des images conteneur. Ce scénario utilise le module registre Docker pour récupérer les images conteneur à partir du cloud et les mettre en cache au niveau de la couche supérieure. Le proxy d’API relaie toutes les requêtes HTTPS pour télécharger à partir des couches inférieures une image conteneur, que le module registre devra traiter dans la couche supérieure.

Dans ce scénario, les appareils IoT Edge en aval doivent pointer vers le nom de domaine $upstream suivi du numéro de port du module proxy d’API, au lieu du registre de conteneurs d’une image. Par exemple : $upstream:8000/azureiotedge-api-proxy:1.1.

Ce cas d’usage est illustré dans le tutoriel Création d’une hiérarchie d’appareils IoT Edge à l’aide de passerelles.

Configurez les modules suivants au niveau de la couche supérieure :

  • Un module registre Docker
    • Configurez le module avec un nom facile à retenir (par exemple, registre), et exposez un port dans le module pour recevoir les demandes.
    • Configurez le module pour qu’il corresponde à votre registre de conteneurs.
  • Un module proxy d’API

    • Configurez les variables d’environnement suivantes :

      Nom Valeur
      DOCKER_REQUEST_ROUTE_ADDRESS Nom du module registre et port ouvert. Par exemple : registry:5000.
      NGINX_DEFAULT_PORT Port sur lequel le proxy nginx écoute les demandes des appareils en aval. Par exemple : 8000.

    • Configurez les options createOptions suivantes :

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

Configurez le module suivant sur n’importe quelle couche inférieure pour ce scénario :

  • Module de proxy d’API. Le module de proxy d’API est nécessaire sur tous les appareils de couche inférieure, à l’exception de l’appareil de la dernière couche.

    • Configurez les variables d’environnement suivantes :

      Nom Valeur
      NGINX_DEFAULT_PORT Port sur lequel le proxy nginx écoute les demandes des appareils en aval. Par exemple : 8000.

    • Configurez les options createOptions suivantes :

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

Exposer le port proxy

Le port 8000 est exposé par défaut à partir de l’image Docker. Si un autre port proxy nginx est utilisé, ajoutez la section ExposedPorts qui déclare le port dans le manifeste de déploiement. Par exemple, si vous remplacez le port proxy nginx par 8001, ajoutez ce qui suit au manifeste de déploiement :

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

Chargement d’objets blob

Il existe un autre cas d’usage courant du module proxy d’API : permettre aux appareils IoT Edge des couches inférieures de charger des objets blob. Sont ainsi activées les fonctionnalités de résolution des problèmes sur les appareils de couche inférieure, notamment le chargement des journaux de modules ou du Bundle de support.

Ce scénario utilise le module Stockage Blob Azure sur IoT Edge au niveau de la couche supérieure pour gérer la création et le chargement d’objets blob. Dans un scénario imbriqué, jusqu’à cinq couches sont prises en charge. Le module Stockage Blob Azure sur IoT Edge est nécessaire sur l’appareil de la couche supérieure et facultatif pour les appareils de couche inférieure. Pour obtenir un exemple de déploiement multicouche, consultez l’exemple Azure IoT Edge pour l’IoT industriel.

Configurez les modules suivants au niveau de la couche supérieure :

  • Un module Stockage Blob Azure sur IoT Edge
  • Un module proxy d’API

    • Configurez les variables d’environnement suivantes :

      Nom Valeur
      BLOB_UPLOAD_ROUTE_ADDRESS Nom du module Stockage Blob et port ouvert. Par exemple : azureblobstorageoniotedge:11002.
      NGINX_DEFAULT_PORT Port sur lequel le proxy nginx écoute les demandes des appareils en aval. Par exemple : 8000.

    • Configurez les options createOptions suivantes :

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

Configurez le module suivant sur n’importe quelle couche inférieure pour ce scénario :

  • Un module proxy d’API

    • Configurez les variables d’environnement suivantes :

      Nom Valeur
      NGINX_DEFAULT_PORT Port sur lequel le proxy nginx écoute les demandes des appareils en aval. Par exemple : 8000.

    • Configurez les options createOptions suivantes :

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

Pour charger le Bundle de support ou le fichier journal dans le module Stockage Blob situé dans la couche supérieure, procédez comme suit :

  1. Créez un conteneur d’objets blob à l’aide de l’Explorateur Stockage Azure ou des API REST. Pour plus d’informations, consultez Stockage de données en périphérie avec le Stockage Blob Azure sur IoT Edge.

  2. Demandez le chargement d’un journal ou d’un Bundle de support en suivant la procédure décrite dans Récupération de journaux à partir de déploiements IoT Edge, mais utilisez le nom de domaine $upstream et le port de proxy ouvert à la place de l’adresse du module Stockage Blob. Par exemple :

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

Modification de la configuration du proxy

Un fichier de configuration par défaut est incorporé dans le module proxy d’API. Il est cependant possible de transmettre une nouvelle configuration à ce module via le cloud à l’aide du jumeau de module.

Lorsque vous écrivez votre propre configuration, vous pouvez toujours utiliser l’environnement pour ajuster les paramètres de chaque déploiement. Utilisez la syntaxe suivante :

  • Utilisez ${MY_ENVIRONMENT_VARIABLE} pour récupérer la valeur d’une variable d’environnement.

  • Utilisez des instructions conditionnelles pour activer ou désactiver les paramètres en fonction de la valeur d’une variable d’environnement :

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

Lorsque le module proxy d’API analyse une configuration de proxy, il commence par remplacer toutes les variables d’environnement listées dans PROXY_CONFIG_ENV_VAR_LIST par les valeurs fournies à l’aide de la substitution. Ensuite, tout ce qui se trouve à l’intérieur de la paire #if_tag et #endif_tag est remplacé. Le module fournit alors la configuration analysée au proxy inverse nginx.

Pour mettre à jour la configuration du proxy de manière dynamique, procédez comme suit :

  1. Écrivez votre fichier de configuration. Vous pouvez utiliser ce modèle par défaut comme référence : nginx_default_config.conf.

  2. Copiez le texte du fichier de configuration et convertissez-le en base64.

  3. Collez le fichier de configuration encodé dans la valeur de la propriété proxy_config souhaitée du jumeau de module.

    Capture d’écran montrant comment coller le fichier config encodé comme valeur de la propriété proxy_config.

Étapes suivantes

Utilisez le module proxy d’API pour connecter un appareil IoT Edge en aval à une passerelle Azure IoT Edge.