Esercitazione: Automatizzare il servizio Device Provisioning di Azure con GitHub Actions

Usare strumenti di automazione come GitHub Actions per gestire il ciclo di vita del dispositivo IoT. Questa esercitazione illustra un flusso di lavoro di GitHub Actions che connette un dispositivo a un hub IoT usando il servizio Device Provisioning di Azure.This tutorial demonstrates a GitHub Actions workflow that connects a device to an IoT hub using Azure Device Provisioning Service (DPS).

In questa esercitazione si apprenderà come:

• Salvare le credenziali di autenticazione come segreti del repository.
• Creare un flusso di lavoro per effettuare il provisioning delle risorse dell'hub IoT e del servizio Device Provisioning.
• Eseguire il flusso di lavoro e monitorare un dispositivo simulato durante la connessione all'hub IoT.

Prerequisiti

• Una sottoscrizione di Azure

  Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

• L'interfaccia della riga di comando di Azure

  • È possibile utilizzare l'ambiente Bash in Azure Cloud Shell.

  • In alternativa, se si preferisce eseguire i comandi di riferimento della CLI in locale, installare l'Azure CLI. Se si esegue in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

    • Se usi un'installazione locale, accedi all'interfaccia della riga di comando di Azure usando il comando az login.

    • Esegui az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, avviare az upgrade.

• Un account GitHub con un repository che possiedi o un repository in cui hai accesso come amministratore. Per altre informazioni, vedere Introduzione a GitHub.

1 - Creare le impostazioni riservate del repository

Il flusso di lavoro definito nella sezione successiva richiede l'accesso alla sottoscrizione di Azure per creare e gestire le risorse. Non si vuole inserire tali informazioni in un file non protetto in cui potrebbe essere individuato, quindi si usano i segreti del repository per archiviare queste informazioni, ma renderle comunque accessibili come variabile di ambiente nel flusso di lavoro. Per altre informazioni, vedere Uso dei segreti in GitHub Actions.

Solo i proprietari e gli amministratori del repository possono gestire i segreti del repository.

Creare un principale servizio

Invece di fornire le credenziali di accesso personali, creiamo un entità servizio principale e aggiungiamo quindi tali credenziali come segreti del repository. Usare l'interfaccia della riga di comando di Azure per creare un nuovo principale di servizio. Per altre informazioni, vedere Creare un'entità servizio di Azure con l'interfaccia della riga di comando di Azure.

1. Utilizzare il comando az ad sp create-for-rbac per creare un principale del servizio con accesso collaboratore a un gruppo di risorse specifico. Sostituire <SUBSCRIPTION_ID> e <RESOURCE_GROUP_NAME> con le informazioni personalizzate.

   Questo comando richiede ruoli di amministratore di accesso proprietario o utente nella sottoscrizione.

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

2. Copiare i seguenti dati dall'output del comando di creazione del principale servizio per utilizzarli nella sezione successiva.

   • ClientId.
   • clientSecret. Questo valore è una password generata per il principale del servizio a cui non potrai più accedere.
   • TenantId.

3. Usare il comando az role assignment create per assegnare due ulteriori ruoli di accesso all'entità servizio: Collaboratore ai dati del servizio di provisioning dei dispositivi e Collaboratore ai dati dell'hub IoT. Sostituire <SP_CLIENT_ID> con il valore clientId copiato dall'output del comando precedente.

   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>"
   

Salvare le credenziali del principale del servizio come segreti

1. In GitHub.com passare a Impostazioni per il repository.

2. Selezionare Segreti dal menu di spostamento, quindi selezionare Azioni.

3. Selezionare Nuovo segreto del repository.

4. Crea un segreto per l'ID principale del servizio.

   • Nome: APP_ID
   • Segreto: incollare il clientId copiato dall'output del comando di creazione dell'entità servizio.

5. Selezionare Aggiungi segreto e quindi nuovo segreto del repository per aggiungere un secondo segreto.

6. Creare un segreto per la password dell'entità servizio.

   • Nome: SECRET
   • Segreto: incollare il clientSecret copiato dall'output del comando di creazione dell'entità servizio.

7. Selezionare Aggiungi segreto, quindi selezionare Nuovo segreto del repository per aggiungere il segreto finale.

8. Crea una credenziale per il tenant di Azure.

   • Nome: TENANT
   • Segreto: incollare il tenantId copiato dall'output del comando di creazione dell'entità servizio.

9. Selezionare Aggiungi segreto.

2 - Creare un flusso di lavoro

Un flusso di lavoro di GitHub Actions definisce le attività eseguite dopo che un evento attiva il flusso di lavoro. Un flusso di lavoro contiene uno o più processi che possono essere eseguiti in parallelo o sequenziale. Per altre informazioni, vedere Informazioni su GitHub Actions.

Per questa esercitazione viene creato un flusso di lavoro contenente processi per ognuna delle attività seguenti:

• Eseguire il provisioning di un'istanza di IoT Hub e un'istanza di DPS.
• Collegare le istanze dell'hub IoT e del servizio Device Provisioning tra loro.
• Creare un'iscrizione individuale nell'istanza del servizio Device Provisioning (DPS) e registrare un dispositivo nell'hub IoT usando l'autenticazione con chiave simmetrica tramite l'iscrizione DPS.
• Simulare il dispositivo per cinque minuti e monitorare gli eventi dell'hub IoT.

I flussi di lavoro sono file YAML che si trovano nella .github/workflows/ directory di un repository.

1. Nel repository GitHub passare alla scheda Azioni .

2. Nel riquadro Azioni selezionare Nuovo flusso di lavoro.

3. Nella pagina Scegliere un flusso di lavoro è possibile scegliere modelli predefiniti da usare. Verrà creato un flusso di lavoro personalizzato per questa esercitazione, quindi selezionare Configura manualmente un flusso di lavoro.

4. GitHub crea automaticamente un nuovo file del flusso di lavoro. Si noti che si trova nella .github/workflows/ directory . Assegnare al nuovo file un nome significativo, ad esempio dps-tutorial.yml.

5. Aggiungere il parametro name per assegnare un nome al flusso di lavoro.

   name: DPS Tutorial
   

6. Aggiungere il parametro on.workflow_dispatch . Il on parametro definisce quando viene eseguito un flusso di lavoro. Il workflow_dispatch parametro indica che si vuole attivare manualmente il flusso di lavoro. Con questo parametro, è possibile definire inputs che verrebbe passato al flusso di lavoro in ogni esecuzione, ma non viene usato inputs per questa esercitazione.

   on: workflow_dispatch
   

7. Definire le variabili di ambiente per le risorse create nel flusso di lavoro. Queste variabili sono disponibili per tutti i processi nel flusso di lavoro. È anche possibile definire variabili di ambiente per singoli processi o per singoli passaggi all'interno dei processi.

   Sostituire i valori segnaposto con i propri valori. Assicurarsi di specificare lo stesso gruppo di risorse a cui il principale del servizio ha accesso.

   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. Definire le variabili di ambiente per i segreti creati nella sezione precedente.

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

9. Aggiungere il parametro jobs al file del flusso di lavoro.

   jobs:
   

10. Definire la prima attività per il flusso di lavoro, che chiamiamo attività provision. Questo processo effettua il provisioning delle istanze dell'hub IoT e del servizio Device Provisioning:

      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"
    

    Per altre informazioni sui comandi eseguiti in questo processo, vedere:

    • az iot hub create
    • az iot dps create

11. Definire un processo per configure le istanze del servizio Device Provisioning e dell'hub IoT. Si noti che questo processo usa il parametro needs , il che significa che il configure processo non viene eseguito fino a quando il processo elencato non completa correttamente la propria esecuzione.

      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"   
    

    Per altre informazioni sui comandi eseguiti in questo processo, vedere:

    • az iot dps linked-hub create

12. Definire un processo denominato register che crea una registrazione singola e quindi usarla per registrare un dispositivo nell'hub IoT.

      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   
    

    Annotazioni

    Questo processo e altri utilizzano il parametro --auth-type login in alcuni comandi per indicare che l'operazione deve usare l'entità servizio dalla sessione corrente di Microsoft Entra. L'alternativa --auth-type key non richiede la configurazione dell'entità servizio, ma è meno sicura.

    Per altre informazioni sui comandi eseguiti in questo processo, vedere:

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

13. Definire un processo per simulate un dispositivo IoT che si connette all'hub IoT e invierà esempi di messaggi di telemetria.

      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"
    

    Per altre informazioni sui comandi eseguiti in questo processo, vedere:

    • az iot device simulate

14. Definire un'attività per monitor l'endpoint dell'hub IoT per gli eventi e monitorare i messaggi provenienti dal dispositivo simulato. Si noti che i processi simulate e monitor definiscono entrambi il processo di registrazione nei loro needs parametri. Questa configurazione significa che una volta completato correttamente il processo di registrazione , entrambi questi processi vengono eseguiti in parallelo.

      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   
    

    Per altre informazioni sui comandi eseguiti in questo processo, vedere:

    • az iot hub monitor-events

15. Il file di configurazione del flusso di lavoro completo dovrebbe assomigliare a questo esempio, con le vostre informazioni che sostituiscono i valori segnaposto nelle variabili d'ambiente.

    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. Salvare, eseguire il commit e il push di questo nuovo file nel repository GitHub.

3 - Eseguire il flusso di lavoro

1. Passare alla scheda Azioni del repository GitHub.

2. Nel riquadro Azioni selezionare DPS Tutorial, ovvero il nome definito nel file del flusso di lavoro, quindi selezionare la casella a discesa Esegui flusso di lavoro .

   

3. Modificare il ramo se il flusso di lavoro è stato creato in un ramo diverso da main, quindi selezionare Esegui flusso di lavoro.

4. Viene visualizzata una nuova esecuzione del flusso di lavoro in corso. Selezionare il nome per visualizzare i dettagli dell'esecuzione.

5. Nel riepilogo del flusso di lavoro è possibile osservare l'inizio e il completamento di ogni processo. Selezionare un nome di attività per visualizzarne i dettagli. Il job del dispositivo simulato viene eseguito per cinque minuti e invia i dati di telemetria all'IoT Hub. Durante questo periodo di tempo, selezionare il processo simulato per controllare i messaggi inviati dal dispositivo e il processo di monitoraggio per osservare i messaggi ricevuti dall'hub IoT.

6. Al termine di tutti i lavori, verranno visualizzate le spunte verdi per ognuno di essi.

   

Pulire le risorse

Se non si intende continuare a usare queste risorse create in questa esercitazione, eliminarle con la procedura seguente.

Usare l'interfaccia della riga di comando di Azure:

1. Elenca le risorse nel tuo gruppo di risorse.

   az resource list --resource-group <RESOURCE_GROUP_NAME>
   

2. Per eliminare singole risorse, usare l'ID risorsa.

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

3. Se si vuole eliminare l'intero gruppo di risorse e tutte le risorse al suo interno, eseguire il comando seguente:

   az group delete --resource-group <RESOURCE_GROUP_NAME>
   

Usare il portale di Azure:

1. Nel portale di Azure passare al gruppo di risorse in cui sono state create le nuove risorse.
2. È possibile eliminare l'intero gruppo di risorse o selezionare le singole risorse da rimuovere, quindi selezionare Elimina.

Passaggi successivi

Scopri come effettuare il provisioning di istanze DPS con altri strumenti di automazione.

Esercitazione: Usare criteri di allocazione personalizzati con il servizio di provisioning di dispositivi (DPS)