Självstudie: Automatisera Azure Device Provisioning Service med GitHub Actions

Artikel
03/09/2023

Använd automatiseringsverktyg som GitHub Actions för att hantera IoT-enhetens livscykel. Den här självstudien visar ett GitHub Actions-arbetsflöde som ansluter en enhet till en IoT-hubb med hjälp av Azure Device Provisioning Service (DPS).

I den här självstudien lär du dig att:

Spara autentiseringsuppgifter som lagringsplatshemligheter.
Skapa ett arbetsflöde för att etablera IoT Hub- och Device Provisioning Service-resurser.
Kör arbetsflödet och övervaka en simulerad enhet när den ansluter till IoT Hub.

Förutsättningar

En Azure-prenumeration

Om du inte har någon Azure-prenumeration skapar du ett kostnadsfritt konto innan du börjar.
Azure CLI
- Använd Bash-miljön i Azure Cloud Shell.
- Om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI. Om du kör i Windows eller macOS kan du överväga att köra Azure CLI i en Docker-container.
  - Om du använder en lokal installation loggar du in på Azure CLI med hjälp av kommandot az login.
  - Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.
Ett GitHub-konto med antingen en lagringsplats som du äger eller en lagringsplats där du har administratörsåtkomst. Mer information finns i Kom igång med GitHub.

1 – Skapa lagringsplatshemligheter

Arbetsflödet som du ska definiera i nästa avsnitt kräver åtkomst till din Azure-prenumeration för att skapa och hantera resurser. Du vill inte placera den informationen i en oskyddad fil där den kan identifieras, så i stället använder vi lagringsplatshemligheter för att lagra den här informationen men ändå göra den tillgänglig som en miljövariabel i arbetsflödet. Mer information finns i Krypterade hemligheter.

Endast lagringsplatsägare och administratörer kan hantera lagringsplatshemligheter.

Skapa ett huvudnamn för tjänsten

I stället för att ange dina autentiseringsuppgifter för personlig åtkomst skapar vi ett huvudnamn för tjänsten och lägger sedan till dessa autentiseringsuppgifter som lagringsplatshemligheter. Använd Azure CLI för att skapa ett nytt huvudnamn för tjänsten. Mer information finns i Skapa ett huvudnamn för Azure-tjänsten.

Använd kommandot az ad sp create-for-rbac för att skapa ett tjänsthuvudnamn med deltagaråtkomst till en specifik resursgrupp. Ersätt <SUBSCRIPTION_ID> och <RESOURCE_GROUP_NAME> med din egen information.

Det här kommandot kräver administratörsroller för ägare eller användare i prenumerationen.
```
az ad sp create-for-rbac --name github-actions-sp --role contributor --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
```
Kopiera följande objekt från utdata från kommandot för att skapa tjänstens huvudnamn som ska användas i nästa avsnitt:
- ClientId.
- ClientSecret. Det här är ett genererat lösenord för tjänstens huvudnamn som du inte kommer att kunna komma åt igen.
- TenantId.
Använd kommandot az role assignment create för att tilldela ytterligare två åtkomstroller till tjänstens huvudnamn: Device Provisioning Service Data Contributor och IoT Hub Data Contributor. Ersätt <SP_CLIENT_ID> med värdet clientId som du kopierade från föregående kommandos utdata.
```
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>"
```

Spara autentiseringsuppgifter för tjänstens huvudnamn som hemligheter

På GitHub.com navigerar du till Inställningar för lagringsplatsen.
Välj Hemligheter på navigeringsmenyn och välj sedan Åtgärder.
Välj Ny lagringsplatshemlighet.
Skapa en hemlighet för tjänstens huvudnamns-ID.
- Namn: APP_ID
- Hemlighet: Klistra in det clientId som du kopierade från utdata från kommandot för att skapa tjänstens huvudnamn.
Välj Lägg till hemlighet och välj sedan Ny lagringsplatshemlighet för att lägga till en andra hemlighet.
Skapa en hemlighet för lösenordet för tjänstens huvudnamn.
- Namn: SECRET
- Hemlighet: Klistra in den clientSecret som du kopierade från utdata från kommandot för att skapa tjänstens huvudnamn.
Välj Lägg till hemlighet och välj sedan Ny lagringsplatshemlighet för att lägga till den slutliga hemligheten.
Skapa en hemlighet för din Azure-klientorganisation.
- Namn: TENANT
- Hemlighet: Klistra in det tenantId som du kopierade från utdata från kommandot för att skapa tjänstens huvudnamn.
Välj Add secret (Lägg till hemlighet).

2 – Skapa ett arbetsflöde

Ett GitHub Actions-arbetsflöde definierar de uppgifter som ska köras när det utlöses av en händelse. Ett arbetsflöde innehåller ett eller flera jobb som kan köras parallellt eller sekventiellt. Mer information finns i Förstå GitHub Actions.

I den här självstudien skapar vi ett arbetsflöde som innehåller jobb för var och en av följande uppgifter:

Etablera en IoT Hub-instans och en DPS-instans.
Länka IoT Hub- och DPS-instanserna till varandra.
Skapa en enskild registrering på DPS-instansen och registrera en enhet till IoT-hubben med hjälp av symmetrisk nyckelautentisering via DPS-registreringen.
Simulera enheten i fem minuter och övervaka IoT Hub-händelserna.

Arbetsflöden är YAML-filer som finns i katalogen för .github/workflows/ en lagringsplats.

Gå till fliken Åtgärder på GitHub-lagringsplatsen.
I fönstret Åtgärder väljer du Nytt arbetsflöde.
På sidan Välj ett arbetsflöde kan du välja fördefinierade mallar att använda. Vi ska skapa ett eget arbetsflöde för den här självstudien, så välj Konfigurera ett arbetsflöde själv.
GitHub skapar en ny arbetsflödesfil åt dig. Observera att den finns i .github/workflows/ katalogen. Ge den nya filen ett beskrivande namn, till exempel dps-tutorial.yml.
Lägg till namnparametern för att ge arbetsflödet ett namn.
```
name: DPS Tutorial
```
Lägg till parametern on.workflow_dispatch . Parametern on definierar när ett arbetsflöde ska köras. Parametern workflow_dispatch anger att vi vill utlösa arbetsflödet manuellt. Med den här parametern kan vi definiera inputs att det skulle skickas till arbetsflödet vid varje körning, men vi kommer inte att använda dem för den här självstudien.
```
on: workflow_dispatch
```
Definiera miljövariablerna för de resurser som du skapar i arbetsflödet. Dessa variabler kommer att vara tillgängliga för alla jobb i arbetsflödet. Du kan också definiera miljövariabler för enskilda jobb eller för enskilda steg i jobb.

Ersätt platshållarvärdena med dina egna värden. Kontrollera att du anger samma resursgrupp som tjänstens huvudnamn har åtkomst till.
```
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>
```

Definiera miljövariabler för hemligheterna som du skapade i föregående avsnitt.

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

Lägg till jobbparametern i arbetsflödesfilen.
```
jobs:
```

Definiera det första jobbet för vårt arbetsflöde, som vi ska anropa provision jobbet. Det här jobbet etablerar IoT Hub- och DPS-instanserna:

  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"

Mer information om kommandona som körs i det här jobbet finns i:

Definiera ett jobb för configure DPS- och IoT Hub-instanserna. Observera att det här jobbet använder parametern needs , vilket innebär att configure jobbet inte körs förrän det angivna jobbet har slutfört sin egen körning.
```
  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"   
```
Mer information om kommandona som körs i det här jobbet finns i:
- az iot dps linked-hub create
Definiera ett jobb med namnet register som skapar en enskild registrering och sedan använder den registreringen för att registrera en enhet till 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   
```
Kommentar

Det här jobbet och andra använder parametern --auth-type login i vissa kommandon för att ange att åtgärden ska använda tjänstens huvudnamn från den aktuella Microsoft Entra-sessionen. Alternativet kräver --auth-type key inte konfigurationen av tjänstens huvudnamn, men är mindre säker.

Mer information om kommandona som körs i det här jobbet finns i:
- az iot dps enrollment create
- az iot device registration create

Definiera ett jobb till simulate en IoT-enhet som ansluter till IoT-hubben och skickar exempeltelemetrimeddelanden.

  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"

Mer information om kommandona som körs i det här jobbet finns i:

az iot device simulate

Definiera ett jobb till monitor IoT Hub-slutpunkten för händelser och titta på meddelanden som kommer in från den simulerade enheten. Observera att både simulera- och övervakningsjobben definierar registerjobbet i parametern needs . Den här konfigurationen innebär att när registerjobbet har slutförts körs båda dessa jobb parallellt.
```
  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   
```
Mer information om kommandona som körs i det här jobbet finns i:
- az iot hub monitor-events

Den fullständiga arbetsflödesfilen bör se ut så här, med din information som ersätter platshållarvärdena i miljövariablerna:

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

Spara, checka in och skicka den här nya filen till din GitHub-lagringsplats.

3 – Kör arbetsflödet

Gå till fliken Åtgärder på din GitHub-lagringsplats.
I fönstret Åtgärder väljer du DPS-självstudie, vilket är det namn som vi definierade i arbetsflödesfilen och väljer sedan listrutan Kör arbetsflöde .
Ändra grenen om du har skapat arbetsflödet i en annan gren än main och välj sedan Kör arbetsflöde.
En ny arbetsflödeskörning pågår. Välj namnet för att visa information om körningen.
I arbetsflödessammanfattningen kan du se när varje jobb börjar och slutförs. Välj valfritt jobbnamn för att visa dess information. Det simulerade enhetsjobbet körs i fem minuter och skickar telemetri till IoT Hub. Under den här tiden väljer du det simulerade jobbet för att se meddelanden som skickas från enheten och övervakningsjobbet för att se de meddelanden som tas emot av IoT Hub.
När alla jobb har slutförts bör du se gröna bockmarkeringar av var och en.

Rensa resurser

Om du inte kommer att fortsätta att använda de här resurserna som skapats i den här självstudien tar du bort dem med följande steg.

Använd Azure CLI:

Visa en lista över resurserna i resursgruppen.

az resource list --resource-group <RESOURCE_GROUP_NAME>

Om du vill ta bort enskilda resurser använder du resurs-ID:t.

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

Om du vill ta bort hela resursgruppen och alla resurser i den kör du följande kommando:
```
az group delete --resource-group <RESOURCE_GROUP_NAME>
```

Använda Azure-portalen:

I Azure-portalen går du till resursgruppen där du skapade de nya resurserna.
Du kan antingen ta bort hela resursgruppen eller välja de enskilda resurser som du vill ta bort och sedan välja Ta bort.

Nästa steg

Lär dig hur du etablerar DPS-instanser med andra automatiseringsverktyg.

Konfigurera DPS med Bicep

Dela via