Tutoriel : automatiser le service de provisionnement des appareils d’Azure avec GitHub Actions

Utilisez des outils d’automatisation tels que GitHub Actions pour gérer le cycle de vie de vos appareils IoT. Ce tutoriel montre un flux de travail GitHub Actions qui connecte un appareil à un hub IoT à l’aide du service de provisionnement des appareils d’Azure.

Dans ce tutoriel, vous allez apprendre à :

• Enregistrez les informations d’identification d’authentification en tant que secrets de référentiel.
• Créez un flux de travail pour provisionner des ressources IoT Hub et le service de provisionnement des appareils.
• Exécutez le flux de travail et surveillez un appareil simulé pendant qu’il se connecte à IoT Hub.

Prérequis

• Un abonnement Azure

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

• L’interface Azure CLI

  • Utilisez l’environnement Bash dans Azure Cloud Shell.

  • Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker.

    • Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login.

    • Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

• Un compte GitHub avec un référentiel dont vous êtes propriétaire ou dans lequel vous disposez d’un accès administrateur. Pour plus d’informations, consultez Bien démarrer avec GitHub.

1 - Créer des secrets de référentiel

Le flux de travail que vous allez définir dans la section suivante nécessite l’accès à votre abonnement Azure pour créer et gérer des ressources. Vous ne souhaitez pas placer ces informations dans un fichier non protégé où elles pourraient être découvertes. Nous allons donc utiliser des secrets de référentiel pour stocker ces informations tout en les rendant accessibles en tant que variable d’environnement dans le flux de travail. Pour plus d’informations, consultez « Secrets chiffrés ».

Seuls les propriétaires et administrateurs de référentiel peuvent gérer les secrets du référentiel.

Créer un principal du service

Au lieu de fournir vos informations d’identification d’accès personnelles, nous allons créer un principal de service, puis ajouter ces informations d’identification en tant que secrets de référentiel. Utilisez l’Azure CLI pour créer un nouveau principal de service. Pour plus d’informations, consultez l’article Créer un principal du service Azure.

1. Utilisez la commande az ad sp create-for-rbac pour créer un principal de service avec un accès contributeur à un groupe de ressources spécifique. Remplacez <SUBSCRIPTION_ID> et <RESOURCE_GROUP_NAME> par vos propres informations.

   Cette commande nécessite des rôles d’administrateur d’accès propriétaire ou utilisateur dans l’abonnement.

   az ad sp create-for-rbac --name github-actions-sp --role contributor --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
   

2. Copiez les éléments suivants à partir de la sortie de la commande de création du principal de service à utiliser dans la section suivante :

   • Le clientId.
   • The clientSecret. Il s’agit d’un mot de passe généré pour le principal de service auquel vous ne pourrez plus accéder.
   • Le tenantId.

3. Utilisez la commande az role assignment create pour attribuer deux rôles d’accès supplémentaires au principal de service : Contributeur de données de service de provisionnement des appareils et Contributeur de données IoT Hub. Remplacez <SP_CLIENT_ID> par la valeur clientId que vous avez copiée à partir de la sortie de la commande précédente.

   az role assignment create --assignee "<SP_CLIENT_ID>" --role "Device Provisioning Service Data Contributor" --resource-group "<RESOURCE_GROUP_NAME>"
   

   az role assignment create --assignee "<SP_CLIENT_ID>" --role "IoT Hub Data Contributor" --resource-group "<RESOURCE_GROUP_NAME>"
   

Enregistrer les informations d’identification du principal de service en tant que secrets

1. Sur GitHub.com, accédez aux paramètres de votre référentiel.

2. Sélectionnez Secrets dans le menu de navigation, puis sélectionnez Actions.

3. Sélectionnez New repository secret (Nouveau secret de dépôt).

4. Créer un secret pour votre ID de principal de service.

   • Nom : APP_ID
   • Secret : collez le clientId que vous avez copié à partir de la sortie de la commande de création du principal de service.

5. Sélectionnez Ajouter un secret, puis sélectionnez Nouveau secret de référentiel pour ajouter un deuxième secret.

6. Créez un secret pour votre mot de passe de principal de service.

   • Nom : SECRET
   • Secret : collez le clientSecret que vous avez copié à partir de la sortie de la commande de création du principal de service.

7. Sélectionnez Ajouter un secret, puis sélectionnez Nouveau secret de référentiel pour ajouter un secret final.

8. Créez un secret pour votre locataire Azure.

   • Nom : TENANT
   • Secret : collez le tenantId que vous avez copié à partir de la sortie de la commande de création du principal de service.

9. Sélectionnez Ajouter un secret.

2 - Créer un flux de travail

Un flux de travail GitHub Actions définit les tâches qui s’exécutent une fois qu’il est déclenché par un événement. Un flux de travail contient un ou plusieurs travaux qui peuvent s’exécuter en parallèle ou de manière séquentielle. Pour plus d’informations, consultez Comprendre GitHub Actions.

Pour ce tutoriel, nous allons créer un flux de travail qui contient des travaux pour chacune des tâches suivantes :

• Provisionnez une instance IoT Hub et une instance DPS.
• Liez les instances IoT Hub et DPS entre elles.
• Créez une inscription individuelle sur l’instance DPS et inscrivez un appareil auprès sur le hub IoT à l’aide de l’authentification par clé symétrique via l’inscription DPS.
• Simulez l’appareil pendant cinq minutes et surveillez les événements IoT Hub.

Les flux de travail sont des fichiers YAML qui se trouvent dans le répertoire d’un référentiel .github/workflows/.

1. Dans votre référentiel GitHub, accédez à l’onglet Actions.

2. Dans le volet Actions , sélectionnez Nouveau flux de travail.

3. Dans Choisir une page de flux de travail, vous pouvez choisir des modèles prédéfinis à utiliser. Nous allons créer votre propre flux de travail pour ce tutoriel. Sélectionnez donc Configurer un flux de travail vous-même.

4. GitHub crée un nouveau fichier de flux de travail pour vous. Notez qu’il se trouve dans le répertoire .github/workflows/. Donnez au nouveau fichier un nom explicite, par exemple dps-tutorial.yml.

5. Ajoutez le paramètre name pour donner un nom à votre flux de travail.

   name: DPS Tutorial
   

6. Ajoutez le paramètre on.workflow_dispatch. Le paramètre on définit le moment où un flux de travail s’exécutera. Le paramètre workflow_dispatch indique que nous voulons déclencher manuellement le flux de travail. Avec ce paramètre, nous pourrions définir inputs qui serait passé au flux de travail à chaque exécution, mais nous ne les utiliserons pas pour ce tutoriel.

   on: workflow_dispatch
   

7. Définissez les variables d’environnement pour les ressources que vous créez dans le flux de travail. Ces variables seront disponibles pour toutes les tâches du flux de travail. Vous pouvez également définir des variables d’environnement pour des tâches individuelles ou pour des étapes individuelles dans des tâches.

   Remplacez les valeurs d’espace réservé par vos propres valeurs. Veillez à spécifier le même groupe de ressources auquel le principal de service a accès.

   env:
     HUB_NAME: <Globally unique IoT hub name>
     DPS_NAME: <Desired Device Provisioning Service name>
     DEVICE_NAME: <Desired device name>
     RESOURCE_GROUP: <Solution resource group where resources will be created>
   

8. Définissez des variables d’environnement pour les secrets que vous avez créés dans la section précédente.

     SP_USER: ${{ secrets.APP_ID }}
     SP_SECRET: ${{ secrets.SECRET }}
     SP_TENANT: ${{ secrets.TENANT }}
   

9. Ajoutez le paramètre jobs au fichier de flux de travail.

   jobs:
   

10. Définissez la première tâche de notre flux de travail, que nous appellerons la tâche provision. Cette tâche approvisionne les instances IoT Hub et DPS :

      provision:
        runs-on: ubuntu-latest
        steps:
          - name: Provision Infra
            run: |
              az --version
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot hub create -n "$HUB_NAME" -g "$RESOURCE_GROUP"
              az iot dps create -n "$DPS_NAME" -g "$RESOURCE_GROUP"
    

    Pour plus d’informations sur les commandes exécutées dans ce travail, consultez :

    • az iot hub create
    • az iot dps create

11. Définissez une tâche pour configure les instances DPS et IoT Hub. Notez que cette tâche utilise le paramètre needs, ce qui signifie qu’elle ne s’exécutera pas tant que la tâche configure n’aura pas terminé sa propre exécution.

      configure:
        runs-on: ubuntu-latest
        needs: provision
        steps:
          - name: Configure Infra
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot dps linked-hub create --dps-name "$DPS_NAME" --hub-name "$HUB_NAME"   
    

    Pour plus d’informations sur les commandes exécutées dans ce travail, consultez :

    • az iot dps linked-hub create

12. Définissez une tâche appelée register qui va créer une inscription individuelle, puis utilisez cette inscription pour inscrire un appareil à IoT Hub.

      register:
        runs-on: ubuntu-latest
        needs: configure
        steps:
          - name: Create enrollment
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot dps enrollment create -n "$DPS_NAME" --eid "$DEVICE_NAME" --attestation-type symmetrickey --auth-type login
          - name: Register device
            run: |
              az iot device registration create -n "$DPS_NAME" --rid "$DEVICE_NAME" --auth-type login   
    

    Remarque

    Ce travail et d’autres utilisent le paramètre --auth-type login dans certaines commandes pour indiquer que l’opération doit utiliser le principal de service de la session Microsoft Entra actuelle. L’alternative --auth-type key ne nécessite pas la configuration du principal de service, mais est moins sécurisée.

    Pour plus d’informations sur les commandes exécutées dans ce travail, consultez :

    • az iot dps enrollment create
    • az iot device registration create

13. Définissez une tâche sur un appareil IoT simulate qui se connectera au hub IoT et enverra des exemples de messages de télémétrie.

      simulate:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Simulate device
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot device simulate -n "$HUB_NAME" -d "$DEVICE_NAME"
    

    Pour plus d’informations sur les commandes exécutées dans ce travail, consultez :

    • az iot device simulate

14. Définissez une tâche sur le point de terminaison IoT Hub pour les événements monitor et surveillez les messages provenant de l’appareil simulé. Notez que les tâches de simulation et de surveillance définissent tous deux la tâche d’inscription dans leur paramètre needs. Cette configuration signifie qu’une fois la tâche d’inscription terminée, ces deux travaux s’exécuteront en parallèle.

      monitor:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Monitor d2c telemetry
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot hub monitor-events -n "$HUB_NAME" -y   
    

    Pour plus d’informations sur les commandes exécutées dans ce travail, consultez :

    • az iot hub monitor-events

15. Le fichier de flux de travail complet doit ressembler à cet exemple, vos informations remplaçant les valeurs d’espace réservé dans les variables d’environnement :

    name: DPS Tutorial
    
    on: workflow_dispatch
    
    env:
      HUB_NAME: <Globally unique IoT hub name>
      DPS_NAME: <Desired Device Provisioning Service name>
      DEVICE_NAME: <Desired device name>
      RESOURCE_GROUP: <Solution resource group where resources will be created>
      SP_USER: ${{ secrets.APP_ID }}
      SP_SECRET: ${{ secrets.SECRET }}
      SP_TENANT: ${{ secrets.TENANT }}
    
    jobs:
      provision:
        runs-on: ubuntu-latest
        steps:
          - name: Provision Infra
            run: |
              az --version
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot hub create -n "$HUB_NAME" -g "$RESOURCE_GROUP"
              az iot dps create -n "$DPS_NAME" -g "$RESOURCE_GROUP"
      configure:
        runs-on: ubuntu-latest
        needs: provision
        steps:
          - name: Configure Infra
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az iot dps linked-hub create --dps-name "$DPS_NAME" --hub-name "$HUB_NAME"
      register:
        runs-on: ubuntu-latest
        needs: configure
        steps:
          - name: Create enrollment
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot dps enrollment create -n "$DPS_NAME" --eid "$DEVICE_NAME" --attestation-type symmetrickey --auth-type login
          - name: Register device
            run: |
              az iot device registration create -n "$DPS_NAME" --rid "$DEVICE_NAME" --auth-type login
      simulate:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Simulate device
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot device simulate -n "$HUB_NAME" -d "$DEVICE_NAME"
      monitor:
        runs-on: ubuntu-latest
        needs: register
        steps:
          - name: Monitor d2c telemetry
            run: |
              az login --service-principal -u "$SP_USER" -p "$SP_SECRET" --tenant "$SP_TENANT"
              az extension add --name azure-iot
              az iot hub monitor-events -n "$HUB_NAME" -y
    

16. Enregistrez, validez et envoyez (push) ce nouveau fichier vers votre référentiel GitHub.

3 - Exécuter le flux de travail

1. Accédez à l’onglet Actions dans votre référentiel GitHub.

2. Dans le volet Actions, sélectionnez Tutoriel DPS, qui est le nom que nous avons défini dans le fichier de flux de travail, puis sélectionnez la zone déroulante Exécuter le flux de travail.

   

3. Modifiez la branche si vous avez créé votre flux de travail dans une branche autre que principale, puis sélectionnez Exécuter le flux de travail.

4. Une nouvelle exécution du flux de travail apparaît en cours. Sélectionnez le nom pour afficher les détails de l’exécution.

5. Dans le résumé du flux de travail, vous pouvez observer le début et la fin de chaque tâche. Sélectionnez le nom d’une tâche pour en afficher les détails. La tâche d’appareil simulé s’exécute pendant cinq minutes et envoie des données de télémétrie à IoT Hub. Pendant ce temps, sélectionnez le travail de simulation pour surveiller les messages envoyés à partir de l’appareil, et le travail de surveillance pour surveiller ces messages reçus par IoT Hub.

6. Une fois que toutes les tâches se sont terminées correctement, vous devez voir des coches vertes sur chacune d’elles.

   

Nettoyer les ressources

Si vous ne pensez pas continuer à utiliser ces ressources créées dans ce tutoriel, supprimez-les en effectuant les étapes suivantes :

Via Azure CLI :

1. Répertoriez les ressources dans votre groupe de ressources.

   az resource list --resource-group <RESOURCE_GROUP_NAME>
   

2. Pour supprimer des ressources individuelles, utilisez l’ID de ressource.

   az resource delete --resource-group <RESOURCE_GROUP_NAME> --ids <RESOURCE_ID>
   

3. Si vous souhaitez supprimer l’ensemble du groupe de ressources et toutes les ressources qu’il contient, exécutez la commande suivante :

   az group delete --resource-group <RESOURCE_GROUP_NAME>
   

Utilisez le portail Azure :

1. Dans le Portail Azure, accédez au groupe de ressources dans lequel vous avez créé les nouvelles ressources.
2. Vous pouvez supprimer l’intégralité du groupe de ressources ou sélectionner les ressources individuelles que vous souhaitez supprimer, puis sélectionner Supprimer.

Étapes suivantes

Découvrez comment provisionner des instances DPS avec d’autres outils d’automatisation.

Configurer DPS avec Bicep