Guide pratique pour migrer automatiquement un hub IoT à l’aide d’Azure CLI

Article
04/21/2023

Utilisez Azure CLI pour migrer un hub IoT vers une nouvelle région, un nouveau niveau ou une nouvelle configuration.

Les étapes décrites dans cet article sont utiles si vous souhaitez :

Passer du niveau gratuit vers un hub IoT de niveau de base ou standard.
Déplacer un hub IoT vers une nouvelle région.
Exporter les informations d’état d’un hub IoT pour disposer d’une sauvegarde.
Augmenter le nombre de partitions d’un hub IoT.
Configurer un hub pour un environnement de développement plutôt que de production.

Comparer les étapes de migration automatique et manuelle

Le résultat de cet article est similaire au Guide pratique de migration d’un hub Azure IoT à l’aide de modèles Azure Resource Manager, mais avec un processus différent. Avant de commencer, déterminez le processus qui convient le plus à votre scénario.

Processus Azure CLI (cet article) :
- Migre votre registre d’appareils, vos informations de routage et de point de terminaison, ainsi que d’autres détails de configuration tels que les déploiements IoT Edge ou les configurations de gestion automatique des appareils.
- Est plus facile pour la migration d’un petit nombre d’appareils (par exemple, jusqu’à 10 000).
- Ne nécessite pas de compte de stockage Azure.
- Collecte les chaînes de connexion pour les points de terminaison de routage et de chargement de fichiers et les inclut dans la sortie du modèle ARM.
Processus manuel :
- Migre votre registre d’appareils et vos informations de routage et de point de terminaison. Vous devez recréer manuellement d’autres détails de configuration dans le nouveau hub IoT.
- Est plus rapide pour la migration d’un grand nombre d’appareils (par exemple, plus de 100 000).
- Utilise un compte de stockage Azure pour transférer le registre d’appareils.
- Nettoie les chaînes de connexion pour le routage et les points de terminaison de chargement de fichiers à partir de la sortie du modèle ARM, et vous devez les rajouter manuellement.

Prérequis

Azure CLI

Les fonctionnalités décrites dans cet article nécessitent la version 0.20.0 ou ultérieure de l’extension azure-iot. Pour vérifier la version de votre extension, exécutez az --version. Pour mettre à jour votre extension, exécutez az extension update --name azure-iot.

Si l’extension azure-cli-iot-ext héritée est toujours installée, supprimez-la avant d’ajouter l’extension azure-iot.

État d’un hub IoT

Lorsque nous parlons de la migration de l’état d’un hub IoT, nous faisons référence à une combinaison de trois aspects :

Ressources Azure Resource Manager (ARM). Cet aspect est tout ce qui peut être défini dans un modèle de ressource, et il s’agit des mêmes informations que celles que vous obtiendriez si vous exportiez le modèle de ressource à partir de votre hub IoT dans le portail Azure. Les informations capturées dans le cadre de l’aspect Azure Resource Manager incluent :
- Temps de rétention de l’Event Hub intégré
- Certificats
- Propriétés cloud-à-appareil
- Désactiver la signature d’accès partagé de l’appareil
- Désactiver l’authentification locale
- Activer les notifications de chargement de fichier
- Point de terminaison de stockage de chargement de fichiers
- Identities
  - Identités affectées par l’utilisateur
  - Identités attribuées par le système (activées ou désactivées)
- Ensemble de règles réseau
- Routage
  - Points de terminaison personnalisés
  - Itinéraire de secours
  - Itinéraires
- Étiquettes
Configurations. Cet aspect concerne les aspects d’un hub IoT qui ne sont pas représentés dans un modèle ARM. Plus précisément, il couvre les configurations de gestion automatique des appareils et les déploiements IoT Edge.
Appareils. Cet aspect représente les informations contenues dans votre registre d’appareils, notamment :
- Identités d’appareil et jumeaux
- Identités de module et jumeaux

Toute propriété ou configuration d’IoT Hub non répertoriée ici peut ne pas être exportée ou importée correctement.

Exporter l’état d’un hub IoT

Utilisez la commande az iot hub state export pour exporter l’état d’un hub IoT vers un fichier JSON.

Si vous souhaitez exécuter les étapes d’exportation et d’importation dans une commande, reportez-vous à la section plus loin dans cet article pour Migrer un hub IoT.

Lorsque vous exportez l’état d’un hub IoT, vous pouvez choisir les aspects à exporter.

Paramètre	Détails
`--aspects`	Aspects d’état à exporter. Spécifiez une ou plusieurs des valeurs acceptées : arm, configurations ou devices. Si ce paramètre est laissé de côté, les trois aspects sont exportés.
`--state-file -f`	Chemin d’accès au fichier dans lequel les informations d’état sont écrites.
`--replace -r`	Si ce paramètre est inclus, la commande export remplace le contenu du fichier d’état.
`--hub-name -n` or `--login -l`	Nom du hub IoT d’origine (`-n`) ou chaîne de connexion pour le hub IoT d’origine (`-l`). Si les deux sont fournis, la chaîne de connexion est prioritaire.
`--resource-group -g`	Nom du groupe de ressources pour le hub IoT d’origine.

L’exemple suivant exporte tous les aspects de l’état d’un hub IoT vers un fichier nommé myHub-state :

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

L’exemple suivant exporte uniquement les appareils et les aspects Azure Resource Manager de l’état d’un hub IoT et remplace le contenu du fichier existant :

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

Exporter des points de terminaison

Si vous choisissez d’exporter l’aspect Azure Resource Manager d’un hub IoT, la commande export récupère les chaînes de connexion pour tous les points de terminaison disposant d’une authentification basée sur les clés et les inclut dans le modèle ARM de sortie.

La commande export vérifie également tous les points de terminaison pour s’assurer que la ressource à laquelle elle se connecte existe toujours. Si ce n’est pas le cas, ce point de terminaison et tous les itinéraires utilisant ce point de terminaison ne sont pas exportés.

Importer l’état d’un hub IoT

Utilisez la commande az iot hub state import pour importer les informations d’état d’un fichier exporté vers un hub IoT nouveau ou existant.

Si vous souhaitez exécuter les étapes d’exportation et d’importation dans une commande, reportez-vous à la section plus loin dans cet article pour Migrer un hub IoT.

Paramètre	Détails
`--aspects`	Aspects d’état à importer. Spécifiez une ou plusieurs des valeurs acceptées : arm, configurations ou devices. Si ce paramètre est laissé de côté, les trois aspects sont importés.
`--state-file -f`	Chemin d’accès au fichier d’état exporté.
`--replace -r`	Si ce paramètre est inclus, la commande import supprime l’état actuel du hub de destination.
`--hub-name -n` or `--login -l`	Nom du hub IoT de destination (`-n`) ou chaîne de connexion du hub IoT de destination (`-l`). Si les deux sont fournis, la chaîne de connexion est prioritaire.
`--resource-group -g`	Nom du groupe de ressources pour le hub IoT de destination.

L’exemple suivant importe tous les aspects dans un nouveau hub IoT, qui est créé s’il n’existe pas déjà :

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

L’exemple suivant importe uniquement les aspects appareils et configurations dans un nouveau hub IoT, qui doit déjà exister, et remplace tous les appareils et configurations existants :

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

Créer un hub IoT avec importation d’état

Vous pouvez utiliser la commande az iot hub state import pour créer un hub IoT ou écrire dans un hub IoT existant.

Si vous souhaitez créer un IoT Hub, vous devez inclure l’aspect arm dans la commande import. Si arm n’est pas inclus dans la commande et que le hub de destination n’existe pas, la commande import échoue.

Si le hub de destination n’existe pas, le paramètre --resource-group est également requis pour la commande import.

Mettre à jour un hub IoT existant avec l’importation d’état

Si le hub IoT de destination existe déjà, l’aspect arm n’est pas requis pour la commande az iot hub state import. Si vous incluez l’aspect arm, toutes les propriétés de ressource seront remplacées à l’exception des propriétés suivantes qui ne peuvent pas être modifiées après la création du hub :

Emplacement
SKU
Nombre de partitions Event Hubs intégrées
Résidence des données
Fonctionnalités

Si --resource-group est spécifié dans la commande import et est différent du groupe de ressources actuel du hub IoT, la commande échoue, car elle tente de créer un hub portant le même nom que celui qui existe déjà.

Si vous incluez l’indicateur --replace dans la commande import, les aspects de hub IoT suivants sont supprimés du hub de destination avant le chargement de l’état du hub :

ARM : tous les certificats chargés sur le hub de destination sont supprimés. Si un certificat est présent, un etag doit être mis à jour.
Appareils : tous les appareils et modules, périphériques et non périphériques, sont supprimés.
Configurations : toutes les configurations ADM et les déploiements IoT Edge sont supprimés.

Migrer un hub IoT

Utilisez la commande az iot hub state migrate pour migrer l’état d’un hub IoT vers un hub IoT nouveau ou existant.

Cette commande encapsule les étapes d’exportation et d’importation dans une seule commande, mais ne génère aucun fichier de sortie. Toutes les instructions et limitations décrites dans les sections Exporter l’état d’un hub IoT et Importer l’état d’un hub IoT s’appliquent également à la commande state migrate.

Si vous migrez un registre d’appareils avec de nombreux appareils (par exemple, quelques centaines ou quelques milliers), il peut être plus facile et plus rapide d’exécuter les commandes export et import séparément plutôt que d’exécuter la commande migrate.

Paramètre	Détails
`--aspects`	Aspects de l’état à migrer. Spécifiez une ou plusieurs des valeurs acceptées : arm, configurations ou devices. Si ce paramètre est omis, les trois aspects sont migrés.
`--replace -r`	Si ce paramètre est inclus, la commande migrate supprime l’état actuel du hub de destination.
`--destination-hub --dh` or `--destination-hub-login --dl`	Nom du hub IoT de destination (`--dh`) ou chaîne de connexion du hub IoT de destination (`--dl`). Si les deux sont fournis, la chaîne de connexion est prioritaire.
`--destination-resource-group --dg`	Nom du groupe de ressources pour le hub IoT de destination. Le groupe de ressources de destination est requis si le hub de destination n’existe pas.
`--origin-hub --oh` or `--origin-hub-login --ol`	Nom du hub IoT d’origine (`--oh`) ou chaîne de connexion du hub IoT d’origine (`--ol`). Si les deux sont fournis, la chaîne de connexion est prioritaire. Utilisez la chaîne de connexion pour éviter d’avoir à vous connecter à la session Azure CLI.
`--origin-resource-group --og`	Nom du groupe de ressources pour le hub IoT d’origine.

L’exemple suivant migre tous les aspects du hub d’origine vers le hub de destination, qui est créé s’il n’existe pas :

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

Résoudre les problèmes liés à une migration

Si vous ne pouvez pas exporter ou importer des appareils ou des configurations, vérifiez que vous avez accès à ces propriétés. L’une des façons de vérifier votre accès consiste à exécuter les commandes az iot hub device-identity list ou az iot hub configuration list.

Si la commande az iot hub state migrate échoue, essayez d’exécuter les commandes export et import séparément. Les deux commandes proviennent des mêmes fonctionnalités que la commande migrate seule, mais en les exécutant séparément, vous pouvez passer en revue les fichiers d’état créés à partir de la commande export.

Étapes suivantes

Pour plus d’informations sur l’exécution d’opérations en bloc sur le registre des identités dans un IoT Hub, consultez Importer et exporter des identités d’appareil IoT Hub.