Dela via

Integrera IoT Central med Azure Pipelines för kontinuerlig integrering och kontinuerlig leverans

  • Artikel

Kontinuerlig integrering och kontinuerlig leverans (CI/CD) avser processen att utveckla och leverera programvara i korta, frekventa cykler med hjälp av automationspipelines. Den här artikeln visar hur du automatiserar bygget, testet och distributionen av en IoT Central-programkonfiguration. Med den här automatiseringen kan utvecklingsteam leverera tillförlitliga versioner oftare.

Kontinuerlig integrering börjar med en incheckning av koden till en gren i en källkodslagringsplats. Varje incheckning sammanfogas med incheckningar från andra utvecklare för att säkerställa att inga konflikter införs. Ändringar verifieras ytterligare genom att skapa en version och köra automatiserade tester mot den versionen. Den här processen resulterar i slutänden i en artefakt eller ett distributionspaket som distribueras till en målmiljö. I det här fallet är målet ett Azure IoT Central-program.

Precis som IoT Central är en del av din större IoT-lösning är IoT Central en del av din CI/CD-pipeline. Din CI/CD-pipeline bör distribuera hela IoT-lösningen och alla konfigurationer till varje miljö från utveckling till produktion:

Diagram som visar stegen i en typisk CI/CD-pipeline.

IoT Central är en programplattform som en tjänst som har olika distributionskrav från plattform som tjänstkomponenter . För IoT Central distribuerar du konfigurationer och enhetsmallar. Dessa konfigurationer och enhetsmallar hanteras och integreras i versionspipelinen med hjälp av API:er.

Det är möjligt att automatisera skapandet av IoT Central-appar, men du bör skapa en app i varje miljö innan du utvecklar din CI/CD-pipeline.

Genom att använda Rest-API:et för Azure IoT Central kan du integrera IoT Central-appkonfigurationer i din versionspipeline.

Den här guiden beskriver hur du skapar en ny pipeline som uppdaterar ett IoT Central-program baserat på konfigurationsfiler som hanteras i GitHub. Den här guiden innehåller specifika instruktioner för integrering med Azure Pipelines, men kan anpassas för att inkludera IoT Central i alla versionspipelines som skapats med verktyg som Tekton, Jenkins, GitLab eller GitHub Actions.

I den här guiden skapar du en pipeline som endast tillämpar en IoT Central-konfiguration på en enda instans av ett IoT Central-program. Du bör integrera stegen i en större pipeline som distribuerar hela lösningen och höjer upp den från utveckling till QA till förproduktion till produktion och utför alla nödvändiga tester längs vägen.

Skripten överför för närvarande inte följande inställningar mellan IoT Central-instanser: instrumentpaneler, vyer, anpassade inställningar i enhetsmallar, prisplan, UX-anpassningar, programbild, regler, schemalagda jobb, sparade jobb och registreringsgrupper.

Skripten tar för närvarande inte bort inställningar från målprogrammet IoT Central som inte finns i konfigurationsfilen.

Förutsättningar

Du behöver följande förutsättningar för att slutföra stegen i den här guiden:

Ladda ned exempelkoden

Kom igång genom att förgrena IoT Central CI/CD GitHub-lagringsplatsen och sedan clne din förgrening till din lokala dator:o

  1. Om du vill förgrena GitHub-lagringsplatsen öppnar du IoT Central CI/CD GitHub-lagringsplatsen och väljer Förgrening.

  2. Klona din förgrening av lagringsplatsen till den lokala datorn genom att öppna ett konsol- eller bash-fönster och köra följande kommando.

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

Skapa ett huvudnamn för tjänsten

Azure Pipelines kan integreras direkt med ett nyckelvalv, men en pipeline behöver ett huvudnamn för tjänsten för vissa dynamiska nyckelvalvsinteraktioner som att hämta hemligheter för dataexportmål.

Så här skapar du ett tjänsthuvudnamn som är begränsat till din prenumeration:

  1. Kör följande kommando för att skapa ett nytt huvudnamn för tjänsten:

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

  2. Anteckna lösenordet, appId och klientorganisationen eftersom du behöver dessa värden senare.

  3. Lägg till lösenordet för tjänstens huvudnamn som en hemlighet som anropas SP-Password till ditt nyckelvalv för produktion:

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

  4. Ge tjänstens huvudnamn behörighet att läsa hemligheter från nyckelvalvet:

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

Generera IoT Central API-token

I den här guiden använder din pipeline API-token för att interagera med dina IoT Central-program. Det går också att använda tjänstens huvudnamn.

Kommentar

API-token för IoT Central upphör att gälla efter ett år.

Slutför följande steg för både dina IoT Central-appar för utveckling och produktion.

  1. I din IoT Central-app väljer du Behörigheter och sedan API-token.

  2. Välj Ny.

  3. Ge token ett namn, ange den översta organisationen i din app och ange rollen till Appadministratör.

  4. Anteckna API-token från ditt IoT Central-program för utveckling. Du använder det senare när du kör skriptet IoTC-Config.ps1 .

  5. Spara den genererade token från IoT Central-produktionsappen som en hemlighet som anropas API-Token till nyckelvalvet för produktion:

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

Generera en konfigurationsfil

De här stegen skapar en JSON-konfigurationsfil för utvecklingsmiljön baserat på ett befintligt IoT Central-program. Du kan också ladda ned alla befintliga enhetsmallar från programmet.

  1. Kör följande PowerShell 7-skript i den lokala kopian av IoT Central CI/CD-lagringsplatsen:

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

  2. Följ anvisningarna för att logga in på ditt Azure-konto.

  3. När du har loggat in visar skriptet menyn IoTC-konfigurationsalternativ. Skriptet kan generera en konfigurationsfil från ett befintligt IoT Central-program och tillämpa en konfiguration på ett annat IoT Central-program.

  4. Välj alternativ 1 för att generera en konfigurationsfil.

  5. Ange nödvändiga parametrar och tryck på Retur:

    • API-token som du genererade för ditt IoT Central-program för utveckling.
    • Underdomänen för ditt IoT Central-program för utveckling.
    • Ange .. \Config\Dev som mappen som ska lagra konfigurationsfilen och enhetsmallarna.
    • Namnet på ditt nyckelvalv för utveckling.

  6. Skriptet skapar en mapp med namnet IoTC Configuration i mappen Config\Dev i din lokala kopia av lagringsplatsen. Den här mappen innehåller en konfigurationsfil och en mapp med namnet Enhetsmodeller för alla enhetsmallar i ditt program.

Ändra konfigurationsfilen

Nu när du har en konfigurationsfil som representerar inställningarna för din IoT Central-programinstans för utveckling gör du nödvändiga ändringar innan du tillämpar den här konfigurationen på din IoT Central-programinstans för produktion.

  1. Skapa en kopia av den Dev-mapp som skapades tidigare och kalla den Produktion.

  2. Öppna IoTC-Config.json i mappen Produktion med hjälp av en textredigerare.

  3. Filen har flera avsnitt. Men om programmet inte använder en viss inställning utelämnas det avsnittet från filen:

    {
  "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. Om ditt program använder filuppladdningar skapar skriptet en hemlighet i ditt nyckelvalv för utveckling med värdet som visas i connectionString egenskapen. Skapa en hemlighet med samma namn i ditt produktionsnyckelvalv som innehåller anslutningssträng för ditt produktionslagringskonto. Till exempel:

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

  5. Om ditt program använder hanterade identiteter för dataexportmål finns det inga hemligheter som du kan hantera. Du behöver dock aktivera den systemtilldelade hanterade identiteten för ditt IoT Central-produktionsprogram och ge det de behörigheter som krävs för att skriva till målet.

  6. Om ditt program använder anslutningssträng för dataexportmål lägger du till hemligheter för målen i nyckelvalvet för produktion. Konfigurationsfilen innehåller inga faktiska hemligheter för ditt mål, hemligheterna lagras i ditt nyckelvalv.

  7. Uppdatera hemligheterna i konfigurationsfilen med namnet på hemligheten i nyckelvalvet.

    Måltyp Egenskap som ska ändras
    Service Bus-kö connectionString
    Service Bus-ämne connectionString
    Öppna Azure-datautforskaren clientSecret
    Azure Blob Storage connectionString
    Event Hubs connectionString
    Webhook Ingen autentisering Ej tillämpligt

    Till exempel:

    "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. Om du vill ladda upp konfigurationsmappen till din GitHub-lagringsplats kör du följande kommandon från mappen IoTC-CICD-howto.

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

Skapa en pipeline

  1. Öppna din Azure DevOps-organisation i en webbläsare genom att gå till https://dev.azure.com/{your DevOps organization}
  2. Välj Nytt projekt för att skapa ett nytt projekt.
  3. Ge projektet ett namn och en valfri beskrivning och välj sedan Skapa.
  4. På sidan Välkommen till projektet väljer du Pipelines och sedan Skapa pipeline.
  5. Välj GitHub som plats för koden.
  6. Välj Auktorisera AzurePipelines för att ge Azure Pipelines åtkomst till ditt GitHub-konto.
  7. På sidan Välj en lagringsplats väljer du din förgrening av IoT Central CI/CD GitHub-lagringsplatsen.
  8. När du uppmanas att logga in på GitHub och ge behörighet för Azure Pipelines att komma åt lagringsplatsen väljer du Godkänn och installera.
  9. På sidan Konfigurera pipeline väljer du Startpipeline för att komma igång. Du kan redigera azure-pipelines.yml .

Skapa en variabelgrupp

Ett enkelt sätt att integrera key vault-hemligheter i en pipeline är genom variabelgrupper. Använd en variabelgrupp för att säkerställa att rätt hemligheter är tillgängliga för distributionsskriptet. Så här skapar du en variabelgrupp:

  1. Välj Bibliotek i avsnittet Pipelines på menyn till vänster.

  2. Välj + Variabelgrupp.

  3. Ange keyvault som namn på variabelgruppen.

  4. Aktivera växlingsknappen för att länka hemligheter från ett Azure-nyckelvalv.

  5. Välj din Azure-prenumeration och auktorisera den. Välj sedan namnet på ditt nyckelvalv för produktion.

  6. Välj Lägg till för att börja lägga till variabler i gruppen.

  7. Lägg till följande hemligheter:

    • IoT Central API-nyckeln för din produktionsapp. Du anropade den här hemligheten API-Token när du skapade den.
    • Lösenordet för tjänstens huvudnamn som du skapade tidigare. Du anropade den här hemligheten SP-Password när du skapade den.

  8. Välj OK.

  9. Välj Spara för att spara variabelgruppen.

Konfigurera din pipeline

Konfigurera nu pipelinen för att skicka konfigurationsändringar till ditt IoT Central-program:

  1. Välj Pipelines i avsnittet Pipelines på menyn till vänster.

  2. Ersätt innehållet i din YAML-pipeline med följande YAML. Konfigurationen förutsätter att ditt nyckelvalv för produktion innehåller:

    • API-token för din IoT Central-produktionsapp i en hemlighet med namnet API-Token.
    • Lösenordet för tjänstens huvudnamn i en hemlighet med namnet SP-Password.

    Ersätt värdena för -AppName och -KeyVault med lämpliga värden för dina produktionsinstanser.

    Du antecknade -AppId och -TenantId när du skapade tjänstens huvudnamn.

    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. Välj Spara och kör.

  4. YAML-filen sparas på din GitHub-lagringsplats, så du måste ange ett incheckningsmeddelande och sedan välja Spara och köra igen.

Din pipeline står i kö. Det kan ta några minuter innan den körs.

Första gången du kör din pipeline uppmanas du att ge pipelinen behörighet att komma åt din prenumeration och få åtkomst till ditt nyckelvalv. Välj Tillåt och sedan Tillåt igen för varje resurs.

När pipelinejobbet har slutförts loggar du in på ditt IoT Central-produktionsprogram och kontrollerar att konfigurationen tillämpades som förväntat.

Främja ändringar från utveckling till produktion

Nu när du har en fungerande pipeline kan du hantera dina IoT Central-instanser direkt med hjälp av konfigurationsändringar. Du kan ladda upp nya enhetsmallar till mappen Enhetsmodeller och göra ändringar direkt i konfigurationsfilen. Med den här metoden kan du behandla konfigurationen för ditt IoT Central-program på samma sätt som annan kod.

Gå vidare

Nu när du vet hur du integrerar IoT Central-konfigurationer i dina CI/CD-pipelines är ett föreslaget nästa steg att lära dig hur du hanterar och övervakar IoT Central-program.