Partager via

Démarrage rapide : Gérer un seul appareil IoT virtuel à l’aide d’Azure CLI

  • Article

Important

Ce document n’est plus mis à jour et sera supprimé. Pour obtenir des instructions de up-to-date sur les scénarios OSConfig :

  1. Tout d’abord, suivez les étapes décrites dans Créer un environnement de laboratoire OSConfig (avec Azure IoT) en 5 minutes
  2. Ensuite, essayez l’un des scénarios à partir de : Que puis-je provisionner et gérer ?

L’objectif de ce guide de démarrage rapide est de vous familiariser avec l’administration à distance des appareils IoT/Edge via OSConfig pour IoT. Dans la partie 1, vous allez configurer un environnement de test, y compris la création d’une machine virtuelle pour agir en tant qu’appareil IoT virtuel. Dans la partie 2, vous allez effectuer plusieurs actions de gestion des appareils, par exemple :

  • Récupérer à distance l’adresse IP de l’appareil
  • Tester à distance la connectivité des points de terminaison du point de vue de l’appareil
  • Redémarrer à distance l’appareil
  • et bien plus encore

Ce guide de démarrage rapide utilise un seul exemple d’appareil. Pour utiliser OSConfig à grande échelle, vous utilisez services Iot Hub Device Management comme plan de contrôle, plutôt que des commandes Azure CLI individuelles.

Conditions préalables

  1. Vous aurez besoin d’un compte Azure avec un abonnement actif. Si nécessaire, vous pouvez créer un compte gratuitement.
  2. Vous utiliserez l’environnement Azure Cloud Shellbash
    • REMARQUE : S’il s’agit de votre première utilisation d’Azure Cloud Shell, le portail vous guide tout au long de la création d’un espace de stockage avant de continuer. C’est normal.
    • REMARQUE : Azure Cloud Shell dispose déjà des derniers outils Azure CLI et est connecté automatiquement à votre compte Azure. Si vous préférez utiliser votre propre environnement de bash plutôt que cloud Shell, vous pouvez installer et configurer azure CLI dans votre propre environnement de bash.
  3. Vous aurez besoin de l’extension Azure IOT pour Azure CLI, qui peut être ajoutée à l’aide de la commande suivante :
az extension add --name azure-iot

capture d’écran montrant az extension add --name azure-iot

Vérification des prérequis

  • À partir de azure Cloud Shell (ou votre autre environnement de bash), vérifiez qu’Azure CLI est connecté au contexte de compte et d’abonnement Azure que vous souhaitez utiliser.
az account show

capture d’écran de la commande : az account show

Si vous devez vous connecter avec un autre compte ou modifier des abonnements, vous pouvez utiliser les commandes az login et az account set.

Vue d’ensemble de l’environnement de démarrage rapide

Diagramme pour le contexte, montrant Azure CLI utilisé pour créer IoT Hub et machine virtuelle, et être utilisé pour utiliser OSConfig

Partie 1 : Configurer votre environnement

1.1 : Créer vos ressources Azure IoT

1.1.1 : Définir un nom unique pour votre IoT Hub

Vous devez créer un nom unique pour votre IoT Hub, tel que « QuickStart12345 » ou « HelloWorld98765 ». Ce nom sera utilisé à plusieurs reprises dans les commandes ultérieures. Nous allons donc le stocker dans une variable bash, comme suit :

# In the following command replace <Your_Made_Up_Name_Here> 
# with your own preferred hub name, for example:
# MY_IOT_HUB_NAME="MyQuickStart54321"
MY_IOT_HUB_NAME="<Your_Made_Up_Name_Here>"

capture d’écran de bash, exemple d’affectation d’un nom unique choisi pour IOT Hub à la variable MY_IOT_HUB_NAME

1.1.2 : Créer un groupe de ressources et un hub IoT

az group create --resource-group QuickstartOSConfig --location westus
az iot hub create --resource-group QuickstartOSConfig --name "$MY_IOT_HUB_NAME" --query id

capture d’écran de la commande az group create

capture d’écran de la commande az iot hub create

Pourboire

Si la commande az iot hub create... échoue avec une erreur indiquant que le nom n’était pas disponible, cela signifie que le nom que vous avez choisi était déjà utilisé ailleurs dans Azure. Pour résoudre ce problème, répétez l’étape MY_IOT_HUB_NAME="<Your_Made_Up_Name_Here>" ci-dessus avec un nouveau nom unique, puis réessayez la commande az iot hub create ....

Pourboire

Il n’est pas rare que la commande az iot hub create... prenne quelques minutes.

1.1.3 : Créer l’ID d’appareil et obtenir la chaîne de connexion de l’appareil

az iot hub device-identity create --hub-name "$MY_IOT_HUB_NAME" -d device01 --query deviceId
az iot hub device-identity connection-string show --hub-name "$MY_IOT_HUB_NAME" --device-id device01

capture d’écran d’exemples de commandes az iot

Pourboire

Notez la valeur connectionString retournée par la dernière commande (elle commence par HostName=). Vous utiliserez cette chaîne de connexion dans une étape ultérieure.

1.2 : Créer une machine virtuelle Azure pour agir en tant qu’appareil IoT virtuel

Utilisez la commande suivante pour créer une machine virtuelle.

az vm create --resource-group QuickstartOSConfig --name device01 --image Canonical:UbuntuServer:18.04-lts:latest --admin-username azureuser --generate-ssh-keys --query publicIpAddress

capture d’écran de la commande az vm create

Pourboire

Notez l’adresse IP retournée par la dernière commande. Vous utiliserez cette adresse à l’étape suivante.

1.3 : Installer le logiciel client sur l’appareil IoT virtuel

1.3.1 : Établir accès au terminal à l’appareil virtuel

Les commandes suivantes doivent s’exécuter sur la machine virtuelle que vous venez de créer. Utilisez SSH pour vous connecter :

# In the following command, replace <public ip address from previous step> with
# the actual IP address. For example:
# ssh azureuser@1.2.3.4
ssh azureuser@<ip address from previous step>

capture d’écran de la commande ssh

Pourboire

Votre client ssh peut vous obliger à taper yes pour continuer. C’est normal.

Pourboire

Avant de continuer, vérifiez que vous êtes maintenant connecté à l’appareil IoT virtuel. Votre invite de commandes doit avoir changé de <your name>@azure: à azureuser@device01:. Si votre invite de commandes n’a pas changé en azureuser@device01:, réexécutez la commande ci-dessus ssh.

1.3.2 : Sur l’appareil virtuel, installer aziot-identity-service

sudo apt-get update
curl -sSL https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add
sudo apt-add-repository https://packages.microsoft.com/ubuntu/18.04/multiarch/prod
sudo apt-get update
sudo apt install -y aziot-identity-service

capture d’écran des commandes apt

capture d’écran 2 des commandes apt

1.3.3 : Sur l’appareil virtuel, appliquer la chaîne de connexion

Configurez l’appareil pour l’authentification auprès d’Azure IoT à l’aide de la commande suivante. Vous utiliserez la valeur de chaîne de connexion que vous avez obtenue précédemment dans Créer vos ressources Azure IoT.

sudo aziotctl config mp --connection-string "<your connection string>"
sudo aziotctl config apply

capture d’écran des commandes aziotctl

1.3.4 : Sur l’appareil virtuel, installer le package OSConfig et observer qu’il est en cours d’exécution

sudo apt install -y osconfig
sudo systemctl status osconfig | grep --color=never Active

capture d’écran de sudo apt install -y osconfig

1.2.5 : Quitter la session SSH

exit

capture d’écran de la sortie de la session SSH, en retournant à la session Cloud Shell

Partie 2 : Utiliser OSConfig pour IoT

Tu l’as fait ! Maintenant que l’environnement est préparé, nous pouvons commencer à utiliser OSConfig pour obtenir et définir la configuration et l’état au niveau de l’hôte via IoT Hub. À partir d’Azure Cloud Shell ou de votre ordinateur, utilisez les commandes Azure CLI suivantes pour terminer chaque exemple.

2.1 : Est-ce que c’est ça ?

Nous allons commencer par obtenir le deviceIdIoT Hub de l’appareil et montrer que OSConfig est actif.

az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,moduleId,connectionState from devices.modules where deviceID='device01' and moduleId='osconfig'"

capture d’écran de la commande de requête az iot hub

2.2 : Obtenir l’état du réseau de l’appareil, tel que les adresses IP et les serveurs DNS, pour tous les appareils activés par OSConfig dans votre IoT Hub

Il existe de nombreux cas d’usage pour signaler l’état du réseau à partir d’appareils gérés. Par exemple, vous aurez peut-être besoin de l’adresse IP locale pour connecter un flux vidéo IP local de la même façon que vous souhaitez signaler sur les serveurs DNS en cours d’utilisation pour résoudre les problèmes ou pour vous assurer que les appareils utilisent l’infrastructure réseau attendue. L’exemple suivant récupère les adresses IP et les serveurs DNS affectés à chaque carte réseau.

az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,properties.reported.Networking.NetworkConfiguration.IpAddresses,properties.reported.Networking.NetworkConfiguration.DnsServers from devices.modules where moduleId='osconfig'"

capture d’écran de la requête az iot (supplémentaire)

Pourboire

Les informations IP retournées sont du point de vue de l’appareil, correspondant à ce que vous obtiendriez en cours d’exécution ifconfig ou ip address localement sur l’appareil. L’adresse IP publique Azure (utilisée précédemment pour SSH) est nat routée en dehors de la machine virtuelle. Elle n’est donc pas vue ici.

2.3 : Configurer la stratégie de télémétrie ADHS (Azure Device Health Service) et vérifier la conformité

ADHS est un agent de diagnostic inclus dans certains appareils. La machine virtuelle que vous venez de créer n’a pas DDHS installée, mais nous pouvons toujours définir la stratégie de manière proactive comme exemple.

La première commande définit la propriété souhaitée du jumeau pour qu’ADHS 2 (ce qui signifie l’inscription). La deuxième commande compare les versions souhaitées (définies par vous, l’administrateur) et signalées (envoyées par l’appareil) de la propriété pour vérifier que l’appareil a reçu et appliqué la stratégie.

az iot hub module-twin update --hub-name "$MY_IOT_HUB_NAME" -d device01 -m osconfig --desired '{"Settings":{"__t":"c","DeviceHealthTelemetryConfiguration":2}}' > /dev/null
az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,properties.desired.Settings.DeviceHealthTelemetryConfiguration AS ADHSLevel_Desired,properties.reported.Settings.DeviceHealthTelemetryConfiguration.value AS ADHSLevel_Reported from devices.modules where moduleId='osconfig'"

capture d’écran de la requête az iot (autre exemple supplémentaire)

2.4 : Appliquer une configuration personnalisée (exemple de fuseau horaire)

La fonctionnalité CommandRunner d’OSConfig vous permet d’obtenir et de définir presque n’importe quoi sur l’appareil. Cet exemple montre comment définir le fuseau horaire du système d’exploitation de l’appareil sur UTC. L’application d’un fuseau horaire uniforme sur les points de terminaison (quel que soit leur emplacement physique) est une pratique courante pour améliorer la gestion des horodatages dans toute une solution distribuée.

La commande Azure CLI suivante indique à OSConfig de définir le fuseau horaire à l’aide de timedatectlet de signaler le fuseau horaire résultant.

az iot hub module-twin update --hub-name "$MY_IOT_HUB_NAME" -d device01 -m osconfig --desired '{"CommandRunner":{"__t":"c","CommandArguments":{"CommandId":"my_timezone_config", "Action":3, "Arguments": "timedatectl set-timezone UTC; timedatectl | grep zone | tr -d '[:space:]'"}}}' --query "properties.desired.CommandRunner"

capture d’écran de la commande az iot hub module-twin update

La sortie indique que nous avons défini la commande souhaitée dans le jumeau. Pour confirmer qu’il a fonctionné, nous allons prendre une étape supplémentaire. Tout d’abord, nous attendons au moins 30 secondes donner le temps à l’appareil de recevoir la commande, de le traiter et de mettre à jour le jumeau avec les résultats.

Après avoir attendu au moins 30 secondes depuis la commande précédente, utilisez les éléments suivants pour récupérer la sortie :

az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,properties.reported.CommandRunner.CommandStatus from devices.modules where moduleId='osconfig'"

capture d’écran de la requête az iot (exemple de fuseau horaire)

2.5 : Tester la connectivité des appareils (exemple ping)

Cet exemple utilise la fonctionnalité de CommandRunner avec ping pour tester la connectivité réseau du point de vue de l’appareil.

az iot hub module-twin update --hub-name "$MY_IOT_HUB_NAME" -d device01 -m osconfig --desired '{"CommandRunner":{"__t":"c","CommandArguments":{"CommandId":"connectivity_test_1", "Action":3, "Arguments":"ping -c 2 example.com"}}}' --query "properties.desired.CommandRunner"

capture d’écran de la commande az iot hub module-twin update (exemple ping)

Comme avec l’exemple précédent, la sortie de az iot hub module-twin update montre que nous avons défini la propriété de commande souhaitée sur le jumeau, et nous allons utiliser une deuxième étape pour récupérer les résultats.

Après avoir attendu au moins 30 secondes depuis la commande précédente, utilisez les éléments suivants pour récupérer les résultats :

az iot hub query --hub-name "$MY_IOT_HUB_NAME" -q "select deviceId,properties.reported.CommandRunner.CommandStatus from devices.modules where moduleId='osconfig'"

capture d’écran de la requête az iot (exemple ping)

2.6 : Redémarrer ou arrêter à l’aide d’actions prédéfinies CommandRunner

L’exemple suivant redémarre l’appareil. Si vous souhaitez arrêter à la place, remplacez Action: 1 par Action: 2 dans la valeur de propriété souhaitée.

az iot hub module-twin update --hub-name "$MY_IOT_HUB_NAME" -d device01 -m osconfig --desired '{"CommandRunner":{"__t":"c","CommandArguments":{"CommandId":"my_reboot_command", "Action":1}}}' --query "properties.desired.CommandRunner"

capture d’écran de la mise à jour du jumeau de module iot hub (exemple de redémarrage)

Nettoyer les ressources

Si vous n’avez pas l’intention de conserver l’une des ressources, vous pouvez les supprimer en supprimant le groupe de ressources que vous avez créé précédemment.

az group delete --resource-group QuickstartOSConfig

capture d’écran az group delete

Étapes suivantes

  • Ce guide n’a utilisé qu’un seul appareil pour commencer rapidement. Pour configurer des appareils à grande échelle, vous pouvez utiliser OSConfig avec IoT Hub Device Management avec OSConfig.
  • Pour en savoir plus sur OSConfig, consultez : documentation OSConfig.