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

S’applique à : IoT Edge 1.5

Important

IoT Edge 1.5 LTS est la version prise en charge. IoT Edge 1.4 LTS est en fin de vie depuis le 12 novembre 2024. Si vous utilisez une version antérieure, consultez l’article Mettre à jour IoT Edge.

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.

Remarque

L’outil de dépannage ne peut pas exécuter de vérifications de connectivité si l’appareil IoT Edge se trouve derrière un serveur proxy.

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

sudo 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 de conteneur mcr.microsoft.com/azureiotedge-diagnostics:latest est disponible via le Microsoft Artifact Registry (MAR). Si vous devez exécuter une vérification sur un appareil sans accès direct à Internet, vos appareils ont besoin d’accéder à l’image conteneur.

Dans un scénario utilisant des appareils IoT Edge imbriqués, vous pouvez accéder à l’image de diagnostic sur les appareils en aval en acheminant le tirage (pull) de l’image par les appareils parents.

sudo iotedge check --diagnostics-image-name <parent_device_fqdn_or_ip>:<port_for_api_proxy_module>/azureiotedge-diagnostics:1.2

Pour plus d’informations sur chacune des vérifications de diagnostic exécutées par cet outil, notamment sur la procédure à suivre si vous recevez une erreur ou un avertissement, consultez la fonctionnalité de résolution des problèmes intégrée.

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 obtient 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.

sudo 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.

Avertissement

La sortie de la support-bundle commande peut contenir des informations sur l’hôte, les noms d’appareils, les noms de module et les informations journalisées par vos modules. Tenez compte de cette inclusion si vous partagez la sortie dans un forum public.

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, la 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 façon de mettre à jour votre appareil, consultez Mettre à jour 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 signalées edgeAgent. 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.

• Consultez l’état des services système IoT Edge :

  sudo iotedge system status
  

• Consultez les journaux des services système IoT Edge :

  sudo iotedge system logs -- -f
  

• Activez les journaux au niveau débogage pour afficher des journaux plus détaillés des services système IoT Edge :

  1. Activez les journaux au niveau débogage.

     sudo iotedge system set-log-level debug
     sudo iotedge system restart
     

  2. Revenez aux journaux de niveau informations par défaut après le débogage.

     sudo iotedge system set-log-level info
     sudo iotedge system restart
     

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 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, les journaux étendus peuvent amener l’appareil à se remplir de journaux et à manquer d’espace disque. Si les journaux de conteneurs volumineux affectent les performances de votre appareil IoT Edge, utilisez la commande suivante pour forcer la suppression du conteneur avec ses 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.

Avertissement

Si vous forcez à supprimer le conteneur edgeHub pendant qu’il a un backlog de messages non remis et qu’aucun stockage hôte n’est configuré, les messages non remis sont perdus.

docker rm --force <container name>

Pour plus d’informations sur les scénarios de maintenance et de production des journaux en cours, consultez Configurer le pilote de journalisation par défaut.

Afficher les messages acheminés via hub IoT Edge

Vous pouvez afficher les messages transitant via le hub IoT Edge et recueillir des insights à partir des journaux d’activité détaillés issus des conteneurs d’exécution. Pour activer les journaux détaillés sur ces conteneurs, définissez la variable d’environnement RuntimeLogLevel dans le manifeste de déploiement.

Pour afficher les messages transitant via le Hub IoT Edge, définissez la variable d’environnement RuntimeLogLevel sur debug pour le module edgeHub.

Les modules edgeHub et edgeAgent disposent de cette variable d’environnement de journal d’exécution, avec la valeur par défaut définie sur info. Cette variable d’environnement peut prendre les valeurs suivantes :

• fatal
• erreur
• avertissement
• informations
• déboguer
• commentaires

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 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 les communications d’un serveur local vers le cloud Azure au moyen des protocoles IoT Hub pris en charge. Pour plus d’informations, consultez Choisir un protocole de communication d’appareil. 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 service, qui réduit la surface d’attaque d’une entité malveillante à 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. Azure IoT Edge Security Manager régit la façon dont cette communication peut être établie. Pour plus d’informations, consultez le gestionnaire de sécurité Azure IoT Edge.

Bien qu’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 impératif 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 :

Protocole	Port	Entrant	Sortant	Instructions
MQTT	8883	BLOQUÉ (par défaut)	BLOQUÉ (par défaut)	Configurez Sortante sur Ouverte lorsque vous utilisez MQTT comme protocole de communication. IoT Edge ne prend pas en charge le port 1883 pour MQTT. Les connexions entrantes doivent être bloquées.
AMQP	5671	BLOQUÉ (par défaut)	OUVERT (par défaut)	Protocole de communication par défaut pour IoT Edge. Doit être configuré sur Ouvert si Azure IoT Edge n’est pas configuré pour les autres protocoles pris en charge ou si AMQP est le protocole de communication souhaité. IoT Edge ne prend pas en charge le port 5672 pour AMQP. Bloquez ce port quand Azure IoT Edge utilise un autre protocole IoT Hub pris en charge. Les connexions entrantes doivent être bloquées.
HTTPS	443	BLOQUÉ (par défaut)	OUVERT (par défaut)	Configurez la connexion sortante pour être Ouverte sur le port 443 pour le provisionnement d’IoT Edge. Cette configuration est requise en cas d’utilisation de scripts manuels ou du service Azure IoT Device Provisioning. La connexion entrante ne peut être Ouverte que dans certaines situations uniquement : Si vous disposez d’une passerelle transparente avec des appareils en aval qui peuvent envoyer des demandes de méthode. Dans ce cas, le port 443 n’a pas besoin d’être ouvert aux réseaux externes pour se connecter à IoTHub ou fournir des services IoTHub via Azure IoT Edge. La règle entrante peut donc être limitée à l’ouverture du trafic entrant en provenance du réseau interne. Pour les scénarios Client vers Appareil (C2D). IoT Edge ne prend pas en charge le port 80 pour HTTP. Si les protocoles non-HTTP (par exemple, AMQP ou MQTT) ne peuvent pas être configurés dans l’entreprise, les messages peuvent être envoyés sur WebSockets. Dans ce cas, le port 443 est utilisé pour la communication WebSocket.

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 précédentes et que les problèmes de conteneur persistent, il est possible que 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.