Tutorial: Automatisieren des Azure Device Provisioning Service mit GitHub Actions

Artikel
03/09/2023

Mithilfe von Automatisierungstools wie GitHub Actions können Sie den Lebenszyklus Ihres IoT-Geräts verwalten. In diesem Tutorial wird ein GitHub Actions-Workflow gezeigt, der ein Gerät mithilfe von Azure Device Provisioning Service (DPS) mit einem IoT-Hub verbindet.

In diesem Tutorial lernen Sie Folgendes:

Speichern Sie Authentifizierungsanmeldeinformationen als Repositorygeheimnisse.
Erstellen Sie einen Workflow zum Bereitstellen von IoT Hub- und Device Provisioning Service-Ressourcen.
Führen Sie den Workflow aus, und überwachen Sie ein simuliertes Gerät, während es eine Verbindung mit IoT Hub herstellt.

Voraussetzungen

Ein Azure-Abonnement

Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.
Die Azure CLI
- Verwenden Sie die Bash-Umgebung in Azure Cloud Shell.
- Wenn Sie CLI-Referenzbefehle aber lieber lokal ausführen möchten, installieren Sie die Azure-Befehlszeilenschnittstelle (Azure CLI). Wenn Sie unter Windows oder macOS arbeiten, sollten Sie die Azure CLI in einem Docker-Container ausführen.
  - Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an.
  - Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.
Ein GitHub-Konto mit einem Repository, das Sie selbst besitzen, oder einem Repository, bei dem Sie Administratorzugriff haben. Weitere Informationen finden Sie unter Erste Schritte mit GitHub.

1 – Erstellen von Repositorygeheimnissen

Der Workflow, den Sie im nächsten Abschnitt definieren werden, erfordert Zugriff auf Ihr Azure-Abonnement, um Ressourcen erstellen und verwalten zu können. Sie möchten diese Informationen nicht in eine ungeschützte Datei einfügen, in der sie gefunden werden könnten. Deshalb verwenden Sie stattdessen Repositorygeheimnisse, um diese Informationen zu speichern, aber als Umgebungsvariable im Workflow weiterhin zugänglich zu machen. Weitere Informationen finden Sie unter Verschlüsselte Geheimnisse.

Nur Repositorybesitzer und Administratoren können Repositorygeheimnisse verwalten.

Erstellen eines Dienstprinzipals

Statt Ihre persönlichen Zugriffsanmeldeinformationen bereitzustellen, erstellen Sie einen Dienstprinzipal und fügen dann diese Anmeldeinformationen als Repositorygeheimnisse hinzu. Verwenden Sie die Azure CLI zum Erstellen eines neuen Dienstprinzipals. Weitere Informationen finden Sie unter Erstellen eines Azure-Dienstprinzipals.

Verwenden Sie den Befehl az ad sp create-for-rbac, um einen Dienstprinzipal mit Zugriff als Mitwirkender auf eine bestimmte Ressourcengruppe zu erstellen. Ersetzen Sie <SUBSCRIPTION_ID> und <RESOURCE_GROUP_NAME> durch Ihre eigenen Angaben.

Für diesen Befehl sind Rollen des Typs „Besitzer“ oder „Benutzerzugriffsadministrator“ im Abonnement erforderlich.
```
az ad sp create-for-rbac --name github-actions-sp --role contributor --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
```
Kopieren Sie die folgenden Elemente aus der Ausgabe des Befehls zum Erstellen des Dienstprinzipals, um sie im nächsten Abschnitt zu verwenden:
- clientId.
- clientSecret. Dies ist ein generiertes Kennwort für den Dienstprinzipal, auf das Sie später nicht mehr zugreifen können.
- tenantId.
Verwenden Sie den Befehl az role assignment create, um dem Dienstprinzipal zwei weitere Zugriffsrollen zuzuweisen: Mitwirkender an Daten des Device Provisioning Service und IoT Hub-Datenmitwirkender. Ersetzen Sie <SP_CLIENT_ID> durch den clientId-Wert, den Sie aus der Ausgabe des vorherigen Befehls kopiert haben.
```
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>"
```

Speichern von Anmeldeinformationen für den Dienstprinzipal als Geheimnisse

Navigieren Sie unter GitHub.com zu den Einstellungen für Ihr Repository.
Wählen Sie im Navigationsmenü die Option Geheimnisse und dann Aktionen aus.
Wählen Sie New repository secret (Neues Repositorygeheimnis) aus.
Erstellen Sie ein Geheimnis für Ihre Dienstprinzipal-ID.
- Name: APP_ID
- Geheimnis: Fügen Sie den clientId-Wert ein, den Sie aus der Ausgabe des Befehls zum Erstellen des Dienstprinzipals kopiert haben.
Wählen Sie Geheimnis hinzufügen und dann Neues Repositorygeheimnis aus, um ein zweites Geheimnis hinzuzufügen.
Erstellen Sie ein Geheimnis für Ihr Dienstprinzipalkennwort.
- Name: SECRET
- Geheimnis: Fügen Sie den clientSecret-Wert ein, den Sie aus der Ausgabe des Befehls zum Erstellen des Dienstprinzipals kopiert haben.
Wählen Sie Geheimnis hinzufügen und dann Neues Repositorygeheimnis aus, um das endgültige Geheimnis hinzuzufügen.
Erstellen Sie ein Geheimnis für Ihren Azure-Mandanten.
- Name: TENANT
- Geheimnis: Fügen Sie den tenantId-Wert ein, den Sie aus der Ausgabe des Befehls zum Erstellen des Dienstprinzipals kopiert haben.
Klicken Sie auf Add secret (Geheimnis hinzufügen).

2 – Erstellen eines Workflows

Ein GitHub Actions-Workflow definiert die Aufgaben, die ausgeführt werden, sobald er durch ein Ereignis ausgelöst wurde. Ein Workflow enthält einen oder mehrere Aufträge, die parallel oder nacheinander ausgeführt werden können. Weitere Informationen finden Sie unter Grundlegendes zu GitHub Actions.

Für dieses Tutorial erstellen Sie einen einzigen Workflow, der Aufträge für jede der folgenden Aufgaben enthält:

Stellen Sie eine IoT Hub-Instanz und eine DPS-Instanz bereit.
Verknüpfen Sie die IoT Hub- und DPS-Instanzen miteinander.
Erstellen Sie eine eigene Registrierung auf der DPS-Instanz, und registrieren Sie ein Gerät beim IoT-Hub. Verwenden Sie dabei die Authentifizierung mit symmetrischen Schlüsseln über die DPS-Registrierung.
Simulieren Sie das Gerät fünf Minuten lang, und überwachen Sie die IoT-Hub-Ereignisse.

Workflows sind YAML-Dateien, die im Verzeichnis .github/workflows/ eines Repositorys gespeichert werden.

Navigieren Sie in Ihrem GitHub-Repository zur Registerkarte Aktionen.
Wählen Sie im Bereich Aktionen die Option Neuer Workflow aus.
Auf der Seite Workflow auswählen können Sie vordefinierte Vorlagen auswählen, die verwendet werden sollen. Weil Sie für dieses Tutorial Ihren eigenen Workflow erstellen, wählen Sie Workflow selbst einrichten aus.
GitHub erstellt für Sie eine neue Workflowdatei. Diese Datei wird im Verzeichnis .github/workflows/ gespeichert. Geben Sie der neuen Datei einen aussagekräftigen Namen, z. B. dps-tutorial.yml.
Fügen Sie den Parameter name hinzu, um Ihrem Workflow einen Namen zu geben.
```
name: DPS Tutorial
```
Fügen Sie den Parameter on.workflow_dispatch hinzu. Der Parameter on definiert, wann ein Workflow ausgeführt wird. Der Parameter workflow_dispatch gibt an, dass der Workflow manuell ausgelöst werden soll. Mit diesem Parameter könnten Sie den Wert inputs definieren, der bei jeder Ausführung an den Workflow übergeben würde, aber Sie verwenden ihn nicht für dieses Tutorial.
```
on: workflow_dispatch
```
Definieren Sie die Umgebungsvariablen für die Ressourcen, die Sie im Workflow erstellen. Diese Variablen sind für alle Aufträge im Workflow verfügbar. Sie können Umgebungsvariablen auch für einzelne Aufträge oder für einzelne Schritte innerhalb von Aufträgen definieren.

Ersetzen Sie die Platzhalterwerte durch eigene Werte. Dabei müssen Sie dieselbe Ressourcengruppe angeben, auf die der Dienstprinzipal Zugriff hat.
```
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>
```
Definieren Sie Umgebungsvariablen für die Geheimnisse, die Sie im vorhergehenden Abschnitt erstellt haben.
```
  SP_USER: ${{ secrets.APP_ID }}
  SP_SECRET: ${{ secrets.SECRET }}
  SP_TENANT: ${{ secrets.TENANT }}
```
Fügen Sie der Workflowdatei den Parameter jobs hinzu.
```
jobs:
```

Definieren Sie den ersten Auftrag für Ihren Workflow, den Sie als Auftrag provision (Bereitstellen) bezeichnen werden. Dieser Auftrag stellt die IoT Hub- und DPS-Instanzen bereit:

  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"

Weitere Informationen zu den Befehlen, die in diesem Auftrag ausgeführt werden, finden Sie hier:

Definieren Sie einen Auftrag zum Konfigurieren (configure) der DPS- und IoT Hub-Instanzen. Beachten Sie, dass bei diesem Auftrag der Parameter needs (erforderlich) verwendet wird. Dies bedeutet, dass der Auftrag configure erst ausgeführt wird, wenn der aufgelistete Auftrag seine eigene Ausführung erfolgreich abgeschlossen hat.
```
  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"   
```
Weitere Informationen zu den Befehlen, die in diesem Auftrag ausgeführt werden, finden Sie hier:
- az iot dps linked-hub create
Definieren Sie den Auftrag register, der eine individuelle Registrierung erstellt. Verwenden Sie diese Registrierung dann zum Registrieren eines Geräts bei 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   
```
Hinweis

Dieser Auftrag und andere Aufträge verwenden den --auth-type login-Parameter in einigen Befehlen, um anzugeben, dass der Vorgang den Dienstprinzipal aus der aktuellen Microsoft Entra-Sitzung verwenden soll. Die Alternative, --auth-type key, erfordert keine Dienstprinzipalkonfiguration, ist aber weniger sicher.

Weitere Informationen zu den Befehlen, die in diesem Auftrag ausgeführt werden, finden Sie hier:
- az iot dps enrollment create
- az iot device registration create

Definieren Sie einen Auftrag zum simulate (Simulieren) eines IoT-Geräts, das eine Verbindung mit dem IoT-Hub herstellt und Beispieltelemetrienachrichten sendet.

  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"

Weitere Informationen zu den Befehlen, die in diesem Auftrag ausgeführt werden, finden Sie hier:

az iot device simulate

Definieren Sie einen Auftrag zum monitor (Überwachen) des IoT Hub-Endpunkts für Ereignisse, und beobachten Sie Nachrichten, die vom simulierten Gerät eingehen. Beachten Sie, dass die Aufträge simulate und monitor in ihrem Parameter needs den Auftrag register (Registrieren) definieren. Diese Konfiguration bedeutet, dass beide Aufträge parallel ausgeführt werden, sobald der Auftrag register erfolgreich abgeschlossen wurde.
```
  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   
```
Weitere Informationen zu den Befehlen, die in diesem Auftrag ausgeführt werden, finden Sie hier:
- az iot hub monitor-events

Die vollständige Workflowdatei sollte wie in diesem Beispiel aussehen, wobei Ihre Informationen die Platzhalterwerte in den Umgebungsvariablen ersetzen:

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

Speichern, committen und pushen Sie diese neue Datei in Ihr GitHub-Repository.

3 – Ausführen des Workflows

Navigieren Sie in Ihrem GitHub-Repository zur Registerkarte Aktionen.
Wählen Sie im Bereich Aktionen die Option DPS-Tutorial aus. Das ist der Name, den Sie in der Workflowdatei definiert haben. Wählen Sie dann das Dropdownfeld Workflow ausführen aus.
Ändern Sie den Branch, wenn Sie Ihren Workflow in einem anderen Branch als dem Mainbranch erstellt haben, und wählen Sie Workflow ausführen aus.
Eine neue Workflowausführung wird als „In Bearbeitung“ angezeigt. Wählen Sie den Namen aus, um Details zur Ausführung anzuzeigen.
In der Workflowzusammenfassung können Sie beobachten, wie jeder Auftrag beginnt und abgeschlossen wird. Wählen Sie einen beliebigen Auftragsnamen aus, um dessen Details anzuzeigen. Der simulierte Geräteauftrag wird fünf Minuten lang ausgeführt und sendet Telemetriedaten an IoT Hub. Wählen Sie während dieser Zeit den Auftrag simulate aus, um zu beobachten, wie Nachrichten vom Gerät gesendet werden, und den Auftrag monitor aus, um zu beobachten, wie diese Nachrichten von IoT Hub empfangen werden.
Wenn alle Aufträge erfolgreich abgeschlossen wurden, sollten dazu jeweils grüne Häkchen angezeigt werden.

Bereinigen von Ressourcen

Falls Sie die in diesem Tutorial erstellten Ressourcen nicht weiterverwenden möchten, löschen Sie sie mit den folgenden Schritten.

Verwenden der Azure-Befehlszeilenschnittstelle:

Listen Sie die Ressourcen in Ihrer Ressourcengruppe auf.

az resource list --resource-group <RESOURCE_GROUP_NAME>

Verwenden Sie die Ressourcen-ID zum Löschen von einzelnen Ressourcen.

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

Wenn Sie die gesamte Ressourcengruppe und alle darin enthaltenen Ressourcen löschen möchten, führen Sie den folgenden Befehl aus:
```
az group delete --resource-group <RESOURCE_GROUP_NAME>
```

Verwenden des Azure-Portals:

Navigieren Sie im Azure-Portal zu der Ressourcengruppe, in der Sie die neuen Ressourcen erstellt haben.
Sie können entweder die gesamte Ressourcengruppe löschen oder die einzelnen Ressourcen auswählen, die Sie entfernen möchten, und dann Löschen auswählen.

Nächste Schritte

Informieren Sie sich, wie Sie DPS-Instanzen mit anderen Automatisierungstools bereitstellen können.

Einrichten von DPS mit Bicep

Freigeben über