Tutoriel : Automatiser le service Azure Device Provisioning avec GitHub Actions

Utilisez des outils d’automatisation comme GitHub Actions pour gérer votre cycle de vie d’appareil IoT. Ce tutoriel illustre un flux de travail GitHub Actions qui connecte un appareil à un hub IoT à l’aide d’Azure Device Provisioning Service (DPS).

Dans ce tutoriel, vous allez apprendre à :

Prerequisites

• Un abonnement Azure

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

• L'interface CLI de Azure

  • Utilisez l’environnement Bash dans Azure Cloud Shell.

  • Ou, si vous préférez exécuter des commandes de référence CLI localement, installez 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 dépôt que vous possédez ou un référentiel où vous disposez d’un accès administrateur. Pour plus d’informations, consultez Prise en main de GitHub.

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

Le flux de travail que vous définissez 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é dans lequel elles peuvent être découvertes. Nous utilisons plutôt des secrets de référentiel pour stocker ces informations, mais la rendre toujours accessible en tant que variable d’environnement dans le flux de travail. Pour plus d’informations, consultez Utilisation des secrets dans GitHub Actions.

Seuls les propriétaires et administrateurs du référentiel peuvent gérer les secrets du dépôt.

Créer un principal de service

Au lieu de fournir vos informations d’identification d’accès personnel, nous créons un principal de service, puis ajoutons ces informations d’identification en tant que secrets de référentiel. Utilisez Azure CLI pour créer un principal de service. Pour plus d’informations, consultez Créer un principal de service Azure avec Azure CLI.

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 :

   • ClientId.
   • clientSecret. Cette valeur est un mot de passe généré pour le principal de service auquel vous ne pouvez pas accéder à nouveau.
   • TenantId.

3. Utilisez la commande az role assignment create pour attribuer deux rôles d’accès supplémentaires au principal du service : Contributeur aux données du service Device Provisioning et Contributeur aux 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 sous forme de 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éez un secret pour votre identifiant du 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 le secret final.

8. Créez un secret pour votre instance 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’un événement déclenche le flux de travail. Un flux de travail contient un ou plusieurs travaux qui peuvent s’exécuter en parallèle ou séquentiellement. Pour plus d’informations, consultez Présentation des actions GitHub.

Pour ce tutoriel, nous créons 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 les unes aux autres.
• Créez une inscription individuelle sur l’instance DPS et inscrivez un appareil auprès du 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 situés dans le .github/workflows/ répertoire d’un référentiel.

1. Dans votre dépôt GitHub, accédez à l’onglet Actions .

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

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

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

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

   name: DPS Tutorial
   

6. Ajoutez le paramètre on.workflow_dispatch . Le on paramètre définit lorsqu’un flux de travail s’exécute. Le workflow_dispatch paramètre indique que nous voulons déclencher manuellement le flux de travail. Avec ce paramètre, nous pourrions définir inputs qui sera passé au flux de travail à chaque exécution, mais nous n’utilisons pas inputs 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 sont disponibles pour tous les travaux du flux de travail. Vous pouvez également définir des variables d’environnement pour des travaux individuels ou pour des étapes individuelles au sein des travaux.

   Remplacez les valeurs d’espace réservé par vos propres valeurs. Vérifiez que vous spécifiez 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 de travaux au fichier de flux de travail.

   jobs:
   

10. Définissez la première tâche de notre flux de travail, que nous appelons la tâche provision. Ce travail configure 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 ce travail utilise le paramètre needs, ce qui signifie que cette tâche ne s’exécute pas tant que la tâche répertoriée n’a pas terminé sa propre exécution avec succès.

      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 un travail appelé register qui crée une inscription individuelle, puis utilisez cette inscription pour inscrire un appareil auprès d’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   
    

    Note

    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 à partir de la session Microsoft Entra actuelle. L’alternative --auth-type key ne nécessite pas la configuration du principal de service, mais elle 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 - Cette commande crée un enregistrement d'appareil IoT.

13. Définir une tâche pour simulate un appareil IoT qui se connecte au hub IoT et envoie 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 travaux de simulation et de surveillance définissent tous les deux le travail d’inscription dans leur needs paramètre. Cette configuration signifie qu’une fois le travail d’inscription terminé, ces deux travaux s’exécutent 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 :

    • Utilisez la commande az iot hub monitor-events pour surveiller les événements de votre hub IoT Azure.

15. Le fichier de flux de travail complet doit ressembler à cet exemple, avec 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 dans votre dépôt GitHub.

3 - Exécuter le flux de travail

1. Accédez à l’onglet Actions de votre dépôt GitHub.

2. Dans le volet Actions , sélectionnez Didacticiel DPS, qui est le nom que nous avons défini dans le fichier de flux de travail, puis sélectionnez la zone de liste 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 de flux de travail est en cours d'exécution. Sélectionnez le nom pour afficher les détails de l’exécution.

5. Dans le résumé du flux de travail, vous pouvez regarder à mesure que chaque travail commence et se termine. Sélectionnez n’importe quel nom de travail pour afficher ses détails. Le travail 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 simulé 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. Lorsque toutes les tâches se terminent correctement, vous devez voir des coches vertes à côté de chacune.

   

Nettoyer les ressources

Si vous ne souhaitez pas continuer à utiliser ces ressources créées dans ce didacticiel, supprimez-les en procédant comme suit.

Utilisez Azure CLI :

1. Répertoriez les ressources de 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 où vous avez créé les nouvelles ressources.
2. Vous pouvez supprimer l’ensemble 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.