Zelfstudie: Azure Device Provisioning Service automatiseren met GitHub Actions

Gebruik automatiseringshulpprogramma's zoals GitHub Actions om de levenscyclus van uw IoT-apparaat te beheren. In deze zelfstudie ziet u een GitHub Actions-werkstroom die een apparaat verbindt met een IoT-hub met behulp van Azure Device Provisioning Service (DPS).

In deze zelfstudie leert u het volgende:

• Sla verificatiereferenties op als opslagplaatsgeheimen.
• Maak een werkstroom voor het inrichten van IoT Hub- en Device Provisioning Service-resources.
• Voer de werkstroom uit en bewaak een gesimuleerd apparaat terwijl het verbinding maakt met IoT Hub.

Vereisten

• Een Azure-abonnement

  Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

• De Azure CLI

  • Gebruik de Bash-omgeving in Azure Cloud Shell.

  • Als u liever CLI-referentieopdrachten lokaal uitvoert, installeert u de Azure CLI. Als u werkt met Windows of macOS, kunt u Overwegen Om Azure CLI uit te voeren in een Docker-container.

    • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login.

    • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

• Een GitHub-account met een opslagplaats die u bezit of een opslagplaats waar u beheerderstoegang hebt. Zie Aan de slag met GitHub voor meer informatie.

1 - Opslagplaatsgeheimen maken

De werkstroom die u in de volgende sectie definieert, vereist toegang tot uw Azure-abonnement om resources te maken en te beheren. U wilt die informatie niet in een niet-beveiligd bestand plaatsen waar deze kan worden gedetecteerd. In plaats daarvan gebruiken we opslagplaatsgeheimen om deze informatie op te slaan, maar toch toegankelijk te maken als een omgevingsvariabele in de werkstroom. Zie Versleutelde geheimen voor meer informatie.

Alleen eigenaren en beheerders van opslagplaatsen kunnen opslagplaatsgeheimen beheren.

Een service-principal maken

In plaats van uw persoonlijke toegangsreferenties op te geven, maken we een service-principal en voegen we deze referenties vervolgens toe als opslagplaatsgeheimen. Gebruik de Azure CLI om een nieuwe service-principal te maken. Zie Een Azure-service-principal maken voor meer informatie.

1. Gebruik de opdracht az ad sp create-for-rbac om een service-principal te maken met inzendertoegang tot een specifieke resourcegroep. Vervang <SUBSCRIPTION_ID> en <RESOURCE_GROUP_NAME> door uw eigen gegevens.

   Voor deze opdracht zijn eigenaars- of gebruikerstoegangsbeheerdersrollen in het abonnement vereist.

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

2. Kopieer de volgende items uit de uitvoer van de opdracht voor het maken van de service-principal die u in de volgende sectie wilt gebruiken:

   • De clientId.
   • De clientSecret. Dit is een gegenereerd wachtwoord voor de service-principal waartoe u geen toegang meer hebt.
   • De tenantId.

3. Gebruik de opdracht az role assignment create om nog twee toegangsrollen toe te wijzen aan de service-principal: Device Provisioning Service Data Contributor en IoT Hub Data Contributor. Vervang door <SP_CLIENT_ID> de clientId-waarde die u hebt gekopieerd uit de uitvoer van de vorige opdracht.

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

Referenties van de service-principal opslaan als geheimen

1. Navigeer in GitHub.com naar de Instellingen voor uw opslagplaats.

2. Selecteer Geheimen in het navigatiemenu en selecteer vervolgens Acties.

3. Selecteer Nieuw opslagplaatsgeheim.

4. Maak een geheim voor uw service-principal-id.

   • Naam: APP_ID
   • Geheim: Plak de clientId die u hebt gekopieerd uit de uitvoer van de opdracht voor het maken van de service-principal.

5. Selecteer Geheim toevoegen en selecteer vervolgens Nieuw opslagplaatsgeheim om een tweede geheim toe te voegen.

6. Maak een geheim voor het wachtwoord van uw service-principal.

   • Naam: SECRET
   • Geheim: plak de clientSecret die u hebt gekopieerd uit de uitvoer van de opdracht voor het maken van de service-principal.

7. Selecteer Geheim toevoegen en selecteer vervolgens Nieuw opslagplaatsgeheim om het uiteindelijke geheim toe te voegen.

8. Maak een geheim voor uw Azure-tenant.

   • Naam: TENANT
   • Geheim: Plak de tenantId die u hebt gekopieerd uit de uitvoer van de opdracht voor het maken van de service-principal.

9. Selecteer Geheim toevoegen.

2 - Een werkstroom maken

Een GitHub Actions-werkstroom definieert de taken die worden uitgevoerd zodra deze worden geactiveerd door een gebeurtenis. Een werkstroom bevat een of meer taken die parallel of opeenvolgend kunnen worden uitgevoerd. Zie GitHub Actions voor meer informatie.

Voor deze zelfstudie maken we één werkstroom met taken voor elk van de volgende taken:

• Een IoT Hub-exemplaar en een DPS-exemplaar inrichten.
• Koppel de IoT Hub- en DPS-exemplaren aan elkaar.
• Maak een afzonderlijke inschrijving op het DPS-exemplaar en registreer een apparaat bij de IoT-hub met behulp van symmetrische sleutelverificatie via de DPS-inschrijving.
• Simuleer het apparaat vijf minuten en bewaak de IoT Hub-gebeurtenissen.

Werkstromen zijn YAML-bestanden die zich in de .github/workflows/ map van een opslagplaats bevinden.

1. Navigeer in uw GitHub-opslagplaats naar het tabblad Acties .

2. Selecteer nieuwe werkstroom in het deelvenster Acties.

3. Op de pagina Een werkstroom kiezen kunt u vooraf gemaakte sjablonen kiezen die u wilt gebruiken. Voor deze zelfstudie gaan we een eigen werkstroom maken, dus selecteer Zelf een werkstroom instellen.

4. GitHub maakt een nieuw werkstroombestand voor u. U ziet dat deze zich in de .github/workflows/ map bevindt. Geef het nieuwe bestand een betekenisvolle naam, zoals dps-tutorial.yml.

5. Voeg de naamparameter toe om uw werkstroom een naam te geven.

   name: DPS Tutorial
   

6. Voeg de parameter on.workflow_dispatch toe. De on parameter definieert wanneer een werkstroom wordt uitgevoerd. De workflow_dispatch parameter geeft aan dat we de werkstroom handmatig willen activeren. Met deze parameter kunnen we definiëren inputs dat deze tijdens elke uitvoering aan de werkstroom wordt doorgegeven, maar we gebruiken deze niet voor deze zelfstudie.

   on: workflow_dispatch
   

7. Definieer de omgevingsvariabelen voor de resources die u in de werkstroom maakt. Deze variabelen zijn beschikbaar voor alle taken in de werkstroom. U kunt ook omgevingsvariabelen definiëren voor afzonderlijke taken of voor afzonderlijke stappen binnen taken.

   Vervang de tijdelijke aanduidingen door uw eigen waarden. Zorg ervoor dat u dezelfde resourcegroep opgeeft waartoe de service-principal toegang heeft.

   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. Definieer omgevingsvariabelen voor de geheimen die u in de vorige sectie hebt gemaakt.

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

9. Voeg de taakparameter toe aan het werkstroombestand.

   jobs:
   

10. Definieer de eerste taak voor onze werkstroom, die we de provision taak noemen. Met deze taak worden de IoT Hub- en DPS-exemplaren uitgevoerd:

      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"
    

    Zie voor meer informatie over de opdrachten die in deze taak worden uitgevoerd:

    • az iot hub create
    • az iot dps create

11. Definieer een taak voor configure de DPS- en IoT Hub-exemplaren. U ziet dat deze taak gebruikmaakt van de parameter Needs , wat betekent dat de taak pas wordt uitgevoerd als de configure vermelde taak zijn eigen uitvoering heeft voltooid.

      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"   
    

    Zie voor meer informatie over de opdrachten die in deze taak worden uitgevoerd:

    • az iot dps linked-hub create

12. Definieer een taak met de naam register die een afzonderlijke inschrijving maakt en gebruik die inschrijving vervolgens om een apparaat te registreren bij 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   
    

    Notitie

    Deze taak en anderen gebruiken de parameter --auth-type login in sommige opdrachten om aan te geven dat de bewerking de service-principal van de huidige Microsoft Entra-sessie moet gebruiken. Het alternatief vereist --auth-type key niet de configuratie van de service-principal, maar is minder veilig.

    Zie voor meer informatie over de opdrachten die in deze taak worden uitgevoerd:

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

13. Definieer een taak voor simulate een IoT-apparaat dat verbinding maakt met de IoT-hub en voorbeeldtelemetrieberichten verzendt.

      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"
    

    Zie voor meer informatie over de opdrachten die in deze taak worden uitgevoerd:

    • az iot device simulate

14. Definieer een taak voor monitor het IoT Hub-eindpunt voor gebeurtenissen en bekijk berichten die afkomstig zijn van het gesimuleerde apparaat. U ziet dat de gesimuleerde en bewaakte taken beide de registertaak definiëren in hun needs parameter. Deze configuratie betekent dat wanneer de registertaak is voltooid, beide taken parallel worden uitgevoerd.

      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   
    

    Zie voor meer informatie over de opdrachten die in deze taak worden uitgevoerd:

    • az iot hub monitor-events

15. Het volledige werkstroombestand moet er als volgt uitzien, waarbij uw gegevens de tijdelijke aanduidingen in de omgevingsvariabelen vervangen:

    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. Sla dit nieuwe bestand op, doorvoer en push dit naar uw GitHub-opslagplaats.

3 - De werkstroom uitvoeren

1. Navigeer naar het tabblad Acties van uw GitHub-opslagplaats.

2. Selecteer in het deelvenster Acties DPS-zelfstudie. Dit is de naam die we hebben gedefinieerd in het werkstroombestand en selecteer vervolgens de vervolgkeuzelijst Werkstroom uitvoeren.

   

3. Wijzig de vertakking als u uw werkstroom hebt gemaakt in een andere vertakking dan de hoofdbranch en selecteer vervolgens Werkstroom uitvoeren.

4. Er wordt een nieuwe werkstroomuitvoering uitgevoerd. Selecteer de naam om de details van de uitvoering weer te geven.

5. In het werkstroomoverzicht kunt u zien hoe elke taak begint en wordt voltooid. Selecteer een taaknaam om de details ervan weer te geven. De gesimuleerde apparaattaak wordt vijf minuten uitgevoerd en verzendt telemetrie naar IoT Hub. Selecteer gedurende deze tijd de simuleertaak om berichten te bekijken die vanaf het apparaat worden verzonden en de monitortaak om te zien hoe deze berichten worden ontvangen door IoT Hub.

6. Wanneer alle taken zijn voltooid, ziet u voor elke taak groene vinkjes.

   

Resources opschonen

Als u deze resources die in deze zelfstudie zijn gemaakt niet meer gaat gebruiken, verwijdert u deze met de volgende stappen.

De Azure CLI gebruiken:

1. Geef de resources in uw resourcegroep weer.

   az resource list --resource-group <RESOURCE_GROUP_NAME>
   

2. Als u afzonderlijke resources wilt verwijderen, gebruikt u de resource-id.

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

3. Als u de hele resourcegroep en alle resources erin wilt verwijderen, voert u de volgende opdracht uit:

   az group delete --resource-group <RESOURCE_GROUP_NAME>
   

De Azure Portal gebruiken:

1. Navigeer in Azure Portal naar de resourcegroep waar u de nieuwe resources hebt gemaakt.
2. U kunt de hele resourcegroep verwijderen of de afzonderlijke resources selecteren die u wilt verwijderen en vervolgens Verwijderen selecteren.

Volgende stappen

Meer informatie over het inrichten van DPS-exemplaren met andere automatiseringshulpprogramma's.

DPS instellen met Bicep