Oktatóanyag: Az Azure Device Provisioning Service automatizálása a GitHub Actions használatával

Cikk
10/18/2023

Az IoT-eszközök életciklusának kezeléséhez használjon olyan automatizálási eszközöket, mint a GitHub Actions. Ez az oktatóanyag egy GitHub Actions-munkafolyamatot mutat be, amely egy eszközt csatlakoztat egy IoT Hubhoz az Azure Device Provisioning Service (DPS) használatával.

Ebben az oktatóanyagban az alábbiakkal fog megismerkedni:

Mentse a hitelesítési hitelesítő adatokat adattári titkos kulcsként.
Hozzon létre egy munkafolyamatot az IoT Hub és a Device Provisioning Service-erőforrások kiépítéséhez.
Futtassa a munkafolyamatot, és monitorozza a szimulált eszközt, miközben csatlakozik az IoT Hubhoz.

Előfeltételek

Azure-előfizetés

Ha még nincs Azure-előfizetése, kezdés előtt hozzon létre egy ingyenes fiókot.
Azure CLI
- Használja a Bash-környezetet az Azure Cloud Shellben.
- Vagy ha helyileg szeretné futtatni a PARANCSSOR-referenciaparancsokat, telepítse az Azure CLI-t. Ha Windows vagy macOS rendszeren fut, fontolja meg az Azure CLI docker-tárolóban való futtatását.
  - Ha helyi telepítést használ, jelentkezzen be az Azure CLI-be az az login parancs futtatásával.
  - Futtassa az az version parancsot a telepített verzió és a függő kódtárak megkereséséhez. A legújabb verzióra az az upgrade paranccsal frissíthet.
Egy GitHub-fiók, amely rendelkezik egy ön által birtokolt adattárral, vagy egy olyan adattárral, amelyhez rendszergazdai hozzáféréssel rendelkezik. További információt a GitHub használatának első lépései című témakörben talál.

1 – Adattár titkos kulcsok létrehozása

A következő szakaszban definiálni kívánt munkafolyamathoz hozzá kell férnie az Azure-előfizetéséhez az erőforrások létrehozásához és kezeléséhez. Nem szeretné ezeket az információkat olyan védett fájlba helyezni, amelyben felderíthető, ezért ehelyett adattári titkos kódokkal tároljuk ezeket az információkat, de környezeti változóként továbbra is elérhetővé tesszük őket a munkafolyamatban. További információ: Titkosított titkos kódok.

Csak az adattár tulajdonosai és rendszergazdái kezelhetik az adattár titkos kulcsait.

Egyszerű szolgáltatás létrehozása

A személyes hozzáférési hitelesítő adatok megadása helyett létrehozunk egy szolgáltatásnevet, majd ezeket a hitelesítő adatokat adattári titkos kulcsokként adjuk hozzá. Az Azure CLI használatával hozzon létre egy új szolgáltatásnevet. További információ: Azure-szolgáltatásnév létrehozása.

Az az ad sp create-for-rbac paranccsal létrehozhat egy szolgáltatásnevet, amely közreműködői hozzáféréssel rendelkezik egy adott erőforráscsoporthoz. Cserélje le és <RESOURCE_GROUP_NAME> cserélje le <SUBSCRIPTION_ID> a saját adatait.

Ehhez a parancshoz tulajdonosi vagy felhasználói hozzáférés-rendszergazdai szerepkörökre van szükség az előfizetésben.
```
az ad sp create-for-rbac --name github-actions-sp --role contributor --scopes /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>
```
Másolja ki a következő elemeket a szolgáltatásnév létrehozási parancsának kimenetéből, hogy a következő szakaszban használhassa:
- Az ügyfélazonosító.
- A clientSecret. Ez egy generált jelszó a szolgáltatásnévhez, amelyet nem fog tudni újból elérni.
- A bérlőazonosító.
Az az role assignment create paranccsal rendeljen hozzá még két hozzáférési szerepkört a szolgáltatásnévhez: Device Provisioning Service Data Contributor és IoT Hub Data Contributor. Cserélje le <SP_CLIENT_ID> azt a clientId értéket, amelyet az előző parancs kimenetéből másolt.
```
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>"
```

Szolgáltatásnév hitelesítő adatainak mentése titkos kulcsként

A GitHub.com lépjen az adattár Gépház.
Válassza a Navigációs menü Titkos kulcsok elemét, majd a Műveletek lehetőséget.
Válassza az Új tárház titkos kódját.
Hozzon létre egy titkos kulcsot a szolgáltatásnév azonosítójához.
- Név: APP_ID
- Titkos kód: Illessze be a szolgáltatásnév-létrehozási parancs kimenetéből kimásolt ügyfélazonosítót .
Válassza a Titkos kód hozzáadása lehetőséget, majd az Új adattárkulcs lehetőséget egy második titkos kód hozzáadásához.
Hozzon létre egy titkos kulcsot a szolgáltatásnév jelszavához.
- Név: SECRET
- Titkos kód: Illessze be a szolgáltatásnév-létrehozási parancs kimenetéből kimásolt clientSecret elemet.
Válassza a Titkos kód hozzáadása lehetőséget, majd az Új tárházi titkos kulcs lehetőséget a végleges titkos kód hozzáadásához.
Hozzon létre egy titkos kulcsot az Azure-bérlőhöz.
- Név: TENANT
- Titkos kód: Illessze be a szolgáltatásnév-létrehozási parancs kimenetéből kimásolt bérlőazonosítót .
Válassza az Add secret (Titkos kód hozzáadása) lehetőséget.

2 – Munkafolyamat létrehozása

Egy GitHub Actions-munkafolyamat határozza meg azokat a feladatokat, amelyeket egy esemény aktivál. A munkafolyamatok egy vagy több olyan feladatot tartalmaznak, amelyek párhuzamosan vagy egymás után futtathatók. További információ: A GitHub Actions ismertetése.

Ebben az oktatóanyagban egy munkafolyamatot hozunk létre, amely az alábbi feladatokhoz tartalmaz feladatokat:

IoT Hub-példány és DPS-példány kiépítése.
Csatolja egymáshoz az IoT Hub és a DPS-példányokat.
Hozzon létre egy egyéni regisztrációt a DPS-példányon, és regisztráljon egy eszközt az IoT Hubra szimmetrikus kulcsos hitelesítéssel a DPS-regisztráción keresztül.
Szimulálja az eszközt öt percig, és figyelje az IoT Hub eseményeit.

A munkafolyamatok olyan YAML-fájlok, amelyek egy .github/workflows/ adattár könyvtárában találhatók.

A GitHub-adattárban lépjen a Műveletek lapra.
A Műveletek panelen válassza az Új munkafolyamat lehetőséget.
A Munkafolyamat kiválasztása lapon kiválaszthatja az előre összeállított sablonokat. Saját munkafolyamatot hozunk létre ehhez az oktatóanyaghoz, ezért válassza a Munkafolyamat beállítása lehetőséget.
A GitHub létrehoz egy új munkafolyamat-fájlt. Figyelje meg, hogy a könyvtárban .github/workflows/ van. Adjon egy értelmes nevet az új fájlnak, például dps-tutorial.yml.
Adja hozzá a névparamétert , hogy nevet adjon a munkafolyamatnak.
```
name: DPS Tutorial
```
Adja hozzá a on.workflow_dispatch paramétert. A on paraméter határozza meg, hogy mikor fut egy munkafolyamat. A workflow_dispatch paraméter azt jelzi, hogy manuálisan szeretnénk aktiválni a munkafolyamatot. Ezzel a paraméterrel meghatározható inputs , hogy az egyes futtatáskor a munkafolyamatnak átadják-e, de ehhez az oktatóanyaghoz nem fogjuk használni őket.
```
on: workflow_dispatch
```
Határozza meg a munkafolyamatban létrehozott erőforrások környezeti változóit . Ezek a változók a munkafolyamat összes feladatához elérhetők lesznek. Környezeti változókat is meghatározhat az egyes feladatokhoz vagy a feladatokon belüli egyes lépésekhez.

Cserélje le a helyőrző értékeket a saját értékeire. Győződjön meg arról, hogy ugyanazt az erőforráscsoportot adja meg, amelyhez a szolgáltatásnév hozzáfér.
```
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>
```

Az előző szakaszban létrehozott titkos kulcsok környezeti változóinak definiálása.

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

Adja hozzá a feladatparamétert a munkafolyamat-fájlhoz.
```
jobs:
```

Adja meg a munkafolyamat első feladatát, amelyet meghívunk a provision feladatnak. Ez a feladat az IoT Hub- és DPS-példányokat helyezi üzembe:

  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"

A feladatban futtatott parancsokkal kapcsolatos további információkért lásd:

Feladat definiálása configure a DPS- és IoT Hub-példányokhoz. Figyelje meg, hogy ez a feladat a szükséges paramétert használja, ami azt jelenti, hogy a feladat csak akkor fut, ha a configure felsorolt feladat sikeresen befejezi a saját futtatását.
```
  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"   
```
A feladatban futtatott parancsokkal kapcsolatos további információkért lásd:
- az iot dps linked-hub create
Definiáljon egy olyan feladatot, register amely létrehoz egy egyéni regisztrációt, majd ezzel a regisztrációval regisztrál egy eszközt az IoT Hubon.
```
  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   
```
Feljegyzés

Ez a feladat és mások egyes parancsokban a paraméter --auth-type login használatával jelzik, hogy a műveletnek az aktuális Microsoft Entra-munkamenet szolgáltatásnevét kell használnia. A másik lehetőség, --auth-type key hogy nem igényel egyszerű szolgáltatáskonfigurációt, de kevésbé biztonságos.

A feladatban futtatott parancsokkal kapcsolatos további információkért lásd:
- az iot dps enrollment create
- az iot device registration create

Adjon meg egy feladatot egy olyan IoT-eszközhöz simulate , amely csatlakozik az IoT Hubhoz, és minta telemetriai üzeneteket küld.

  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"

A feladatban futtatott parancsokkal kapcsolatos további információkért lásd:

az iot device simulate

Feladat definiálása monitor az IoT Hub-végponton eseményekhez, és a szimulált eszközről érkező üzenetek megtekintése. Figyelje meg, hogy a szimulált és monitorozási feladatok egyaránt meghatározzák a regisztrációs feladatot a paraméterükbenneeds. Ez a konfiguráció azt jelenti, hogy ha a regisztrációs feladat sikeresen befejeződött, mindkét feladat párhuzamosan fog futni.
```
  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   
```
A feladatban futtatott parancsokkal kapcsolatos további információkért lásd:
- az iot hub monitor-events

A teljes munkafolyamat-fájlnak az alábbi példához hasonlóan kell kinéznie, és az adatok a környezeti változók helyőrző értékeit cserélik le:

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

Mentse, véglegesítse és küldje le ezt az új fájlt a GitHub-adattárba.

3 – A munkafolyamat futtatása

Lépjen a GitHub-adattár Műveletek lapjára.
A Műveletek panelen válassza a DPS-oktatóanyagot, amely a munkafolyamat-fájlban definiált név, majd válassza a Munkafolyamat futtatása legördülő menüt.
Módosítsa az ágat, ha a munkafolyamatot nem fő ágban hozta létre, majd válassza a Munkafolyamat futtatása lehetőséget.
Folyamatban van egy új munkafolyamat-futtatás. Válassza ki a nevet a futtatás részleteinek megtekintéséhez.
A munkafolyamat összegzésében megtekintheti, hogy az egyes feladatok elkezdődnek és befejeződnek. Válassza ki a feladat nevét a részleteinek megtekintéséhez. A szimulált eszközfeladat öt percig fut, és telemetriát küld az IoT Hubnak. Ez idő alatt válassza ki a szimulált feladatot az eszközről küldött üzenetek megtekintéséhez, a monitorozási feladat pedig az IoT Hub által fogadott üzenetek megtekintéséhez.
Ha az összes feladat sikeresen befejeződött, mindegyiknél zöld pipáknak kell megjelenniük.

Az erőforrások eltávolítása

Ha nem fogja továbbra is használni az oktatóanyagban létrehozott erőforrásokat, törölje őket az alábbi lépésekkel.

Az Azure CLI használata:

Listázhatja az erőforráscsoport erőforrásait.

az resource list --resource-group <RESOURCE_GROUP_NAME>

Az egyes erőforrások törléséhez használja az erőforrás-azonosítót.

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

Ha törölni szeretné a teljes erőforráscsoportot és a benne lévő összes erőforrást, futtassa a következő parancsot:
```
az group delete --resource-group <RESOURCE_GROUP_NAME>
```

Az Azure Portalon:

Az Azure Portalon lépjen arra az erőforráscsoportra, ahol létrehozta az új erőforrásokat.
Törölheti a teljes erőforráscsoportot, vagy kiválaszthatja az eltávolítani kívánt erőforrásokat, majd válassza a Törlés lehetőséget.

Következő lépések

Megtudhatja, hogyan építhet ki DPS-példányokat más automatizálási eszközökkel.

A DPS beállítása a Bicep-lel

Megosztás a következőn keresztül: