Sdílet prostřednictvím

Integrace IoT Central se službou Azure Pipelines pro kontinuální integraci a průběžné doručování

  • Článek

Kontinuální integrace a průběžné doručování (CI/CD) se týká procesu vývoje a doručování softwaru v krátkých častých cyklech pomocí kanálů automatizace. V tomto článku se dozvíte, jak automatizovat sestavení, testování a nasazení konfigurace aplikace IoT Central. Tato automatizace umožňuje vývojových týmům poskytovat spolehlivější vydané verze častěji.

Kontinuální integrace začíná potvrzením kódu do větve v úložišti zdrojového kódu. Každé potvrzení se sloučí s potvrzeními od jiných vývojářů, aby se zajistilo, že nebudou zavedeny žádné konflikty. Změny jsou dále ověřeny vytvořením sestavení a spuštěním automatizovaných testů v tomto sestavení. Výsledkem tohoto procesu je nakonec artefakt nebo sada nasazení, která se nasadí do cílového prostředí. V tomto případě je cílem aplikace Azure IoT Central.

Stejně jako ioT Central je součástí vašeho většího řešení IoT, je IoT Central součástí vašeho kanálu CI/CD. Kanál CI/CD by měl nasadit celé řešení IoT a všechny konfigurace do každého prostředí od vývoje až po produkční prostředí:

Diagram znázorňující fáze typického kanálu CI/CD

IoT Central je aplikační platforma jako služba , která má jiné požadavky na nasazení než komponenty platformy jako služby . Pro IoT Central nasadíte konfigurace a šablony zařízení. Tyto konfigurace a šablony zařízení se spravují a integrují do kanálu verze pomocí rozhraní API.

I když je možné automatizovat vytváření aplikací IoT Central, měli byste před vývojem kanálu CI/CD vytvořit aplikaci v každém prostředí.

Pomocí rozhraní Azure IoT Central REST API můžete integrovat konfigurace aplikací IoT Central do kanálu verze.

Tato příručka vás provede vytvořením nového kanálu, který aktualizuje aplikaci IoT Central na základě konfiguračních souborů spravovaných v GitHubu. Tato příručka obsahuje konkrétní pokyny pro integraci se službou Azure Pipelines, ale je možné ji přizpůsobit tak, aby zahrnovala IoT Central do libovolného kanálu verze vytvořeného pomocí nástrojů, jako jsou Tekton, Jenkins, GitLab nebo GitHub Actions.

V této příručce vytvoříte kanál, který použije pouze konfiguraci IoT Central na jednu instanci aplikace IoT Central. Kroky byste měli integrovat do většího kanálu, který nasazuje celé řešení a podporuje ho od vývoje až po kontrolu kvality až po předprodukci do produkčního prostředí a provádět veškeré nezbytné testování.

Skripty aktuálně nepřenášejí následující nastavení mezi instancemi IoT Central: řídicí panely, zobrazení, vlastní nastavení v šablonách zařízení, cenový plán, přizpůsobení uživatelského rozhraní, image aplikace, pravidla, naplánované úlohy, uložené úlohy a skupiny registrací.

Skripty aktuálně neodeberou nastavení z cílové aplikace IoT Central, které nejsou v konfiguračním souboru.

Požadavky

K dokončení kroků v této příručce potřebujete následující požadavky:

Stažení ukázkového kódu

Začněte tím, že forkujete úložiště IoT Central CI/CD GitHubu a pak naklonujete fork do místního počítače:

  1. Pokud chcete vytvořit fork úložiště GitHub, otevřete úložiště IoT Central CI/CD GitHub a vyberte Fork.

  2. Naklonujte fork úložiště do místního počítače otevřením okna konzoly nebo bashe a spuštěním následujícího příkazu.

    git clone https://github.com/{your GitHub username}/iot-central-CICD-sample

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

Azure Pipelines se sice může integrovat přímo s trezorem klíčů, ale kanál potřebuje instanční objekt pro některé dynamické interakce trezoru klíčů, jako je načtení tajných kódů pro cíle exportu dat.

Vytvoření instančního objektu vymezeného pro vaše předplatné:

  1. Spuštěním následujícího příkazu vytvořte nový instanční objekt:

    az ad sp create-for-rbac -n DevOpsAccess --scopes /subscriptions/{your Azure subscription Id} --role Contributor

  2. Poznamenejte si heslo, appId a tenanta , protože tyto hodnoty budete potřebovat později.

  3. Přidejte heslo instančního objektu jako tajný klíč volaný SP-Password do vašeho produkčního trezoru klíčů:

    az keyvault secret set --name SP-Password --vault-name {your production key vault name} --value {your service principal password}

  4. Udělte instančnímu objektu oprávnění ke čtení tajných kódů z trezoru klíčů:

    az keyvault set-policy --name {your production key vault name} --secret-permissions get list --spn {the appId of the service principal}

Generování tokenů rozhraní API IoT Central

V této příručce váš kanál používá tokeny rozhraní API k interakci s aplikacemi IoT Central. Instanční objekt je také možné použít.

Poznámka:

Platnost tokenů rozhraní API IoT Central vyprší po jednom roce.

Pro aplikace IoT Central pro vývoj i produkční prostředí proveďte následující kroky.

  1. V aplikaci IoT Central vyberte Oprávnění a pak tokeny rozhraní API.

  2. Vyberte Nový.

  3. Dejte tokenu název, zadejte v aplikaci organizaci nejvyšší úrovně a nastavte roli na Správce aplikací.

  4. Poznamenejte si token rozhraní API z vaší vývojové aplikace IoT Central. Použijete ho později při spuštění skriptu IoTC-Config.ps1 .

  5. Uložte vygenerovaný token z produkční aplikace IoT Central jako tajný kód, který se volá API-Token do trezoru produkčních klíčů:

    az keyvault secret set --name API-Token --vault-name {your production key vault name} --value '{your production app API token}'

Vygenerování konfiguračního souboru

Tento postup vytvoří konfigurační soubor JSON pro vaše vývojové prostředí na základě existující aplikace IoT Central. Také si stáhnete všechny existující šablony zařízení z aplikace.

  1. V místní kopii úložiště CI/CD IoT Central spusťte následující skript PowerShellu 7:

    cd .\iot-central-CICD-sample\PowerShell\
.\IoTC-Config.ps1

  2. Podle pokynů se přihlaste ke svému účtu Azure.

  3. Po přihlášení skript zobrazí nabídku možností konfigurace IoTC. Skript může vygenerovat konfigurační soubor z existující aplikace IoT Central a použít konfiguraci na jinou aplikaci IoT Central.

  4. Vyberte možnost 1 a vygenerujte konfigurační soubor.

  5. Zadejte potřebné parametry a stiskněte Enter:

    • Token rozhraní API, který jste vygenerovali pro vývojovou aplikaci IoT Central.
    • Subdoména vaší vývojové aplikace IoT Central.
    • Zadejte .. \Config\Dev jako složka pro uložení konfiguračního souboru a šablon zařízení.
    • Název vašeho vývojového trezoru klíčů.

  6. Skript vytvoří složku s názvem IoTC Configuration ve složce Config\Dev v místní kopii úložiště. Tato složka obsahuje konfigurační soubor a složku s názvem Modely zařízení pro všechny šablony zařízení ve vaší aplikaci.

Úprava konfiguračního souboru

Teď, když máte konfigurační soubor, který představuje nastavení pro instanci vaší vývojové aplikace IoT Central, proveďte potřebné změny před použitím této konfigurace na produkční instanci aplikace IoT Central.

  1. Vytvořte kopii dříve vytvořené složky Dev a pojmenujte ji Production.

  2. Otevřete IoTC-Config.json v produkční složce pomocí textového editoru.

  3. Soubor obsahuje více oddílů. Pokud ale vaše aplikace nepoužívá konkrétní nastavení, tento oddíl se ze souboru vynechá:

    {
  "APITokens": {
    "value": [
      {
        "id": "dev-admin",
        "roles": [
          {
            "role": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4"
          }
        ],
        "expiry": "2023-05-31T10:47:08.53Z"
      }
    ]
  },
  "data exports": {
    "value": [
      {
        "id": "5ad278d6-e22b-4749-803d-db1a8a2b8529",
        "displayName": "All telemetry to blob storage",
        "enabled": false,
        "source": "telemetry",
        "destinations": [
          {
            "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63"
          }
        ],
        "status": "notStarted"
      }
    ]
  },
  "device groups": {
    "value": [
      {
        "id": "66f41d29-832d-4a12-9e9d-18932bee3141",
        "displayName": "MXCHIP Getting Started Guide - All devices"
      },
      {
        "id": "494dc749-0963-4ec1-89ff-e1de2228e750",
        "displayName": "RS40 Occupancy Sensor - All devices"
      },
      {
        "id": "dd87877d-9465-410b-947e-64167a7a1c39",
        "displayName": "Cascade 500 - All devices"
      },
      {
        "id": "91ceac5b-f98d-4df0-9ed6-5465854e7d9e",
        "displayName": "Simulated devices"
      }
    ]
  },
  "organizations": {
    "value": []
  },
  "roles": {
    "value": [
      {
        "id": "344138e9-8de4-4497-8c54-5237e96d6aaf",
        "displayName": "Builder"
      },
      {
        "id": "ca310b8d-2f4a-44e0-a36e-957c202cd8d4",
        "displayName": "Administrator"
      },
      {
        "id": "ae2c9854-393b-4f97-8c42-479d70ce626e",
        "displayName": "Operator"
      }
    ]
  },
  "destinations": {
    "value": [
      {
        "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
        "displayName": "Blob destination",
        "type": "blobstorage@v1",
        "authorization": {
          "type": "systemAssignedManagedIdentity",
          "endpointUri": "https://yourstorageaccount.blob.core.windows.net/",
          "containerName": "dataexport"
        },
        "status": "waiting"
      }
    ]
  },
  "file uploads": {
    "connectionString": "FileUpload",
    "container": "fileupload",
    "sasTtl": "PT1H"
  },
  "jobs": {
    "value": []
  }
}

  4. Pokud vaše aplikace používá nahrání souborů, vytvoří skript ve vašem trezoru vývojového klíče tajný kód s hodnotou zobrazenou connectionString ve vlastnosti. Vytvořte tajný klíč se stejným názvem v trezoru produkčních klíčů, který obsahuje připojovací řetězec pro váš účet produkčního úložiště. Příklad:

    az keyvault secret set --name FileUpload --vault-name {your production key vault name} --value '{your production storage account connection string}'

  5. Pokud vaše aplikace používá spravované identity pro cíle exportu dat, nejsou k dispozici žádné tajné kódy, které byste mohli spravovat. Musíte ale povolit spravovanou identitu přiřazenou systémem pro produkční aplikaci IoT Central a udělit jí potřebná oprávnění k zápisu do cíle.

  6. Pokud vaše aplikace používá připojovací řetězec pro cíle exportu dat, přidejte tajné kódy pro cíle do produkčního trezoru klíčů. Konfigurační soubor neobsahuje žádné skutečné tajné kódy pro váš cíl, tajné kódy se ukládají do vašeho trezoru klíčů.

  7. Aktualizujte tajné kódy v konfiguračním souboru názvem tajného kódu ve vašem trezoru klíčů.

    Typ cíle Vlastnost, která se má změnit
    Fronta služby Service Bus připojovací řetězec
    Téma služby Service Bus připojovací řetězec
    Průzkumník dat Azure clientSecret
    Azure Blob Storage připojovací řetězec
    Event Hubs připojovací řetězec
    Webhook Bez ověřování –

    Příklad:

    "destinations": {
  "value": [
    {
      "id": "393adfc9-0ed8-45f4-aa29-25b5c96ecf63",
      "displayName": "Blob destination",
      "type": "blobstorage@v1",
      "authorization": {
        "type": "connectionString",
        "connectionString": "Storage-CS",
        "containerName": "dataexport"
      },
      "status": "waiting"
    }
  ]
}

  8. Pokud chcete nahrát konfigurační složku do úložiště GitHub, spusťte ze složky IoTC-CICD-howto následující příkazy.

     git add Config
 git commit -m "Adding config directories and files"
 git push

Vytvořit kanál

  1. Otevřete organizaci Azure DevOps ve webovém prohlížeči tak, že přejdete na https://dev.azure.com/{your DevOps organization}
  2. Vyberte Nový projekt a vytvořte nový projekt.
  3. Zadejte název projektu a volitelný popis a pak vyberte Vytvořit.
  4. Na stránce Vítejte na stránce projektu vyberte Kanály a pak vytvořte kanál.
  5. Jako umístění kódu vyberte GitHub .
  6. Výběrem možnosti Autorizovat AzurePipelines autorizujete Azure Pipelines pro přístup k vašemu účtu GitHubu.
  7. Na stránce Vybrat úložiště vyberte fork úložiště IoT Central CI/CD GitHubu.
  8. Po zobrazení výzvy k přihlášení k GitHubu a poskytnutí oprávnění pro přístup k úložišti Azure Pipelines vyberte Schválit a nainstalovat.
  9. Na stránce Konfigurace kanálu vyberte Úvodní kanál, abyste mohli začít. Zobrazí se azure-pipelines.yml , které můžete upravit.

Vytvoření skupiny proměnných

Snadný způsob integrace tajných kódů trezoru klíčů do kanálu je prostřednictvím skupin proměnných. Pomocí skupiny proměnných se ujistěte, že jsou pro váš skript nasazení k dispozici správné tajné kódy. Vytvoření skupiny proměnných:

  1. V části Kanály v nabídce na levé straně vyberte Knihovnu.

  2. Vyberte + Proměnná skupina.

  3. Zadejte keyvault jako název skupiny proměnných.

  4. Povolte přepínač pro propojení tajných kódů z trezoru klíčů Azure.

  5. Vyberte své předplatné Azure a autorizujete ho. Pak vyberte název vašeho trezoru produkčních klíčů.

  6. Výběrem možnosti Přidat zahájíte přidávání proměnných do skupiny.

  7. Přidejte následující tajné kódy:

    • Klíč rozhraní API Služby IoT Central pro vaši produkční aplikaci. Tento tajný kód API-Token jste volali při jeho vytvoření.
    • Heslo pro instanční objekt, který jste vytvořili dříve. Tento tajný kód SP-Password jste volali při jeho vytvoření.

  8. Vyberte OK.

  9. Výběrem možnosti Uložit uložte skupinu proměnných.

Konfigurace kanálu

Teď nakonfigurujte kanál pro nabízení změn konfigurace do aplikace IoT Central:

  1. V části Kanály v nabídce vlevo vyberte Kanály.

  2. Nahraďte obsah kanálu YAML následujícím kódem YAML. Konfigurace předpokládá, že váš trezor produkčních klíčů obsahuje:

    • Token rozhraní API pro produkční aplikaci IoT Central v tajném kódu s názvem API-Token.
    • Vaše heslo instančního objektu v tajném kódu s názvem SP-Password.

    Nahraďte hodnoty odpovídajícími -AppName hodnotami pro vaše produkční instance a -KeyVault nahraďte je příslušnými hodnotami.

    Poznamenali -AppId jste si instanční objekt a -TenantId kdy jste vytvořili instanční objekt.

    trigger:
- master
variables:
- group: keyvault
- name: buildConfiguration
  value: 'Release'
steps:
- task: PowerShell@2
  displayName: 'IoT Central'
  inputs:
    filePath: 'PowerShell/IoTC-Task.ps1'
    arguments: '-ApiToken "$(API-Token)" -ConfigPath "Config/Production/IoTC Configuration" -AppName "{your production IoT Central app name}" -ServicePrincipalPassword (ConvertTo-SecureString "$(SP-Password)" -AsPlainText -Force) -AppId "{your service principal app id}" -KeyVault "{your production key vault name}" -TenantId "{your tenant id}"'
    pwsh: true
    failOnStderr:  true

  3. Zvolte Uložit a Spustit.

  4. Soubor YAML se uloží do úložiště GitHubu, takže musíte zadat zprávu potvrzení a pak vybrat Uložit a spustit znovu.

Váš kanál je zařazen do fronty. Než se spustí, může to trvat několik minut.

Při prvním spuštění kanálu se zobrazí výzva k udělení oprávnění kanálu pro přístup k vašemu předplatnému a přístupu k trezoru klíčů. Vyberte Povolit a pak znovu povolte pro každý prostředek.

Po úspěšném dokončení úlohy kanálu se přihlaste k produkční aplikaci IoT Central a ověřte, že se konfigurace použila podle očekávání.

Zvýšení úrovně změn z vývoje do produkčního prostředí

Teď, když máte funkční kanál, můžete spravovat instance IoT Central přímo pomocí změn konfigurace. Nové šablony zařízení můžete nahrát do složky Modely zařízení a provést změny přímo v konfiguračním souboru. Tento přístup vám umožní zacházet s konfigurací aplikace IoT Central stejně jako s jakýmkoli jiným kódem.

Další krok

Teď, když víte, jak integrovat konfigurace IoT Central do kanálů CI/CD, je navrhovaným dalším krokem informace o správě a monitorování aplikací IoT Central.