Kurz: Automatizace služby Azure Device Provisioning pomocí GitHub Actions

Ke správě životního cyklu zařízení IoT použijte nástroje pro automatizaci, jako je GitHub Actions. Tento kurz ukazuje pracovní postup GitHub Actions, který připojí zařízení k centru IoT pomocí služby Azure Device Provisioning Service (DPS).

V tomto kurzu se naučíte:

• Uložte přihlašovací údaje pro ověřování jako tajné kódy úložiště.
• Vytvořte pracovní postup pro zřízení prostředků služby IoT Hub a Device Provisioning Service.
• Spusťte pracovní postup a monitorujte simulované zařízení při připojení ke službě IoT Hub.

Požadavky

• Předplatné Azure

  Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.

• Azure CLI

  • Použijte prostředí Bash v Azure Cloud Shellu.

  • Nebo pokud dáváte přednost místnímu spouštění referenčních příkazů rozhraní příkazového řádku, nainstalujte Azure CLI. Pokud používáte Windows nebo macOS, zvažte spuštění Azure CLI v kontejneru Dockeru.

    • Pokud používáte místní instalaci, přihlaste se k Azure CLI pomocí příkazu az login.

    • Spuštěním příkazu az version zjistěte verzi a závislé knihovny, které jsou nainstalované. Pokud chcete upgradovat na nejnovější verzi, spusťte az upgrade.

• Účet GitHubu s úložištěm, které vlastníte, nebo úložištěm, ke kterému máte přístup správce. Další informace najdete v tématu Začínáme s GitHubem.

1. Vytvoření tajných kódů úložiště

Pracovní postup, který definujete v další části, vyžaduje přístup k vašemu předplatnému Azure k vytváření a správě prostředků. Tyto informace nechcete umístit do nechráněného souboru, kde by se daly zjistit, takže místo toho použijeme tajné kódy úložiště k uložení těchto informací, ale přesto je zpřístupníme jako proměnnou prostředí v pracovním postupu. Další informace najdete v tématu Šifrované tajné kódy.

Tajné kódy úložiště můžou spravovat jenom vlastníci úložiště a správci.

Vytvoření instančního objektu služby

Místo poskytnutí přihlašovacích údajů pro osobní přístup vytvoříme instanční objekt a pak tyto přihlašovací údaje přidáme jako tajné kódy úložiště. Pomocí Azure CLI vytvořte nový instanční objekt. Další informace najdete v tématu Vytvoření instančního objektu Azure.

1. Pomocí příkazu az ad sp create-for-rbac vytvořte instanční objekt s přístupem přispěvatele ke konkrétní skupině prostředků. Nahraďte <SUBSCRIPTION_ID> a <RESOURCE_GROUP_NAME> nahraďte vlastními informacemi.

   Tento příkaz vyžaduje role správce přístupu vlastníka nebo uživatele v předplatném.

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

2. Zkopírujte následující položky z výstupu příkazu pro vytvoření instančního objektu, který se použije v další části:

   • ClientId.
   • ClientSecret. Toto je vygenerované heslo pro instanční objekt, ke kterému nebudete mít přístup znovu.
   • ID tenanta.

3. Pomocí příkazu az role assignment create přiřaďte instančnímu objektu dvě další role přístupu: Přispěvatel dat služby Device Provisioning a Přispěvatel dat služby IoT Hub. Nahraďte <SP_CLIENT_ID> hodnotou clientId, kterou jste zkopírovali z výstupu předchozího příkazu.

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

Uložení přihlašovacích údajů instančního objektu jako tajných kódů

1. Na GitHub.com přejděte do Nastavení úložiště.

2. V navigační nabídce vyberte Tajné kódy a pak vyberte Akce.

3. Vyberte Nový tajný klíč úložiště.

4. Vytvořte tajný kód pro ID instančního objektu.

   • Název: APP_ID
   • Tajný kód: Vložte id klienta , které jste zkopírovali z výstupu příkazu pro vytvoření instančního objektu.

5. Vyberte Přidat tajný klíč a pak vyberte Nový tajný klíč úložiště a přidejte druhý tajný klíč.

6. Vytvořte tajný kód pro heslo instančního objektu.

   • Název: SECRET
   • Tajný kód: Vložte clientSecret , který jste zkopírovali z výstupu příkazu pro vytvoření instančního objektu.

7. Vyberte Přidat tajný klíč a pak vyberte Nový tajný klíč úložiště a přidejte konečný tajný klíč.

8. Vytvořte tajný kód pro vašeho tenanta Azure.

   • Název: TENANT
   • Tajný kód: Vložte ID tenanta, které jste zkopírovali z výstupu příkazu pro vytvoření instančního objektu.

9. Vyberte Add secret (Přidat tajný kód).

2. Vytvoření pracovního postupu

Pracovní postup GitHub Actions definuje úlohy, které se spustí po aktivaci událostí. Pracovní postup obsahuje jednu nebo více úloh , které se můžou spouštět paralelně nebo postupně. Další informace najdete v tématu Principy GitHub Actions.

V tomto kurzu vytvoříme jeden pracovní postup, který obsahuje úlohy pro každou z následujících úloh:

• Zřízení instance služby IoT Hub a instance DPS
• Propojte mezi sebou instance IoT Hubu a DPS.
• Vytvořte individuální registraci v instanci DPS a zaregistrujte zařízení do centra IoT pomocí ověřování symetrického klíče prostřednictvím registrace DPS.
• Simulujte zařízení po dobu pěti minut a monitorujte události centra IoT.

Pracovní postupy jsou soubory YAML umístěné v .github/workflows/ adresáři úložiště.

1. V úložišti GitHub přejděte na kartu Akce .

2. V podokně Akce vyberte Nový pracovní postup.

3. Na stránce Zvolit pracovní postup můžete zvolit předem připravené šablony, které chcete použít. Pro účely tohoto kurzu vytvoříme vlastní pracovní postup, takže vyberte Nastavit pracovní postup sami.

4. GitHub pro vás vytvoří nový soubor pracovního postupu. Všimněte si, že je v adresáři .github/workflows/ . Dejte novému souboru smysluplný název, například dps-tutorial.yml.

5. Přidejte parametr name, který vašemu pracovnímu postupu pojmenuje.

   name: DPS Tutorial
   

6. Přidejte parametr on.workflow_dispatch. Parametr on definuje, kdy se pracovní postup spustí. Parametr workflow_dispatch označuje, že chceme pracovní postup aktivovat ručně. Pomocí tohoto parametru bychom mohli definovat inputs , že se při každém spuštění předá pracovnímu postupu, ale pro účely tohoto kurzu je nebudeme používat.

   on: workflow_dispatch
   

7. Definujte proměnné prostředí pro prostředky, které vytváříte v pracovním postupu. Tyto proměnné budou k dispozici pro všechny úlohy v pracovním postupu. Můžete také definovat proměnné prostředí pro jednotlivé úlohy nebo pro jednotlivé kroky v rámci úloh.

   Zástupné hodnoty nahraďte vlastními hodnotami. Ujistěte se, že jste zadali stejnou skupinu prostředků, ke které má instanční objekt přístup.

   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. Definujte proměnné prostředí pro tajné kódy, které jste vytvořili v předchozí části.

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

9. Přidejte parametr úlohy do souboru pracovního postupu.

   jobs:
   

10. Definujte první úlohu pro náš pracovní postup, který budeme volat provision . Tato úloha zřizuje instance IoT Hubu a 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"
    

    Další informace o příkazech spuštěných v této úloze najdete tady:

    • az iot hub create
    • az iot dps create

11. Definujte úlohu pro configure instance DPS a IoT Hubu. Všimněte si, že tato úloha používá parametr needs , což znamená, že configure úloha se nespustí, dokud uvedená úloha nedokončí vlastní spuštění úspěšně.

      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"   
    

    Další informace o příkazech spuštěných v této úloze najdete tady:

    • az iot dps linked-hub create

12. Definujte úlohu, register která vytvoří jednotlivou registraci a pak ji použije k registraci zařízení do IoT Hubu.

      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   
    

    Poznámka:

    Tato úloha a další používají parametr --auth-type login v některých příkazech k označení, že operace by měla používat instanční objekt z aktuální relace Microsoft Entra. Alternativní možnost --auth-type key nevyžaduje konfiguraci instančního objektu, ale je méně zabezpečená.

    Další informace o příkazech spuštěných v této úloze najdete tady:

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

13. Definujte úlohu do simulate zařízení IoT, které se připojí k centru IoT a odešle ukázkové zprávy telemetrie.

      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"
    

    Další informace o příkazech spuštěných v této úloze najdete tady:

    • az iot device simulate

14. Definujte úlohu do monitor koncového bodu centra IoT pro události a sledujte zprávy přicházející ze simulovaného zařízení. Všimněte si, že úlohy simulování a monitorování definují úlohu registru v parametru needs . Tato konfigurace znamená, že po úspěšném dokončení úlohy registrace se obě tyto úlohy spustí paralelně.

      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   
    

    Další informace o příkazech spuštěných v této úloze najdete tady:

    • az iot hub monitor-events

15. Úplný soubor pracovního postupu by měl vypadat jako v tomto příkladu s informacemi, které nahradí zástupné hodnoty v proměnných prostředí:

    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. Uložte, potvrďte a nasdílejte tento nový soubor do úložiště GitHub.

3. Spuštění pracovního postupu

1. Přejděte na kartu Akce úložiště GitHub.

2. V podokně Akce vyberte kurz DPS, což je název, který jsme definovali v souboru pracovního postupu, a pak vyberte rozevírací seznam Spustit pracovní postup.

   

3. Pokud jste pracovní postup vytvořili v jiné větvi než hlavní, změňte větev a pak vyberte Spustit pracovní postup.

4. Probíhá nové spuštění pracovního postupu. Výběrem názvu zobrazíte podrobnosti o spuštění.

5. V souhrnu pracovního postupu můžete sledovat, jak jednotlivé úlohy začínají a dokončí. Výběrem libovolného názvu úlohy zobrazíte jeho podrobnosti. Úloha simulovaného zařízení běží pět minut a odesílá telemetrii do IoT Hubu. Během této doby vyberte simulované úlohy, která sleduje zprávy odesílané ze zařízení, a úlohu monitorování , která sleduje příjem těchto zpráv službou IoT Hub.

6. Po úspěšném dokončení všech úloh by se měly u každé z nich zobrazit zelené značky zaškrtnutí.

   

Vyčištění prostředků

Pokud nebudete tyto prostředky vytvořené v tomto kurzu dál používat, odstraňte je pomocí následujícího postupu.

Použijte Azure CLI:

1. Uveďte prostředky ve vaší skupině prostředků.

   az resource list --resource-group <RESOURCE_GROUP_NAME>
   

2. Pokud chcete odstranit jednotlivé prostředky, použijte ID prostředku.

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

3. Pokud chcete odstranit celou skupinu prostředků a všechny prostředky v ní, spusťte následující příkaz:

   az group delete --resource-group <RESOURCE_GROUP_NAME>
   

Použití portálu Azure Portal:

1. Na webu Azure Portal přejděte do skupiny prostředků, ve které jste vytvořili nové prostředky.
2. Můžete buď odstranit celou skupinu prostředků, nebo vybrat jednotlivé prostředky, které chcete odebrat, a pak vybrat Odstranit.

Další kroky

Naučte se zřizovat instance DPS pomocí dalších nástrojů pro automatizaci.

Nastavení DPS pomocí Bicep