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

Articolo
10/18/2023

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 apprenderai a:

Salvare le credenziali di autenticazione come segreti del repository.
Creare un flusso di lavoro per effettuare il provisioning di hub IoT e le risorse del servizio Device Provisioning.
Eseguire il flusso di lavoro e monitorare un dispositivo simulato durante la connessione a 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
- Usare l'ambiente Bash in Azure Cloud Shell.
- In alternativa, se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Se si esegue in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
  - Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login.
  - Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.
Un account GitHub con un repository proprietario o un repository in cui si ha accesso amministratore. Per altre informazioni, vedere Introduzione a GitHub.

1 - Creare segreti del repository

Il flusso di lavoro che verrà 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 useranno i segreti del repository per archiviare queste informazioni, ma renderle comunque accessibili come variabile di ambiente nel flusso di lavoro. Per altre informazioni, vedere Segreti crittografati.

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

Creare un'entità servizio

Invece di fornire le credenziali di accesso personale, si creerà un'entità servizio e quindi si aggiungeranno tali credenziali come segreti del repository. Usare l'interfaccia della riga di comando di Azure per creare una nuova entità servizio. Per altre informazioni, vedere Creare un'entità servizio di Azure.

Usare il comando az ad sp create-for-rbac per creare un'entità 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>
```
Copiare gli elementi seguenti dall'output del comando di creazione dell'entità servizio da usare nella sezione successiva:
- ClientId.
- ClientSecret. Si tratta di una password generata per l'entità servizio a cui non sarà possibile accedere di nuovo.
- TenantId.

Usare il comando az role assignment create per assegnare due ruoli di accesso all'entità servizio: Collaboratore ai dati del servizio Device Provisioning e Collaboratore dati 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 dell'entità servizio come segreti

In GitHub.com passare al Impostazioni per il repository.
Selezionare Segreti dal menu di spostamento, quindi selezionare Azioni.
Selezionare Nuovo segreto repository.
Creare un segreto per l'ID entità servizio.
- Nome: APP_ID
- Segreto: incollare l'ID client copiato dall'output del comando di creazione dell'entità servizio.
Selezionare Aggiungi segreto e quindi nuovo segreto del repository per aggiungere un secondo segreto.
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.
Selezionare Aggiungi segreto, quindi selezionare Nuovo segreto del repository per aggiungere il segreto finale.
Creare un segreto per il tenant di Azure.
- Nome: TENANT
- Segreto: incollare l'ID tenant copiato dall'output del comando di creazione dell'entità servizio.
Selezionare Aggiungi segreto.

2 - Creare un flusso di lavoro

Un flusso di lavoro di GitHub Actions definisce le attività che verranno eseguite una volta attivate da un evento. Un flusso di lavoro contiene uno o più processi che possono essere eseguiti in parallelo o in sequenza. Per altre informazioni, vedere Informazioni su GitHub Actions.

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

Effettuare il provisioning di un'istanza di hub IoT e di un'istanza del servizio Device Provisioning.
Collegare tra loro le istanze di hub IoT e DPS.
Creare una registrazione singola nell'istanza del servizio Device Provisioning e registrare un dispositivo nell'hub IoT usando l'autenticazione con chiave simmetrica tramite la registrazione 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.

Nel repository GitHub passare alla scheda Azioni .
Nel riquadro Azioni selezionare Nuovo flusso di lavoro.
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.
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.
Aggiungere il parametro name per assegnare un nome al flusso di lavoro.
```
name: DPS Tutorial
```
Aggiungere il parametro on.workflow_dispatch . Il on parametro definisce quando verrà 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 verranno usati per questa esercitazione.
```
on: workflow_dispatch
```
Definire le variabili di ambiente per le risorse create nel flusso di lavoro. Queste variabili saranno 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 l'entità 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>
```

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

Aggiungere il parametro jobs al file del flusso di lavoro.
```
jobs:
```

Definire il primo processo per il flusso di lavoro, che verrà chiamato il provision processo. Questo processo effettua il provisioning delle istanze di hub IoT e 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"

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

Definire un processo per il servizio Device Provisioning configure e le istanze di hub IoT. Si noti che questo processo usa il parametro needs , il che significa che il processo non verrà eseguito fino a quando il configure 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
Definire un processo denominato register che creerà una registrazione singola e quindi userà tale registrazione per registrare un dispositivo per 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   
```
Nota

Questo processo e altri usano 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 non --auth-type key 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

Definire un processo a simulate un dispositivo IoT che si connetterà all'hub IoT e invierà messaggi di telemetria di esempio.

  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

Definire un processo per monitor l'endpoint dell'hub IoT per gli eventi e controllare i messaggi provenienti dal dispositivo simulato. Si noti che i processi simulati e monitorano entrambi il processo di registrazione nel relativo needs parametro. Questa configurazione significa che una volta completato correttamente il processo di registrazione , entrambi questi processi verranno 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

Il file del flusso di lavoro completo dovrebbe essere simile a questo esempio, con le informazioni che sostituiscono i valori segnaposto nelle variabili di 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

Salvare, eseguire il commit e il push di questo nuovo file nel repository GitHub.

3 - Eseguire il flusso di lavoro

Passare alla scheda Azioni del repository GitHub.
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.
Modificare il ramo se il flusso di lavoro è stato creato in un ramo diverso da main, quindi selezionare Esegui flusso di lavoro.
Viene visualizzata una nuova esecuzione del flusso di lavoro in corso. Selezionare il nome per visualizzare i dettagli dell'esecuzione.
Nel riepilogo del flusso di lavoro è possibile osservare l'inizio e il completamento di ogni processo. Selezionare un nome di processo per visualizzarne i dettagli. Il processo del dispositivo simulato viene eseguito per cinque minuti e invia i dati di telemetria a hub IoT. Durante questo periodo di tempo, selezionare il processo simulato per controllare i messaggi inviati dal dispositivo e il processo di monitoraggio per controllare i messaggi ricevuti da hub IoT.
Quando tutti i processi sono stati completati correttamente, verranno visualizzati segni di spunta 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.

Usando l'interfaccia della riga di comando di Azure:

Elencare le risorse nel gruppo di risorse.

az resource list --resource-group <RESOURCE_GROUP_NAME>

Per eliminare singole risorse, usare l'ID risorsa.

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

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:

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

Passaggi successivi

Informazioni su come effettuare il provisioning di istanze del servizio Device Provisioning con altri strumenti di automazione.

Configurare il servizio Device Provisioning con Bicep

Condividi tramite