Configurer un appareil IoT Edge pour communiquer via un serveur proxy

Article
05/03/2024

S’applique à : IoT Edge 1.5 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.

Les appareils IoT Edge envoient des requêtes HTTPS pour communiquer avec IoT Hub. Si vous avez connecté votre appareil à un réseau qui utilise un serveur proxy, vous devez configurer le runtime IoT Edge pour qu’il communique avec le serveur. Les serveurs proxy peuvent également affecter des modules IoT Edge individuels s’ils envoient des requêtes HTTP ou HTTPS que vous n’avez pas routées dans le hub IoT Edge.

Cet article vous montre la procédure en quatre étapes à suivre pour configurer et gérer un appareil IoT Edge derrière un serveur proxy :

Installer le runtime IoT Edge sur votre appareil

Les scripts d’installation d’IoT Edge extraient les packages et les fichiers à partir d’Internet. Votre appareil doit donc communiquer via le serveur proxy pour envoyer ces demandes. 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.
Configurer IoT Edge et le runtime du conteneur sur votre appareil

IoT Edge est responsable des communications avec IoT Hub. Le runtime du conteneur est responsable de la gestion de celui-ci. Il communique donc 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.
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 du module edgeAgent directement sur l’appareil pour que l’agent IoT Edge puisse établir 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.
Pour tous vos futurs déploiements de module, définissez des variables d’environnement pour chaque module communiquant via le proxy

Une fois que vous avez configuré et connecté un appareil IoT Edge à IoT Hub en utilisant le serveur proxy, vous devez maintenir la connexion dans tous les futurs déploiements de module.

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 l’une des étapes de cet article, vous devez connaître l’URL de votre proxy.

Les URL de proxy se présentent sous ce format : protocol://proxy_host:proxy_port.

Le paramètre protocol a la valeur HTTP ou HTTPS. Le démon Docker peut utiliser chacun de ces protocoles, selon vos paramètres de registre de conteneurs, mais les conteneurs de runtime et le démon IoT Edge doivent toujours utiliser HTTP pour se connecter au proxy.
Le paramètre proxy_host est une adresse du serveur proxy. Si votre serveur proxy requiert une authentification, vous pouvez fournir vos informations d’identification à l’aide de l’hôte de proxy au format suivant : user:password@proxy_host.
proxy_port représente le port réseau à partir duquel le proxy répond au trafic réseau.

Installer IoT Edge via un proxy

Si vous exécutez votre appareil IoT Edge sur Windows ou Linux, vous devez accéder 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 de sorte à passer par votre serveur proxy pour accéder au package d’installation. Par exemple, Configurez apt-get pour utiliser un proxy http. Dès que votre gestionnaire de package est configuré, suivez les instructions dans Installer le runtime Azure IoT Edge comme d’habitude.

Appareils Windows avec IoT Edge pour Linux sur Windows

Si vous installez le runtime IoT Edge à l’aide de IoT Edge pour Linux sur Windows, 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 seconde survient pendant l’installation afin de télécharger les composants nécessaires. 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 sous Windows qui utilise l’argument -proxy :

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>
```
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 vous avez des informations d’identification complexes pour le serveur proxy que vous ne pouvez pas inclure dans l’URL, utilisez le paramètre -ProxyCredential 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 s’appuie sur deux démons s’exécutant sur l’appareil IoT Edge. Le démon Moby effectue des requêtes web pour extraire les images conteneur des registres de conteneurs. Le démon IoT Edge effectue des requêtes web pour communiquer avec IoT Hub.

Vous devez configurer les démons Moby et IoT Edge pour qu’ils utilisent le serveur proxy afin d’assurer la fonctionnalité continue de l’appareil. Cette étape s’effectue sur l’appareil IoT Edge pendant la première installation de l’appareil.

Démon Moby

Étant donné que Moby est basé sur Docker, consultez la documentation sur Docker pour savoir comment configurer le démon Moby avec des variables d’environnement. La plupart des registres de conteneurs (y compris les registres de conteneurs DockerHub et Azure) prennent en charge les requêtes HTTPS. Vous devez donc définir 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.

Choisissez l’article correspondant au système d’exploitation de votre appareil IoT Edge :

Configurez le démon Docker sur Linux Le démon Mobyx garde le nom Docker sur les appareils Linux.
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

Ouvrez un éditeur dans le terminal 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 système IoT Edge pour que les modifications apportées aux deux démons prennent effet.

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 à votre machine virtuelle IoT Edge pour Linux sur 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.

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.
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 section [agent] 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.

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>"

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>"
```

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>"

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>"
```
Enregistrez les modifications et fermez l'éditeur. Appliquez vos dernière modifications.
```
sudo iotedge config apply
```
Vérifiez que vos paramètres de proxy sont propagés à l’aide de docker inspect edgeAgent dans la section Env. Sinon, vous devez recréer le conteneur.
```
sudo docker rm -f edgeAgent
```
Le runtime IoT Edge doit recréer 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

Dès que vous avez configuré votre appareil IoT Edge pour qu’il fonctionne avec votre serveur proxy, déclarez la variable d’environnement HTTPS_PROXY dans les manifestes des futurs déploiements. 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.

Vous devez toujours configurer les deux modules de runtime, edgeAgent et edgeHub, pour communiquer via le serveur proxy afin qu’ils puissent conserver une connexion avec IoT Hub. Si vous supprimez les informations de proxy du module edgeAgent, vous ne pouvez rétablir la connexion qu’en modifiant le fichier config 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 doivent accéder aux ressources Azure en plus d’IoT Hub, comme le stockage Blob, et pour lesquels la variable HTTPS_PROXY doit être spécifiée dans le fichier manifeste de déploiement.

La procédure suivante 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.

Capture d’écran montrant comment configurer les paramètres avancés du runtime Edge.

Ajoutez la variable d’environnement https_proxy aux définitions des paramètres de runtime de l’agent IoT Edge et du module Hub IoT Edge. Si vous avez inclus la variable d’environnement UpstreamProtocol dans le fichier config sur votre appareil IoT Edge, ajoutez-la également à la définition du module de l’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 propre valeur.

Utilisez le format JSON suivant :

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

Après l’ajout des variables d’environnement, votre définition de module doit ressembler à 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 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 résoudre l’échec de la négociation, configurez le système d’exploitation et les modules IoT Edge pour qu’ils approuvent le certificat racine du proxy avec les étapes suivantes.

Configurez un 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.
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’offre groupée d’approbations, consultez Gérer l’autorité de certification racine approuvée (offre groupée d’approbations).

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 de proxy.

Noms de domaine complets (FQDN) des destinations avec lesquelles IoT Edge communique

Si le pare-feu de votre proxy nécessite l’ajout de tous les FQDN à votre liste d’autorisation pour la connectivité Internet, passez en revue la liste dans Autoriser les connexions à partir d’appareils IoT Edge pour déterminer les FQDN à ajouter.

Étapes suivantes

En savoir plus sur les rôles du runtime IoT Edge

Résoudre les erreurs d’installation et de configuration avec Problèmes courants et résolutions pour Azure IoT Edge