IoT Central integreren met Azure Pipelines voor continue integratie en continue levering

  • Artikel

Continue integratie en continue levering (CI/CD) verwijst naar het proces van het ontwikkelen en leveren van software in korte, frequente cycli met behulp van automatiseringspijplijnen. In dit artikel leest u hoe u de build, test en implementatie van een IoT Central-toepassingsconfiguratie automatiseert. Dankzij deze automatisering kunnen ontwikkelteams vaker betrouwbare releases leveren.

Continue integratie begint met het doorvoeren van uw code naar een vertakking in een opslagplaats met broncode. Elke doorvoering wordt samengevoegd met doorvoeringen van andere ontwikkelaars om ervoor te zorgen dat er geen conflicten worden geïntroduceerd. Wijzigingen worden verder gevalideerd door een build te maken en geautomatiseerde tests uit te voeren op die build. Dit proces resulteert uiteindelijk in een artefact of implementatiebundel om te implementeren in een doelomgeving. In dit geval is het doel een Azure IoT Central-toepassing.

Net zoals IoT Central deel uitmaakt van uw grotere IoT-oplossing, maakt IoT Central deel uit van uw CI/CD-pijplijn. Uw CI/CD-pijplijn moet uw volledige IoT-oplossing en alle configuraties in elke omgeving implementeren, van ontwikkeling tot productie:

Diagram met de fasen van een typische CI/CD-pijplijn.

IoT Central is een toepassingsplatform als een service met verschillende implementatievereisten van platform als serviceonderdelen . Voor IoT Central implementeert u configuraties en apparaatsjablonen. Deze configuraties en apparaatsjablonen worden beheerd en geïntegreerd in uw release-pijplijn met behulp van API's.

Hoewel het mogelijk is om het maken van IoT Central-apps te automatiseren, moet u in elke omgeving een app maken voordat u uw CI/CD-pijplijn ontwikkelt.

Met behulp van de Azure IoT Central REST API kunt u IoT Central-app-configuraties integreren in uw release-pijplijn.

Deze handleiding begeleidt u bij het maken van een nieuwe pijplijn waarmee een IoT Central-toepassing wordt bijgewerkt op basis van configuratiebestanden die worden beheerd in GitHub. Deze handleiding bevat specifieke instructies voor integratie met Azure Pipelines, maar kan worden aangepast om IoT Central op te nemen in elke releasepijplijn die is gebouwd met behulp van hulpprogramma's zoals Tekton, Jenkins, GitLab of GitHub Actions.

In deze handleiding maakt u een pijplijn die alleen een IoT Central-configuratie toepast op één exemplaar van een IoT Central-toepassing. U moet de stappen integreren in een grotere pijplijn die uw hele oplossing implementeert en deze bevordert van ontwikkeling naar QA tot preproductie naar productie, waarbij alle benodigde tests onderweg worden uitgevoerd.

De scripts dragen momenteel niet de volgende instellingen over tussen IoT Central-exemplaren: dashboards, weergaven, aangepaste instellingen in apparaatsjablonen, prijsplan, UX-aanpassingen, toepassingsinstallatiekopieën, regels, geplande taken, opgeslagen taken en inschrijvingsgroepen.

De scripts verwijderen momenteel geen instellingen uit de doel-IoT Central-toepassing die niet aanwezig zijn in het configuratiebestand.

Vereisten

U hebt de volgende vereisten nodig om de stappen in deze handleiding te voltooien:

De voorbeeldcode downloaden

Om aan de slag te gaan, forkt u de GitHub-opslagplaats voor IoT Central CI/CD en kloont u uw fork vervolgens naar uw lokale computer:

  1. Als u de GitHub-opslagplaats wilt splitsen, opent u de IoT Central CI/CD GitHub-opslagplaats en selecteert u Fork.

  2. Kloon uw fork van de opslagplaats naar uw lokale computer door een console- of bash-venster te openen en de volgende opdracht uit te voeren.

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

Een service-principal maken

Hoewel Azure Pipelines rechtstreeks kan worden geïntegreerd met een sleutelkluis, heeft een pijplijn een service-principal nodig voor bepaalde dynamische sleutelkluisinteracties, zoals het ophalen van geheimen voor gegevensexportbestemmingen.

Ga als volgende te werk om een service-principal te maken die is afgestemd op uw abonnement:

  1. Voer de volgende opdracht uit om een nieuwe service-principal te maken:

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

  2. Noteer het wachtwoord, de appId en de tenant, omdat u deze waarden later nodig hebt.

  3. Voeg het wachtwoord van de service-principal toe als een geheim dat is aangeroepen SP-Password aan uw productiesleutelkluis:

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

  4. Geef de service-principal toestemming om geheimen uit de sleutelkluis te lezen:

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

IoT Central-API-tokens genereren

In deze handleiding gebruikt uw pijplijn API-tokens om te communiceren met uw IoT Central-toepassingen. Het is ook mogelijk om een service-principal te gebruiken.

Notitie

IoT Central API-tokens verlopen na één jaar.

Voer de volgende stappen uit voor uw ioT Central-apps voor ontwikkeling en productie.

  1. Selecteer machtigingen in uw IoT Central-app en vervolgens API-tokens.

  2. Selecteer Nieuw.

  3. Geef het token een naam, geef de organisatie op het hoogste niveau in uw app op en stel de rol in op App Beheer istrator.

  4. Noteer het API-token van uw IoT Central-ontwikkeltoepassing. U gebruikt deze later wanneer u het IoTC-Config.ps1-script uitvoert.

  5. Sla het gegenereerde token op uit de IoT Central-productietoepassing als een geheim dat wordt aangeroepen API-Token naar de productiesleutelkluis:

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

Een configuratiebestand genereren

Deze stappen produceren een JSON-configuratiebestand voor uw ontwikkelomgeving op basis van een bestaande IoT Central-toepassing. U downloadt ook alle bestaande apparaatsjablonen uit de toepassing.

  1. Voer het volgende PowerShell 7-script uit in de lokale kopie van de IoT Central CI/CD-opslagplaats:

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

  2. Volg de instructies om u aan te melden bij uw Azure-account.

  3. Nadat u zich hebt aangemeld, wordt in het script het menu IoTC-configuratieopties weergegeven. Het script kan een configuratiebestand genereren op basis van een bestaande IoT Central-toepassing en een configuratie toepassen op een andere IoT Central-toepassing.

  4. Selecteer optie 1 om een configuratiebestand te genereren.

  5. Voer de benodigde parameters in en druk op Enter:

    • Het API-token dat u hebt gegenereerd voor uw IoT Central-ontwikkeltoepassing.
    • Het subdomein van uw IoT Central-toepassing voor ontwikkeling.
    • Voer .. in . \Config\Dev als map voor het opslaan van het configuratiebestand en apparaatsjablonen.
    • De naam van uw sleutelkluis voor ontwikkeling.

  6. Met het script maakt u een map met de naam IoTC-configuratie in de map Config\Dev in uw lokale kopie van de opslagplaats. Deze map bevat een configuratiebestand en een map met de naam Apparaatmodellen voor alle apparaatsjablonen in uw toepassing.

Het configuratiebestand wijzigen

Nu u een configuratiebestand hebt dat de instellingen voor uw ioT Central-toepassingsexemplaren voor ontwikkeling vertegenwoordigt, moet u de benodigde wijzigingen aanbrengen voordat u deze configuratie toepast op uw ioT Central-toepassingsexemplaren voor productie.

  1. Maak een kopie van de map Dev die u eerder hebt gemaakt en noem deze productie.

  2. Open IoTC-Config.json in de map Productie met behulp van een teksteditor.

  3. Het bestand heeft meerdere secties. Als uw toepassing echter geen bepaalde instelling gebruikt, wordt deze sectie weggelaten uit het bestand:

    {
  "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": "connectionString",
          "connectionString": "DefaultEndpointsProtocol=https;AccountName=yourexportaccount;AccountKey=*****;EndpointSuffix=core.windows.net",
          "containerName": "dataexport"
        },
        "status": "waiting"
      }
    ]
  },
  "file uploads": {
    "connectionString": "FileUpload",
    "container": "fileupload",
    "sasTtl": "PT1H"
  },
  "jobs": {
    "value": []
  }
}

  4. Als uw toepassing bestandsuploads gebruikt, maakt het script een geheim in uw ontwikkelsleutelkluis met de waarde die wordt weergegeven in de connectionString eigenschap. Maak een geheim met dezelfde naam in uw productiesleutelkluis met de verbindingsreeks voor uw productieopslagaccount. Voorbeeld:

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

  5. Als uw toepassing gegevensexport gebruikt, voegt u geheimen voor de bestemmingen toe aan de productiesleutelkluis. Het configuratiebestand bevat geen werkelijke geheimen voor uw bestemming, de geheimen worden opgeslagen in uw sleutelkluis.

  6. Werk de geheimen in het configuratiebestand bij met de naam van het geheim in uw sleutelkluis.

    Doeltype Eigenschap die moet worden gewijzigd
    Service Bus-wachtrij connectionString
    Service Bus-onderwerp connectionString
    Azure Data Explorer clientSecret
    Azure Blob-opslag connectionString
    Event Hubs connectionString
    Webhook zonder verificatie N.v.t.

    Voorbeeld:

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

  7. Als u de configuratiemap wilt uploaden naar uw GitHub-opslagplaats, voert u de volgende opdrachten uit vanuit de map IoTC-CICD-howto .

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

Een pipeline maken

  1. Open uw Azure DevOps-organisatie in een webbrowser door naar https://dev.azure.com/{your DevOps organization}
  2. Selecteer Nieuw project om een nieuw project te maken.
  3. Geef uw project een naam en een optionele beschrijving en selecteer Vervolgens Maken.
  4. Selecteer Op de pagina Welkom bij het project de optie Pijplijnen en vervolgens Pijplijn maken.
  5. Selecteer GitHub als de locatie van uw code.
  6. Selecteer AzurePipelines autoriseren om Azure Pipelines toegang te geven tot uw GitHub-account.
  7. Selecteer op de pagina Een opslagplaats selecteren uw fork van de GitHub-opslagplaats van IoT Central CI/CD.
  8. Wanneer u wordt gevraagd u aan te melden bij GitHub en toestemming te geven voor Azure Pipelines voor toegang tot de opslagplaats, selecteert u Goedkeuren en installeren.
  9. Selecteer Op de pagina Uw pijplijn configureren starterspijplijn om aan de slag te gaan. De azure-pipelines.yml wordt weergegeven om te bewerken.

Een variabelegroep maken

Een eenvoudige manier om sleutelkluisgeheimen in een pijplijn te integreren, is via variabele groepen. Gebruik een variabelegroep om ervoor te zorgen dat de juiste geheimen beschikbaar zijn voor uw implementatiescript. Een variabelegroep maken:

  1. Selecteer Bibliotheek in de sectie Pijplijnen van het menu aan de linkerkant.

  2. Selecteer + Variabele groep.

  3. Voer keyvault de naam in voor de variabelegroep.

  4. Schakel de wisselknop in om geheimen uit een Azure-sleutelkluis te koppelen.

  5. Selecteer uw Azure-abonnement en autoriseren. Selecteer vervolgens de naam van uw productiesleutelkluis.

  6. Selecteer Toevoegen om variabelen toe te voegen aan de groep.

  7. Voeg de volgende geheimen toe:

    • De IoT Central-API-sleutel voor uw productie-app. U hebt dit geheim API-Token aangeroepen toen u het maakte.
    • Het wachtwoord voor de service-principal die u eerder hebt gemaakt. U hebt dit geheim SP-Password aangeroepen toen u het maakte.

  8. Selecteer OK.

  9. Selecteer Opslaan om de variabelegroep op te slaan.

Uw pijplijn configureren

Configureer nu de pijplijn om configuratiewijzigingen naar uw IoT Central-toepassing te pushen:

  1. Selecteer Pijplijnen in de sectie Pijplijnen van het menu aan de linkerkant.

  2. Vervang de inhoud van uw pijplijn-YAML door de volgende YAML. Bij de configuratie wordt ervan uitgegaan dat uw productiesleutelkluis het volgende bevat:

    • Het API-token voor uw IoT Central-productie-app in een geheim met de naam API-Token.
    • Uw service-principal-wachtwoord in een geheim met de naam SP-Password.

    Vervang de waarden voor -AppName en -KeyVault door de juiste waarden voor uw productie-exemplaren.

    U hebt een notitie gemaakt van de -AppId service-principal en -TenantId toen u uw service-principal hebt gemaakt.

    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. Selecteer Opslaan en uitvoeren.

  4. Het YAML-bestand wordt opgeslagen in uw GitHub-opslagplaats, dus u moet een doorvoerbericht opgeven en vervolgens Opslaan selecteren en opnieuw uitvoeren .

Uw pijplijn is in de wachtrij geplaatst. Het kan enkele minuten duren voordat het wordt uitgevoerd.

De eerste keer dat u uw pijplijn uitvoert, wordt u gevraagd om machtigingen te verlenen voor de pijplijn om toegang te krijgen tot uw abonnement en om toegang te krijgen tot uw sleutelkluis. Selecteer Toestaan en vervolgens Opnieuw toestaan voor elke resource.

Wanneer de pijplijntaak is voltooid, meldt u zich aan bij de IoT Central-productietoepassing en controleert u of de configuratie is toegepast zoals verwacht.

Wijzigingen van ontwikkeling naar productie verhogen

Nu u een werkende pijplijn hebt, kunt u uw IoT Central-exemplaren rechtstreeks beheren met behulp van configuratiewijzigingen. U kunt nieuwe apparaatsjablonen uploaden naar de map Apparaatmodellen en rechtstreeks wijzigingen aanbrengen in het configuratiebestand. Met deze methode kunt u de configuratie van uw IoT Central-toepassing op dezelfde manier behandelen als andere code.

Volgende stap

Nu u weet hoe u IoT Central-configuraties kunt integreren in uw CI/CD-pijplijnen, is een voorgestelde volgende stap om te leren hoe u IoT Central-toepassingen beheert en bewaakt.