Tutoriel : développer des modules IoT Edge avec des conteneurs Linux en utilisant IoT Edge pour Linux sous Windows

S’applique à : IoT Edge 1.4

Ce didacticiel vous guide dans le développement, le débogage et le déploiement de votre propre code sur un appareil Azure IoT Edge à l’aide d’IoT Edge pour Linux sur Windows et Visual Studio 2022. Vous apprendrez le scénario de développement le plus courant pour les solutions IoT Edge en déployant un module C# sur un appareil Linux. Vous déploierez et déboguerez un module IoT Edge personnalisé exécuté dans un conteneur Linux sous Windows. Même si vous prévoyez d’utiliser un langage différent ou de déployer un service Azure, ce didacticiel reste utile pour en savoir plus sur les outils et concepts de développement.

Ce didacticiel comprend les étapes de deux outils de développement IoT Edge :

• L'interface de ligne de commande (CLI) Azure IoT Edge Dev Tool, qui est l'outil privilégié pour le développement
• L'extension Azure IoT Edge Tools pour Visual Studio, qui est en mode maintenance

Utilisez le bouton de sélection au début de ce didacticiel pour sélectionner la version de l'outil.

Dans ce tutoriel, vous allez apprendre à :

Prérequis

Ce didacticiel suppose que vous utilisez une machine exécutant Windows comme machine de développement. Sur les ordinateurs Windows, vous pouvez développer des modules Windows ou Linux. Ce didacticiel vous guide dans le développement de conteneurs Linux, en utilisant IoT Edge pour Linux sur Windows pour créer et déployer les modules.

Avant de commencer :

• Installez IoT Edge pour Linux sur Windows.

• Lisez le guide de démarrage rapide Déployez votre premier module IoT Edge sur un appareil Windows.

• Téléchargez le SDK .NET Core.

• Installez ou modifiez Visual Studio 2022 sur votre machine de développement. Choisissez les options de charge de travail de développement Azure et de développement de bureau avec C++.

• Une fois votre installation de Visual Studio 2022 prête, téléchargez et installez Azure IoT Edge Tools à partir de Visual Studio Marketplace.

  Vous pouvez utiliser l’extension Azure IoT Edge Tools pour créer et générer votre solution IoT Edge. L’outil de développement préféré est l’interface de ligne de commande Azure IoT Edge Dev Tool CLI. L’extension inclut les modèles de projet Azure IoT Edge que vous utilisez pour créer le projet Visual Studio. Actuellement, vous devez installer l'extension quel que soit l'outil de développement que vous utilisez.

  Conseil

  Si vous utilisez Visual Studio 2019, téléchargez et installez Azure IoT Edge Tools pour Visual Studio 2019 à partir de Visual Studio Marketplace.

• Créez un hub IoT gratuit ou de niveau standard dans Azure en tant que ressource cloud.

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit Azure avant de commencer.

Concepts clés

Ce tutoriel décrit le développement d'un module IoT Edge. Un module IoT Edge est un conteneur contenant du code exécutable. Vous pouvez déployer un ou plusieurs modules sur un appareil IoT Edge. Les modules effectuent des tâches spécifiques comme l’ingestion de données provenant de capteurs, le nettoyage et l’analyse de données ou encore l’envoi de messages à un hub IoT. Pour plus d’informations, consultez Présentation des modules Azure IoT Edge.

Lorsque vous développez des modules IoT Edge, il est important de comprendre la différence entre la machine de développement et l'appareil IoT Edge cible sur lequel le module sera éventuellement déployé. Le conteneur que vous générez pour le stockage du code du module doit correspondre au système d’exploitation (OS) de l’appareil cible.

Par exemple, le scénario le plus courant est celui d’une personne développant un module sur un ordinateur Windows qui souhaite cibler un appareil Linux exécutant IoT Edge. Dans ce cas, le système d’exploitation du conteneur est Linux.

À mesure que vous parcourez ce tutoriel, gardez à l’esprit la différence entre système d’exploitation de la machine de développement et système d’exploitation du conteneur. Pour ce didacticiel, vous utiliserez votre hôte Windows pour le développement et la machine virtuelle (VM) IoT Edge pour Linux sur Windows pour créer et déployer les modules.

Ce didacticiel cible les appareils qui exécutent IoT Edge avec des conteneurs Linux. Vous pouvez utiliser le système d’exploitation de votre choix, à condition que votre machine de développement exécute des conteneurs Linux. Visual Studio étant recommandé pour développer avec des conteneurs Linux, nous l’utilisons dans le cadre de ce tutoriel. Vous pouvez également utiliser Visual Studio Code, bien qu’il existe des différences de support entre les deux outils. Pour des informations complémentaires, consultez Développer des modules Azure IoT Edge à l’aide de Visual Studio Code.

Configurez la CLI Docker et le moteur Docker pour la connexion à distance

Les modules IoT Edge étant empaquetés en tant que conteneurs, vous avez besoin d’un moteur de conteneur sur votre machine de développement pour les générer et les gérer.

L’IoT Edge pour Linux sur la machine virtuelle Windows contient déjà une instance du moteur Docker. Ce didacticiel vous montre comment vous connecter à distance depuis la machine de développement Windows à l'instance Docker IoT Edge pour Linux sur Windows VM. En utilisant cette connexion à distance, vous supprimez la dépendance à Docker Desktop pour Windows.

Configurez la CLI Docker

La première étape consiste à configurer la CLI Docker sur la machine de développement Windows pour pouvoir se connecter au moteur Docker distant :

1. Téléchargez la version docker.exe précompilée de Docker CLI depuis Chocolatey. Vous pouvez également télécharger le projet cli officiel depuis GitHub et le compiler en suivant les instructions du dépôt.

2. Extrayez docker.exe dans un répertoire de votre machine de développement ; par exemple, C:\Docker\bin.

3. Ouvrez À propos de votre PC>Informations système>Paramètres système avancés.

4. Sélectionnez Variables d’environnement>avancées. Sous Variables utilisateur, sélectionnez Chemin.

5. Modifiez la variable Chemin et ajoutez l'emplacement de docker.exe.

6. Ouvrez une session PowerShell avec élévation de privilèges.

7. Vérifiez que la CLI Docker est accessible en utilisant cette commande :

   docker --version
   

   Si vous avez tout configuré avec succès, la sortie de la commande doit afficher la version de Docker. Elle doit se présenter comme Docker version 20.10.12, build e91ed57.

Configurez le moteur Docker

La deuxième étape consiste à configurer le moteur Docker IoT Edge pour Linux sur Windows VM pour accepter les connexions externes et à ajouter les règles de pare-feu appropriées.

1. Ouvrez une session PowerShell avec privilèges élevés et exécutez les commandes suivantes :

   # Configure the IoT Edge for Linux on Windows VM Docker engine to accept external connections, and add the appropriate firewall rules.
   Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"
   
   # Create a copy of the IoT Edge for Linux on Windows VM _docker.service_ in the system folder.
   Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"
   
   # Replace the service execution line to listen for external connections.
   Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g'  /etc/systemd/system/docker.service"
   
   # Reload the IoT Edge for Linux on Windows VM services configurations.
   Invoke-EflowVmCommand "sudo systemctl daemon-reload"
   
   # Reload the Docker engine service.
   Invoke-EflowVmCommand "sudo systemctl restart docker.service"
   
   # Check that the Docker engine is listening to external connections.
   Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"
   

   Voici un exemple de sortie :

   PS C:\> # Configure the IoT Edge for Linux on Windows virtual machine Docker engine to accept external connections, and add the appropriate firewall rules.
   PS C:\> Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"
   PS C:\>
   PS C:\> # Create a copy of the IoT Edge for Linux on Windows VM docker.service in the system folder.
   PS C:\> Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"
   PS C:\>
   PS C:\> # Replace the service execution line to listen for external connections.
   PS C:\> Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g' /etc/systemd/system/docker.service"
   PS C:\>
   PS C:\> # Reload the IoT Edge for Linux on Windows VM services configurations.
   PS C:\> Invoke-EflowVmCommand "sudo systemctl daemon-reload"
   PS C:\>
   PS C:\> # Reload the Docker engine service.
   PS C:\> Invoke-EflowVmCommand "sudo systemctl restart docker.service"
   PS C:\>
   PS C:\> # Check that the Docker engine is listening to external connections.
   PS C:\> Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"
   tcp6       0      0 :::2375                 :::*                    LISTEN      2790/dockerd
   

Tester la connexion

L'étape de configuration finale consiste à tester la connexion Docker au moteur Docker IoT Edge pour Linux sur Windows VM :

1. Obtenez l'adresse IP de l'IoT Edge pour Linux sur une machine virtuelle Windows :

   Get-EflowVmAddr
   

   Conseil

   Si IoT Edge pour Linux sur une machine virtuelle Windows a été déployé sans IP statique, l’adresse IP peut changer lors des redémarrages du système d’exploitation hôte Windows ou des modifications du réseau. Assurez-vous d’utiliser l’adresse IP correcte pour IoT Edge pour Linux sur la machine virtuelle Windows chaque fois que vous souhaitez établir une connexion à distance au moteur Docker.

   Voici un exemple de sortie :

   PS C:\> Get-EflowVmAddr
   [03/15/2022 15:22:30] Querying IP and MAC addresses from virtual machine (DESKTOP-J1842A1-EFLOW)
    - Virtual machine MAC: 00:15:5d:6f:da:78
    - Virtual machine IP : 172.31.24.105 retrieved directly from virtual machine
   00:15:5d:6f:da:78
   172.31.24.105 
   

2. Connectez-vous au moteur Docker IoT Edge pour Linux sur Windows VM et exécutez l’exemple de conteneur hello-world. Remplacez <EFLOW-VM-IP> par l’adresse IP de la machine virtuelle IoT Edge pour Linux sur Windows que vous avez obtenue à l’étape précédente.

   docker -H tcp://<EFLOW-VM-IP>:2375 run --rm hello-world
   

   Une fois le téléchargement du conteneur terminé, le conteneur s'exécute et produit cette sortie :

   PS C:\> docker -H tcp://172.31.24.105:2375 run --rm hello-world
   Unable to find image 'hello-world:latest' locally
   latest: Pulling from library/hello-world
   2db29710123e: Pull complete
   Digest: sha256:4c5f3db4f8a54eb1e017c385f683a2de6e06f75be442dc32698c9bbe6c861edd
   Status: Downloaded newer image for hello-world:latest
   
   Hello from Docker!
   This message shows that your installation appears to be working correctly.
   
   To generate this message, Docker took the following steps:
    1. The Docker client contacted the Docker daemon.
    2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
       (amd64)
    3. The Docker daemon created a new container from that image which runs the
       executable that produces the output you're currently reading.
    4. The Docker daemon streamed that output to the Docker client, which sent it
       to your terminal.
   
   To try something more ambitious, you can run an Ubuntu container with:
    $ docker run -it ubuntu bash
   
   Share images, automate workflows, and more with a free Docker ID:
    https://hub.docker.com/
   
   For more examples and ideas, visit:
    https://docs.docker.com/get-started/
   

Créer un projet Azure IoT Edge

Le modèle de projet IoT Edge dans Visual Studio crée une solution que vous pouvez déployer sur des appareils IoT Edge. Utilisez les étapes suivantes pour créer une solution Azure IoT Edge, puis générez le premier module de cette solution. Chaque solution IoT Edge peut contenir plusieurs modules.

1. Dans Visual Studio, créez un nouveau projet en sélectionnant Créer un nouveau projet sur la page de démarrage ou en sélectionnant le bouton Nouveau projet dans la barre d’outils.

2. Sur la page Créer un projet, recherchez Azure IoT Edge. Sélectionnez le projet qui correspond à la plateforme (module Linux IoT Edge) et à l’architecture de votre appareil IoT Edge, puis sélectionnez Suivant.

3. Sur la page Configurer votre nouveau projet, entrez un nom pour votre projet et spécifiez l’emplacement, puis sélectionnez Créer.

4. Dans la boîte de dialogue Ajouter un module, sélectionnez le type de module que vous souhaitez développer. Vous pouvez également sélectionner Module existant pour ajouter un module de IOT Edge existant à votre déploiement.

5. Dans Nom du module, spécifiez le nom de votre module.

6. Dans Url du dépôt, indiquez le nom du référentiel d’images du module. Visual Studio renseigne automatiquement le nom du module avec localhost:5000/<votre nom de module>. Remplacez-le par vos propres informations de registre.

   Utilisez localhost si vous utilisez un registre Docker local pour les tests. Si vous utilisez Azure Container Registry, utilisez le serveur de connexion à partir des paramètres de votre registre. Le serveur de connexion se présente comme suit : <nom du registre>.azurecr.io. Remplacez uniquement la partie localhost:5000 de la chaîne, afin que le résultat final ressemble au <nom de registre >.azurecr.io/<de votre nom de module>.

7. Sélectionnez Ajouter pour ajouter votre module au projet.

   

   Remarque

   Si vous disposez d’un projet IoT Edge existant, vous pouvez modifier l’URL du référentiel en ouvrant le fichier module.json. L'URL du référentiel se trouve dans la propriété repository du fichier JSON.

Vous disposez maintenant d’un projet IoT Edge et d’un module IoT Edge dans votre solution Visual Studio.

Structure de projet

Votre solution comporte deux dossiers au niveau du projet : un dossier de projet principal et un dossier de module. Par exemple, vous pouvez avoir un dossier de projet principal nommé AzureIotEdgeApp1 et un dossier de module nommé IotEdgeModule1.

Le dossier principal du projet contient votre manifeste de déploiement. Le manifeste de déploiement est un document JSON qui décrit les modules devant être configurés sur l’appareil IoT Edge ciblé.

Le dossier du module contient un fichier pour le code de votre module. Il s'appelle soit Program.cs ou main.c, selon la langue que vous avez choisie. Ce dossier contient également un fichier nommé module.json décrivant les métadonnées de votre module. Divers fichiers Docker fournissent les informations nécessaires pour créer votre module en tant que conteneur Windows ou Linux.

Manifeste de déploiement de votre projet

Le manifeste de déploiement que vous modifiez est nommé deployment.debug.template.json. Ce fichier est un modèle de manifeste de déploiement IoT Edge qui définit tous les modules qui s'exécutent sur un appareil. Le fichier définit également comment les modules communiquent entre eux. Pour plus d’informations sur les manifestes de déploiement, consultez Découvrir comment déployer des modules et établir des routes.

Le modèle de déploiement comprend :

• Les deux modules d'exécution edgeAgent et edgeHub.
• Le module personnalisé que vous avez créé dans ce projet Visual Studio.
• Un module nommé SimulatedTemperatureSensor. Ce module par défaut génère des données simulées que vous pouvez utiliser pour tester vos modules (ou supprimer si ce n'est pas nécessaire). Pour voir comment fonctionne le capteur de température simulé, consultez le code source SimulatedTemperatureSensor.csproj.

Définissez la version d'exécution d'IoT Edge

Actuellement, la dernière version stable est la version 1.4. Mettez à jour la version d'exécution d'IoT Edge vers la dernière version stable ou la version que vous souhaitez cibler pour vos appareils :

Développer votre module

Lorsque vous ajoutez un nouveau module, il est livré avec un code par défaut prêt à être créé et déployé sur un appareil afin que vous puissiez commencer les tests sans toucher à aucun code. Le code du module se trouve dans le dossier de celui-ci, dans un fichier nommé Program.cs (pour C#) ou main.c (pour C).

Dans la solution par défaut, les données simulées du module SimulatedTemperatureSensor sont acheminées vers votre module. Le module prend l’entrée, puis l’envoie à Azure IoT Hub.

Lorsque vous êtes prêt à personnaliser le modèle de module avec votre propre code, utilisez les kits SDK Azure IoT Hub pour créer d’autres modules qui répondent aux besoins clés des solutions IoT. Ces besoins peuvent inclure la sécurité, la gestion des appareils et la fiabilité.

Générer et envoyer (push) un module unique

En général, il est préférable de tester et de déboguer chaque module avant de l’exécuter au sein d’une solution entière avec plusieurs modules. Étant donné que la solution sera créée ou déboguée à l'aide du moteur Docker exécuté dans IoT Edge pour Linux sur une machine virtuelle Windows, la première étape consiste à créer et à publier le module pour permettre le débogage à distance :

1. Dans l’Explorateur de solutions, sélectionnez le dossier du projet de module (par exemple, myIotEdgeModule).

2. Définissez le module personnalisé comme projet de démarrage. Dans le menu, sélectionnez Projet>Définir comme projet StartUp.

3. Pour déboguer le module C# Linux, vous devez mettre à jour le fichier Dockerfile.amd64.debug pour activer le service SSH. Mettez à jour le fichier Dockerfile.amd64.debug pour utiliser le modèle suivant : Dockerfile pour Azure IoT Edge AMD64 C# Module avec prise en charge du débogage à distance.

   Remarque

   Lorsque vous sélectionnez Déboguer, Visual Studio utilise Dockerfile.(amd64|windows-amd64).debug pour créer des images Docker. Ce fichier inclut le débogueur de ligne de commande .NET Core VSDBG dans votre image de conteneur lors de sa création. Pour obtenir des modules IoT Edge prêts pour la production, nous vous recommandons d’utiliser la configuration Publier qui utilise Dockerfile.(amd64|windows-amd64) sans VSDBG.

   Assurez-vous que dans la dernière ligne du modèle, ENTRYPOINT ["dotnet", "IotEdgeModule1.dll"], le nom de la DLL correspond au nom de votre projet de module IoT Edge.

4. Pour établir une connexion SSH avec le module Linux, vous devez créer une clé RSA. Ouvrez une session PowerShell avec élévation de privilèges et exécutez les commandes suivantes pour créer une clé RSA. Enregistrez la clé RSA dans le même dossier du module IoT Edge et assurez-vous que le nom de la clé est id_rsa.

   ssh-keygen -t RSA -b 4096 -m PEM
   

   

5. Si vous utilisez un registre privé tel qu’Azure Container Registry, servez-vous de la commande Docker suivante pour vous y connecter. Vous pouvez récupérer le nom d’utilisateur et le mot de passe à partir de la page Clés d’accès de votre registre dans le Portail Azure. Si vous utilisez un registre local, vous pouvez exécuter un registre local.

   docker -H tcp://<EFLOW-VM-IP>:2375 login -u <Container Registry username> -p <Container Registry password> <Container Registry login server>
   

docker build --rm -f "<DockerFilePath>" -t <ImageNameAndTag> "<ContextPath>" 

# Build the image for the local registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t localhost:5000/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

# Or build the image for an Azure container registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

# Push the Docker image to the local registry

docker push localhost:5000/iotedgemodule1:0.0.1-amd64

# Or push the Docker image to an Azure container registry
az acr login --name myacr
docker push myacr.azurecr.io/iotedgemodule1:0.0.1-amd64

Déboguer la solution

1. Dans une session PowerShell avec privilèges élevés, exécutez les commandes suivantes :

   1. Obtenez la valeur moduleId, en fonction du nom du module Linux C#. Remplacez l'espace réservé <iot-edge-module-name> par le nom de votre module.

      $moduleId = Invoke-EflowVmCommand "sudo docker ps -aqf name=<iot-edge-module-name>"
      

   2. Vérifiez que $moduleId est correct. Si la variable est vide, assurez-vous que vous utilisez le nom de module correct.

   3. Démarrez le service SSH dans le conteneur Linux :

      Invoke-EflowVmCommand "sudo docker exec -it -d $moduleId service ssh start"
      

   4. Ouvrez le port SSH du module sur IoT Edge pour Linux sur la machine virtuelle Windows. (Ce tutoriel utilise le port 10022.)

      Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 10022 -j ACCEPT"
      

   Avertissement

   Pour des raisons de sécurité, chaque fois que la machine virtuelle IoT Edge pour Linux sur Windows redémarre, la règle de table IP est supprimée et revient aux paramètres d'origine. De plus, vous devez redémarrer manuellement le service SSH du module.

2. Une fois le service SSH démarré avec succès, sélectionnez Déboguer>Attacher au processus, définissez le type de connexion sur SSH et définissez la cible de connexion sur l’adresse IP de votre machine virtuelle IoT Edge pour Linux sur Windows. Si vous ne connaissez pas l’adresse IP de votre machine virtuelle IoT Edge pour Linux sur Windows, vous pouvez utiliser l’applet de commande PowerShell Get-EflowVmAddr.

   Tapez l'adresse IP puis sélectionnez la touche Entrée. Dans la fenêtre contextuelle, entrez les configurations suivantes :

   Champ	Valeur
   Nom d’hôte	Adresse IP pour IoT Edge pour Linux sur machine virtuelle Windows
   Port	10022 (ou celui que vous avez utilisé dans votre configuration de déploiement)
   Nom d’utilisateur	root
   Type d’authentification	Clé privée
   Fichier de clé privée	Chemin d'accès complet vers la valeur id_rsa que vous avez créée à une étape précédente
   Phrase secrète	Phrase secrète utilisée pour la clé que vous avez créée à une étape précédente

3. Après vous être connecté avec succès au module en utilisant SSH, vous pouvez choisir le processus et sélectionner Attacher. Pour le module C#, vous devez choisir le processus dotnet et Attacher à Managed (CoreCLR). Cela peut prendre 10 à 20 secondes la première fois.

4. Définissez un point d’arrêt pour inspecter le module :

   • Si vous développez en C#, définissez un point d'arrêt dans la fonction PipeMessage() dans ModuleBackgroundService.cs.
   • Si vous utilisez C, définissez un point d'arrêt dans la fonction InputQueue1Callback() dans main.c.

5. La sortie SimulatedTemperatureSensor doit être redirigée vers input1 du module Linux C# personnalisé. Le point d’arrêt doit être déclenché. Vous pouvez regarder les variables dans la fenêtre Variables locales de Visual Studio.

   

6. Pour arrêter le débogage, sélectionnez Ctrl+F5 ou sélectionnez le bouton Arrêter.

Nettoyer les ressources

Si vous envisagez de passer à l’article recommandé suivant, vous pouvez conserver les ressources et configurations que vous avez créées afin de les réutiliser. Vous pouvez également continuer à utiliser le même appareil IoT Edge comme appareil de test.

Sinon, supprimez les configurations locales et les ressources Azure que vous avez utilisées dans cet article pour éviter des frais.

Supprimer les ressources Azure

La suppression des ressources et des groupes de ressources Azure est irréversible. Veillez à ne pas supprimer accidentellement les mauvaises ressources ou le mauvais groupe de ressources. Si vous avez créé le hub IoT à l’intérieur d’un groupe de ressources existant qui contient des ressources que vous souhaitez conserver, supprimez uniquement la ressource du hub IoT, plutôt que le groupe de ressources.

Pour supprimer les ressources :

1. Connectez-vous au Portail Azure, puis sélectionnez Groupes de ressources.

2. Sélectionnez le nom du groupe de ressources contenant vos ressources de test de IoT Edge.

3. Consultez la liste des ressources que contient votre groupe de ressources. Si vous souhaitez toutes les supprimer, vous pouvez sélectionner Supprimer le groupe de ressources. Si vous souhaitez en supprimer seulement quelques-unes, vous pouvez sélectionner chaque ressource pour la supprimer individuellement.

Étape suivante

Dans ce didacticiel, vous avez configuré Visual Studio sur votre machine de développement et vous avez déployé et débogué votre premier module IoT Edge à partir de celui-ci. Maintenant que vous connaissez les concepts de base, essayez d'ajouter des fonctionnalités à un module afin qu'il puisse analyser les données qui le traversent :