Résoudre les problèmes de votre appareil IoT Edge

S’applique à : IoT Edge 1.1

Si vous rencontrez des problèmes lors de l’exécution d’Azure IoT Edge dans votre environnement, consultez cet article qui vous guidera pour la résolution des problèmes et les diagnostics.

Exécuter la commande « vérification »

La première étape dans la résolution des problèmes relatifs à IoT Edge consiste à utiliser la commande check qui exécute une collection de tests de configuration et de connectivité à la recherche de problèmes courants. La commande check est disponible dans la version 1.0.7 et supérieure.

Vous pouvez exécuter la commande check comme suit, ou inclure l’indicateur --help pour afficher une liste complète des options :

Sur Linux :

sudo iotedge check

Sur Windows :

iotedge check

L’outil de résolution des problèmes exécute de nombreuses vérifications qui sont triées dans les trois catégories suivantes :

• La Vérification de configuration contrôle des détails susceptibles d’empêcher les appareils IoT Edge de se connecter au cloud, dont des problèmes avec le fichier config et le moteur de conteneur.
• La Vérification de connexion vérifie que le runtime IoT Edge peut accéder aux ports sur l’appareil hôte et que tous les composants IoT Edge peuvent se connecter à IoT Hub. Cet ensemble de vérifications renvoie des erreurs si l’appareil IoT Edge se trouve derrière un proxy.
• La Vérification de disponibilité de la production recherche les meilleures pratiques de production recommandées, comme l’état des certificats d’autorité de l’appareil et la configuration du fichier journal du module.

L’outil de vérification IoT Edge utilise un conteneur pour exécuter ses diagnostics. L’image conteneur, mcr.microsoft.com/azureiotedge-diagnostics:latest, est disponible via Microsoft Container Registry. S’il vous faut exécuter une vérification portant sur un appareil sans accès direct à Internet, vos appareils doivent pouvoir accéder à l’image conteneur.

Pour plus d’informations sur chacune des vérifications de diagnostic exécutées par cet outil, notamment ce qu’il faut faire si vous obtenez une erreur ou un avertissement, consultez Vérifications de dépannage IoT Edge.

Collecter les informations de débogage avec la commande « support-bundle »

Pour collecter des journaux à partir d’un appareil IoT Edge, la méthode la plus pratique consiste à utiliser la commande support-bundle. Par défaut, cette commande collecte les journaux des modules, du gestionnaire de sécurité IoT Edge et du moteur de conteneur, la sortie JSON de la commande iotedge check et d’autres informations de débogage utiles. Elle les compresse dans un fichier unique pour faciliter le partage. La commande support-bundle est disponible dans la version 1.0.9 et supérieure.

Exécutez la commande support-bundle avec l’indicateur --since pour spécifier la période pour laquelle vous souhaitez récupérer les journaux. Par exemple 6h obtiendra les journaux des six dernières heures, 6d des six derniers jours, 6m des six dernières minutes, et ainsi de suite. Incluez l’indicateur --help pour voir la liste complète des options.

Sur Linux :

sudo iotedge support-bundle --since 6h

Sur Windows :

iotedge support-bundle --since 6h

Par défaut, la commande support-bundle crée un fichier zip appelé support_bundle.zip dans le répertoire où la commande est appelée. Utilisez l’indicateur --output pour spécifier un chemin d’accès ou un nom de fichier différent pour la sortie.

Pour plus d’informations sur la commande, consultez ses informations d’aide.

iotedge support-bundle --help

Vous pouvez également utiliser l’appel de méthode directe intégré UploadSupportBundle pour charger la sortie de la commande « support-bundle » dans Stockage Blob Azure.

Examiner les métriques collectées à partir du runtime

Les modules de runtime IoT Edge produisent des métriques qui vous permettent de superviser et de comprendre l’intégrité de vos appareils IoT Edge. Ajoutez le module collecteur de métriques à vos déploiements pour gérer la collecte de ces métriques et leur envoi au cloud afin de faciliter la supervision.

Pour plus d’informations, consultez Collecter et transporter les métriques.

Vérifier votre version d’IoT Edge

Si vous exécutez une version antérieure d’IoT Edge, une mise à niveau peut résoudre votre problème. L’outil iotedge check vérifie que le démon de sécurité IoT Edge est la version la plus récente, mais ne vérifie pas les versions des modules de hub et d’agent IoT Edge. Pour vérifier la version des modules de runtime sur votre appareil, utilisez les commandes iotedge logs edgeAgent et iotedge logs edgeHub. Le numéro de version est déclaré dans les journaux au démarrage du module.

Pour obtenir des instructions sur la mise à jour de votre appareil, consultez Mettre à jour le runtime et le démon de sécurité IoT Edge.

Vérifier l’installation d’IoT Edge sur vos appareils

Vous pouvez vérifier l’installation d’IoT Edge sur vos appareils en surveillant le jumeau de module edgeAgent.

Pour obtenir le dernier jumeau de module, exécutez la commande suivante depuis Azure Cloud Shell :

az iot hub module-twin show --device-id <edge_device_id> --module-id '$edgeAgent' --hub-name <iot_hub_name>

Cette commande renvoie toutes les propriétés edgeAgent signalées. Vous trouverez ci-dessous quelques propriétés utiles pour surveiller l’état de l’appareil :

• état du runtime
• heure de début du runtime
• heure de la dernière sortie du runtime
• nombre de redémarrages du runtime

Vérifier l’état des journaux et du gestionnaire de sécurité IoT Edge

Le gestionnaire de sécurité IoT Edge est responsable d’opérations telles que l’initialisation du système IoT Edge au démarrage et l’approvisionnement des appareils. Si IoT Edge ne démarre pas, les journaux du gestionnaire de sécurité peuvent fournir des informations utiles.

Sur Linux :

• Consultez l’état du gestionnaire de sécurité IoT Edge :

  sudo systemctl status iotedge
  

• Consultez les journaux du gestionnaire de sécurité IoT Edge :

  sudo journalctl -u iotedge -f
  

• Consultez les journaux plus détaillés du gestionnaire de sécurité IoT Edge :

  1. Modifiez les paramètres du démon IoT Edge :

     sudo systemctl edit iotedge.service
     

  2. Mettez à jour les lignes suivantes :

     [Service]
     Environment=IOTEDGE_LOG=debug
     

  3. Redémarrez le démon de sécurité IoT Edge :

     sudo systemctl cat iotedge.service
     sudo systemctl daemon-reload
     sudo systemctl restart iotedge
     

Sur Windows :

• Consultez l’état du gestionnaire de sécurité IoT Edge :

  Get-Service iotedge
  

• Consultez les journaux du gestionnaire de sécurité IoT Edge :

  . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog
  

• Affichez uniquement les 5 dernières minutes des journaux du gestionnaire de sécurité IoT Edge :

  . {Invoke-WebRequest -useb aka.ms/iotedge-win} | Invoke-Expression; Get-IoTEdgeLog -StartTime ([datetime]::Now.AddMinutes(-5))
  

• Consultez les journaux plus détaillés du gestionnaire de sécurité IoT Edge :

  1. Ajouter une variable d’environnement au niveau du système

     [Environment]::SetEnvironmentVariable("IOTEDGE_LOG", "debug", [EnvironmentVariableTarget]::Machine)
     

  2. Redémarrez le démon de sécurité IoT Edge :

     Restart-Service iotedge
     

Vérifier si les journaux d’activité des conteneurs indiquent des problèmes

Une fois que le démon de sécurité IoT Edge s’exécute, vérifiez si les journaux des conteneurs signalent des problèmes. Commencez par les conteneurs déployés, puis examinez les conteneurs qui composent le runtime IoT Edge : Edge Agent et Edge Hub. En général, les journaux d’activité de l’agent IoT Edge fournissent des informations sur le cycle de vie de chaque conteneur. Les journaux d’activité du hub IoT Edge fournissent des informations sur la messagerie et le routage.

Il est possible de récupérer les journaux de conteneur à plusieurs endroits :

• Sur l’appareil IoT Edge, exécutez la commande suivante pour afficher les journaux :

  iotedge logs <container name>
  

• Sur le Portail Azure, utilisez l’outil de résolution des problèmes intégré. Pour plus d’informations, consultez Surveillance et résolution des problèmes des appareils IoT Edge sur le Portail Azure.

• Utilisez la méthode directe UploadModuleLogs pour charger les journaux d’un module dans le Stockage Blob Azure.

Nettoyer les journaux de conteneur

Par défaut, le moteur de conteneur Moby ne définit pas de limites de taille pour le journal de conteneur. Au fil du temps, cela peut amener l’appareil à se remplir de journaux et à manquer d’espace disque. Si les journaux de conteneurs volumineux nuisent aux performances de votre appareil IoT Edge, utilisez la commande suivante pour forcer la suppression du conteneur et des journaux associés.

Si vous êtes toujours en train de résoudre des problèmes, attendez d’avoir inspecté les journaux du conteneur pour effectuer cette étape.

docker rm --force <container name>

Pour les scénarios de maintenance et de production des journaux en cours, configurez le pilote de journalisation par défaut.

Afficher les messages acheminés via hub IoT Edge

Vous pouvez afficher les messages acheminés via le hub IoT Edge et recueillir des insights à partir des journaux d’activité détaillés issus des conteneurs du runtime. Pour activer les journaux d’activité détaillés sur ces conteneurs, définissez RuntimeLogLevel dans votre fichier de configuration yaml. Pour ouvrir le fichier :

Sur Linux :

sudo nano /etc/iotedge/config.yaml

Sur Windows :

notepad C:\ProgramData\iotedge\config.yaml

Par défaut, l’élément agent se présente comme dans l’exemple suivant :

agent:
  name: edgeAgent
  type: docker
  env: {}
  config:
    image: mcr.microsoft.com/azureiotedge-agent:1.1
    auth: {}

Remplacez env: {} par :

env:
  RuntimeLogLevel: debug

Enregistrez le fichier et redémarrez le gestionnaire de sécurité IoT Edge.

Vous pouvez également vérifier les messages échangés entre IoT Hub et les appareils IoT. Affichez ces messages à l’aide de l’extension Azure IoT Hub pour Visual Studio Code. Pour plus d’informations, consultez Handy tool when you develop with Azure IoT.

Redémarrer les conteneurs

Une fois que vous avez examiné les journaux d’activité et les messages pour obtenir des informations, vous pouvez essayer de redémarrer les conteneurs.

Sur l’appareil IoT Edge, utilisez les commandes suivantes pour redémarrer les modules :

iotedge restart <container name>

Redémarrez les conteneurs du runtime IoT Edge :

iotedge restart edgeAgent && iotedge restart edgeHub

Vous pouvez également redémarrer les modules à distance sur le Portail Azure. Pour plus d’informations, consultez Surveillance et résolution des problèmes des appareils IoT Edge sur le Portail Azure.

Vérifier vos règles de configuration de pare-feu et de port

Azure IoT Edge permet la communication entre un serveur local et le cloud Azure au moyen des protocoles IoT Hub pris en charge (voir Choisir un protocole de communication). Pour renforcer la sécurité, les canaux de communication entre Azure IoT Edge et Azure IoT Hub sont toujours configurés pour être sortants. Cette configuration est basée sur le modèle de communication assistée par des services, ce qui réduit la surface d’attaque qu’une entité malveillante pourrait explorer. Les communications entrantes sont uniquement requises pour des scénarios spécifiques où Azure IoT Hub a besoin d’envoyer (push) des messages à l’appareil Azure IoT Edge. Les messages cloud-à-appareil sont protégés à l’aide de canaux TLS sécurisés, protection qui peut être renforcée à l’aide de certificats X.509 et de modules d’appareil TPM. Le Gestionnaire de sécurité Azure IoT Edge régit la façon dont cette communication peut être établie (voir Gestionnaire de sécurité IoT Edge).

Bien que IoT Edge assure une configuration améliorée pour la sécurisation du runtime Azure IoT Edge et des modules déployés, il dépend toujours de la configuration du réseau et de l’ordinateur sous-jacents. Il est donc indispensable de vérifier que les règles de pare-feu et de réseau sont bien configurées pour assurer la sécurisation de la communication Edge vers Cloud. Vous pouvez utiliser le tableau suivant pour configurer les règles de pare-feu pour les serveurs sous-jacents hébergeant le runtime Azure IoT Edge :

Dernier recours : arrêter et recréer tous les conteneurs

Parfois, un système peut nécessiter une modification spéciale importante pour fonctionner avec les contraintes de réseau ou de système d’exploitation existantes. Par exemple, un système peut nécessiter un montage de disque de données et des paramètres de proxy différents. Si vous avez suivi toutes les étapes ci-dessus et que les problèmes de conteneur persistent, il est possible que quelque part les caches du système Docker ou les paramètres réseau persistants ne soient pas à jour avec la dernière reconfiguration. Dans ce cas, l’option de dernier recours consiste à utiliser docker prune pour repartir de zéro.

La commande suivante arrête le système IoT Edge (et donc tous les conteneurs), et utilise les options « all » et « volume » pour docker prune afin de supprimer tous les conteneurs et volumes. Examinez l’avertissement émis par la commande et confirmez avec y lorsque vous êtes prêt.

sudo iotedge system stop
docker system prune --all --volumes

WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all volumes not used by at least one container
  - all images without at least one container associated to them
  - all build cache

Are you sure you want to continue? [y/N]

Redémarrez le système. Pour plus de sécurité, appliquez toute configuration potentiellement restante et démarrez le système avec une seule commande.

sudo iotedge config apply

Patientez quelques minutes, puis vérifiez à nouveau.

sudo iotedge list

Étapes suivantes

Vous pensez que vous avez trouvé un bogue dans la plateforme IoT Edge ? Soumettez un problème afin que nous puissions poursuivre les améliorations.

Si vous avez d'autres questions, créez une Support request pour obtenir de l'aide.