Configurer un appareil IoT Edge pour communiquer via un serveur proxy

S’applique à : IoT Edge 1.5

Les appareils IoT Edge envoient des requêtes HTTPS pour communiquer avec IoT Hub. Si votre appareil se connecte à un réseau qui utilise un serveur proxy, configurez le runtime IoT Edge pour communiquer via le serveur. Les serveurs proxy peuvent également affecter des modules IoT Edge individuels s’ils effectuent des requêtes HTTP ou HTTPS qui ne sont pas routées via le hub IoT Edge.

Cet article explique les quatre étapes à suivre pour configurer et gérer un appareil IoT Edge derrière un serveur proxy :

1. Installer le runtime IoT Edge sur votre appareil

   Les scripts d’installation IoT Edge extrayent des packages et des fichiers à partir d’Internet, de sorte que l’appareil communique via le serveur proxy pour effectuer ces requêtes. Pour les appareils Windows, le script d’installation fournit également une option d’installation hors connexion.

   Vous n’effectuerez la configuration décrite dans cette étape qu’une seule fois lors de la première installation de votre appareil IoT Edge. Vous avez besoin de ces connexions quand vous mettez à jour le runtime IoT Edge.

2. Configurer IoT Edge et le runtime du conteneur sur votre appareil

   IoT Edge gère les communications avec IoT Hub. Le runtime de conteneur gère les conteneurs et communique avec les registres de conteneurs. Ces deux composants doivent effectuer des demandes web via le serveur proxy.

   Vous n’effectuerez la configuration décrite dans cette étape qu’une seule fois lors de la première installation de votre appareil IoT Edge.

3. Configurer les propriétés de l’agent IoT Edge dans le fichier config sur votre appareil

   Le démon IoT Edge démarre initialement le module edgeAgent. Ensuite, le module edgeAgent récupère le manifeste de déploiement à partir de IoT Hub et démarre tous les autres modules. Configurez manuellement les variables d’environnement de module edgeAgent sur l’appareil afin que l’agent IoT Edge établit la connexion initiale à IoT Hub. Une fois la première connexion effectuée, vous pouvez configurer le module edgeAgent à distance.

   Vous n’effectuerez la configuration décrite dans cette étape qu’une seule fois lors de la première installation de votre appareil IoT Edge.

4. Pour tous vos futurs déploiements de module, définissez des variables d’environnement pour chaque module communiquant via le proxy

   Après avoir configuré et connecté un appareil IoT Edge à IoT Hub via le serveur proxy, conservez la connexion dans tous les futurs déploiements de modules.

   Cette étape est un processus continu à effectuer à distance afin que chaque nouvelle mise à jour de module ou de déploiement conserve la capacité de l’appareil à communiquer via le serveur proxy.

Identifier l’URL de votre proxy

Avant de commencer les étapes décrites dans cet article, connaissez l’URL de votre proxy.

Les URL proxy utilisent le format suivant : protocole ://proxy_host :proxy_port.

• Le paramètre protocol a la valeur HTTP ou HTTPS. Le démon Docker peut utiliser l’un ou l’autre protocole en fonction des paramètres de votre registre de conteneurs, mais les démons IoT Edge et les conteneurs d’exécution utilisent toujours HTTP pour se connecter au proxy.

• Le proxy_host est l’adresse du serveur proxy. Si le serveur proxy nécessite une authentification, fournissez vos informations d’identification dans le cadre de l’hôte proxy au format suivant : user :password@proxy_host.

• Le proxy_port est le port réseau où le proxy répond au trafic.

Installer IoT Edge via un proxy

Que votre appareil IoT Edge s’exécute sur Windows ou Linux, accédez aux packages d’installation via le serveur proxy. Pour installer le runtime IoT Edge via un serveur proxy, suivez les étapes correspondant à votre système d’exploitation.

Appareils Linux

Si vous installez le runtime IoT Edge sur un appareil Linux, configurez le gestionnaire de package pour utiliser votre serveur proxy pour accéder au package d’installation. Par exemple, Configurez apt-get pour utiliser un proxy http. Après avoir configuré votre gestionnaire de package, suivez les instructions de l’installation du runtime Azure IoT Edge.

Appareils Windows avec IoT Edge pour Linux sur Windows

Si vous installez le runtime IoT Edge à l’aide d’IoT Edge pour Linux sur Windows, le runtime IoT Edge est installé par défaut sur votre machine virtuelle Linux. Vous n’êtes pas obligé d’installer ou de mettre à jour les autres étapes.

Appareils Windows utilisant des conteneurs Windows

Si vous installez le runtime IoT Edge sur un appareil Windows, vous devez passer deux fois par le serveur proxy. La première connexion télécharge le fichier de script du programme d’installation et la deuxième connexion télécharge les composants nécessaires pendant l’installation. Vous pouvez configurer les informations de proxy dans les paramètres Windows ou inclure vos informations de proxy directement dans les commandes PowerShell.

Les étapes suivantes illustrent un exemple d’installation de Windows à l’aide de l’argument -proxy :

1. La commande Invoke-WebRequest a besoin des informations de proxy pour accéder au script du programme d’installation. Ensuite, la commande Deploy-IoTEdge a besoin des informations de proxy pour télécharger les fichiers d’installation.

   . {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
   

2. La commande Initialize-IoTEdge n’a pas besoin de transiter par le serveur proxy, alors seule la commande Invoke-WebRequest doit disposer des informations de proxy lors de la seconde étape.

   . {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
   

Si vos informations d’identification de serveur proxy sont complexes et ne peuvent pas être incluses dans l’URL, utilisez le -ProxyCredential paramètre dans -InvokeWebRequestParameters. Par exemple,

$proxyCredential = (Get-Credential).GetNetworkCredential()
. {Invoke-WebRequest -proxy <proxy URL> -ProxyCredential $proxyCredential -useb aka.ms/iotedge-win} | Invoke-Expression; `
Deploy-IoTEdge -InvokeWebRequestParameters @{ '-Proxy' = '<proxy URL>'; '-ProxyCredential' = $proxyCredential }

Pour plus d’informations sur les paramètres de proxy, consultez Invoke-WebRequest.

Configurer IoT Edge et Moby

IoT Edge utilise deux démons s’exécutant sur l’appareil IoT Edge. Le démon Moby extrait des images conteneur à partir de registres de conteneurs. Le démon IoT Edge communique avec IoT Hub.

Configurer les démons Moby et IoT Edge pour utiliser le serveur proxy pour le fonctionnement continu des appareils. Effectuez cette étape sur l’appareil IoT Edge lors de la configuration initiale.

Démon Moby

Étant donné que Moby est basé sur Docker, consultez la documentation Docker pour configurer le démon Moby avec des variables d’environnement. La plupart des registres de conteneurs, notamment DockerHub et Azure Container Registrys, prennent en charge les requêtes HTTPS. Définissez donc le paramètre HTTPS_PROXY . Si vous tirez des images d’un registre qui ne prend pas en charge le protocole TLS, vous devez définir le paramètre HTTP_PROXY.

Sélectionnez l’article qui s’applique à votre système d’exploitation d’appareil IoT Edge :

• Configurer le démon Docker sur Linux Sur les appareils Linux, le démon Moby est toujours appelé Docker.
• Configurez le démon Docker sur Windows Le démon Moby s’appelle iotedge-moby sur les appareils Windows. Les noms sont différents, car il est possible d’exécuter simultanément Docker Desktop et Moby sur un appareil Windows.

Démon IoT Edge

Le démon IoT Edge est similaire au démon Moby. Suivez les étapes ci-dessous afin de définir une variable d’environnement pour le service, selon votre système d’exploitation.

Le démon IoT Edge utilise toujours le protocole HTTPS pour envoyer des demandes à IoT Hub.

Linux

Dans le terminal, ouvrez un éditeur pour configurer le démon IoT Edge.

sudo systemctl edit aziot-edged

Entrez le texte suivant, en remplaçant <proxy URL> par l’adresse et le port de votre serveur proxy. Ensuite, enregistrez et quittez.

[Service]
Environment="https_proxy=<proxy URL>"

Depuis la version 1.2, IoT Edge utilise le service d’identité IoT pour gérer l’approvisionnement d’appareil avec IoT Hub ou le service IoT Hub Device Provisioning. Ouvrez un éditeur dans le terminal pour configurer le démon de service d’identité IoT.

sudo systemctl edit aziot-identityd

Entrez le texte suivant, en remplaçant <proxy URL> par l’adresse et le port de votre serveur proxy. Ensuite, enregistrez et quittez.

[Service]
Environment="https_proxy=<proxy URL>"

Actualisez le gestionnaire de services pour sélectionner les nouvelles configurations.

sudo systemctl daemon-reload

Redémarrez les services IoT Edge pour appliquer les modifications aux deux processus en arrière-plan.

sudo iotedge system restart

Vérifiez que vos variables d’environnement et la nouvelle configuration sont présentes.

systemctl show --property=Environment aziot-edged
systemctl show --property=Environment aziot-identityd

Windows avec IoT Edge pour Linux sur Windows

Connectez-vous à IoT Edge pour Linux sur une machine virtuelle Windows :

Connect-EflowVm

Suivez les mêmes étapes que celles de la section Linux de cet article pour configurer le démon IoT Edge.

Windows utilisant des conteneurs Windows

Ouvrez une fenêtre PowerShell en tant qu’administrateur et exécutez la commande suivante pour modifier le registre avec la nouvelle variable d’environnement. Remplacez <proxy url> par l’adresse et le port de votre serveur proxy.

reg add HKLM\SYSTEM\CurrentControlSet\Services\iotedge /v Environment /t REG_MULTI_SZ /d https_proxy=<proxy URL>

Redémarrez IoT Edge pour que les modifications soient prises en compte.

Restart-Service iotedge

Configurer l’agent IoT Edge

L’agent IoT Edge est le premier module démarré sur un appareil IoT Edge. Ce module démarre pour la première fois avec les informations du fichier config IoT Edge. L’agent IoT Edge se connecte ensuite à IoT Hub pour récupérer les manifestes de déploiement. Le manifeste déclare les autres modules que l’appareil doit déployer.

Cette étape s’effectue une seule fois sur l’appareil IoT Edge pendant la première installation de l’appareil.

1. Ouvrez le fichier config sur votre appareil IoT Edge : /etc/aziot/config.toml. Vous avez besoin de privilèges administratifs pour accéder au fichier config. Sur les systèmes Linux, utilisez la commande sudo avant d’ouvrir le fichier dans votre éditeur de texte habituel.

2. Dans le fichier config, recherchez la section [agent] qui contient toutes les informations de configuration du module edgeAgent à utiliser au démarrage. Vérifiez que la [agent] section n’a pas de commentaires. Si la section [agent] est manquante, ajoutez-la à config.toml. La définition de l’agent IoT Edge inclut une sous-section [agent.env] dans laquelle vous pouvez ajouter des variables d’environnement.

3. Ajoutez le paramètre https_proxy à la section variables d’environnement et définissez l’URL de votre proxy comme valeur.

   [agent]
   name = "edgeAgent"
   type = "docker"
   
   [agent.config]
   image = "mcr.microsoft.com/azureiotedge-agent:1.5"
   
   [agent.env]
   # RuntimeLogLevel = "debug"
   # UpstreamProtocol = "AmqpWs"
   https_proxy = "<proxy URL>"
   

4. Le runtime IoT Edge utilise AMQP par défaut pour communiquer avec IoT Hub. Certains serveurs proxy bloquent les ports AMQP. Si c’est le cas, vous devez également configurer edgeAgent pour utiliser AMQP sur WebSocket. Supprimez le commentaire du paramètre UpstreamProtocol.

   [agent.config]
   image = "mcr.microsoft.com/azureiotedge-agent:1.5"
   
   [agent.env]
   # RuntimeLogLevel = "debug"
   UpstreamProtocol = "AmqpWs"
   https_proxy = "<proxy URL>"
   

5. Ajoutez le paramètre https_proxy à la section des variables d’environnement, puis définissez l’URL de votre proxy comme valeur.

   [agent]
   name = "edgeAgent"
   type = "docker"
   
   [agent.config]
   image = "mcr.microsoft.com/azureiotedge-agent:1.5"
   
   [agent.env]
   # RuntimeLogLevel = "debug"
   # UpstreamProtocol = "AmqpWs"
   https_proxy = "<proxy URL>"
   

6. Le runtime IoT Edge utilise AMQP par défaut pour communiquer avec IoT Hub. Certains serveurs proxy bloquent les ports AMQP. Si c’est le cas, vous devez également configurer edgeAgent pour utiliser AMQP sur WebSocket. Supprimez les marques de commentaire du paramètre UpstreamProtocol.

   [agent.config]
   image = "mcr.microsoft.com/azureiotedge-agent:1.5"
   
   [agent.env]
   # RuntimeLogLevel = "debug"
   UpstreamProtocol = "AmqpWs"
   https_proxy = "<proxy URL>"
   

7. Enregistrez les modifications et fermez l'éditeur. Appliquez les modifications.

   sudo iotedge config apply
   

8. Vérifiez que les paramètres du proxy sont appliqués à l’aide de docker inspect edgeAgent dans la section Env. Sinon, vous devez recréer le conteneur.

   sudo docker rm -f edgeAgent
   

9. Le runtime IoT Edge recrée edgeAgent dans un délai d’une minute. Une fois le conteneur edgeAgent de nouveau en cours d’exécution, utilisez la commande docker inspect edgeAgent pour vérifier que les paramètres de proxy correspondent au fichier config.

Configurer les manifestes de déploiement

Après avoir configuré votre appareil IoT Edge pour qu’il fonctionne avec votre serveur proxy, déclarez la variable d’environnement HTTPS_PROXY dans les futurs manifestes de déploiement. Vous pouvez modifier les manifestes de déploiement à l’aide de l’Assistant du portail Azure ou en modifiant un fichier JSON de déploiement de manifeste.

Configurez toujours les deux modules runtime, edgeAgent et edgeHub, pour communiquer via le serveur proxy afin qu’ils conservent une connexion avec IoT Hub. Si vous supprimez les informations du proxy du module edgeAgent, la seule façon de rétablir la connexion consiste à modifier le fichier de configuration sur l’appareil, comme décrit dans la section précédente.

Outre les modules edgeAgent et edgeHub, d’autres modules peuvent nécessiter la configuration du proxy. Les modules qui accèdent aux ressources Azure en plus d’IoT Hub, comme le stockage d’objets blob, doivent spécifier la variable HTTPS_PROXY dans le fichier manifeste de déploiement.

Cette procédure s’applique tout au long de la durée de vie de l’appareil IoT Edge.

Portail Azure

Quand vous créez des déploiements sur des appareils IoT Edge à l’aide de l’Assistant Définir des modules, chaque module a une section Variables d’environnement dans laquelle vous pouvez configurer des connexions au serveur proxy.

Pour configurer les modules de l’agent IoT Edge et du hub IoT Edge, sélectionnez Paramètres d'exécution à la première étape de l’Assistant.

Ajoutez la variable d’environnement https_proxy aux définitions de paramètres de runtime des modules Hub IoT Edge et de l’agent IoT Edge . Si vous incluez la variable d’environnement UpstreamProtocol dans le fichier de configuration sur votre appareil IoT Edge, ajoutez-la également à la définition du module d’agent IoT Edge.

Tous les autres modules que vous ajoutez à un manifeste de déploiement suivent le même modèle. Sélectionnez Appliquer pour enregistrer vos modifications.

Fichiers de manifeste de déploiement JSON

Quand vous créez des déploiements sur des appareils IoT Edge en utilisant des modèles dans Visual Studio Code ou en créant manuellement des fichiers JSON, vous pouvez ajouter les variables d’environnement directement à chaque définition de module. Si vous ne les avez pas ajoutés dans le portail Azure, ajoutez-les ici à votre fichier manifeste JSON. Remplacez <proxy URL> par votre valeur.

Utilisez le format JSON suivant :

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    }
}

Avec les variables d’environnement incluses, la définition du module ressemble à l’exemple edgeHub suivant :

"edgeHub": {
    "type": "docker",
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
        "createOptions": "{}"
    },
    "env": {
        "https_proxy": {
            "value": "http://proxy.example.com:3128"
        }
    },
    "status": "running",
    "restartPolicy": "always"
}

Si vous avez inclus la variable d’environnement UpstreamProtocol dans le fichier config.yaml sur votre appareil IoT Edge, ajoutez-la également à la définition du module de l’agent IoT Edge.

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    },
    "UpstreamProtocol": {
        "value": "AmqpWs"
    }
}

Utilisation de proxys d’inspection du trafic

Certains proxys comme Zscaler peuvent inspecter le trafic chiffré TLS. Pendant l’inspection du trafic TLS, le certificat retourné par le proxy n’est pas le certificat du serveur cible, mais il est plutôt le certificat signé par le propre certificat racine du proxy. Par défaut, les modules IoT Edge (y compris edgeAgent et edgeHub) ne font pas confiance à ce certificat de proxy et la négociation TLS échoue.

Pour corriger l’échec de l’échange, configurez à la fois le système d’exploitation et les modules IoT Edge pour approuver le certificat racine du proxy en suivant ces étapes.

1. Configurez le certificat proxy dans le magasin de certificats racine approuvé de votre système d’exploitation hôte. Pour plus d’informations sur l’installation d’un certificat racine, consultez Installer l’autorité de certification racine sur le magasin de certificats du système d’exploitation.

2. Configurez votre appareil IoT Edge pour communiquer via un serveur proxy en référençant le certificat dans le bundle d’approbation. Pour plus d’informations sur la configuration de l’ensemble de certificats de confiance, consultez Gérer l’autorité de certification racine approuvée (ensemble de certificats de confiance).

Pour configurer la prise en charge du proxy d’inspection du trafic pour les conteneurs non gérés par IoT Edge, contactez votre fournisseur proxy.

Les noms de domaine complets (FQDN) des destinations avec lesquelles IoT Edge communique.

Si votre pare-feu proxy nécessite l'ajout de tous les noms de domaine complets à votre liste d’autorisation pour la connectivité Internet, consultez la section Autoriser les connexions depuis les appareils IoT Edge pour déterminer quels noms de domaine complets ajouter.

Étapes suivantes

Découvrez les rôles du runtime IoT Edge.

Résolvez les erreurs d’installation et de configuration dans les problèmes courants et les résolutions pour Azure IoT Edge.