Integrieren von IoT Central in Azure Pipelines zum Implementieren von Continuous Integration und Continuous Delivery (CI/CD)

Artikel
06/12/2023

Continuous Integration und Continuous Delivery (CI/CD) bezieht sich auf den Prozess der Entwicklung und Bereitstellung von Software in kurzen, häufigen Zyklen unter Verwendung von Automatisierungspipelines. In diesem Artikel wird gezeigt, wie Sie das Erstellen, Testen und Bereitstellen von IoT Central-Anwendungskonfigurationen automatisieren. Diese Automatisierung ermöglicht es Entwicklungsteams, häufiger zuverlässige Releases bereitzustellen.

Continuous Integration beginnt mit einem Commit Ihres Codes in einen Zweig Branch ein einem Quellcoderepository. Jeder Commit wird mit den Commits anderer Entwickler zusammengeführt, um sicherzustellen, dass keine Konflikte entstehen. Änderungen werden weiter überprüft, indem ein Build erstellt und automatisierte Tests für diesen Build ausgeführt werden. Dieser Prozess führt letztendlich zu einem Artefakt oder Bereitstellungspaket, das in einer Zielumgebung bereitgestellt werden kann. In diesem Fall ist das Ziel eine Azure IoT Central-Anwendung.

Ebenso wie IoT Central Teil Ihrer umfangreicheren IoT-Lösung ist, ist IoT Central auch Teil Ihrer CI/CD-Pipeline. Ihre CI/CD-Pipeline sollte Ihre gesamte IoT-Lösung und alle Konfigurationen für jede Umgebung von der Entwicklung bis hin zur Produktion bereitstellen:

Diagramm der Stufen einer typischen CI/CD-Pipeline.

IoT Central ist eine Anwendungsplattform als Dienst mit unterschiedlichen Bereitstellungsanforderungen der Plattform als Dienst-Komponenten. Für IoT Central stellen Sie Konfigurationen und Gerätevorlagen bereit. Diese Konfigurationen und Gerätevorlagen werden mithilfe von APIs verwaltet und in Ihre Releasepipeline integriert.

Obwohl es möglich ist, die Erstellung von IoT Central-Anwendungen zu automatisieren, sollten Sie in jeder Umgebung eine Anwendung erstellen, bevor Sie Ihre CI/CD-Pipeline entwickeln.

Mithilfe der Azure IoT Central REST-API können Sie die Konfigurationen der IoT Central-Anwendung in Ihre Releasepipeline integrieren.

In diesem Leitfaden wird die Erstellung einer neuen Pipeline beschrieben, die eine IoT Central-Anwendung basierend auf Konfigurationsdateien aktualisiert, die in GitHub verwaltet werden. Dieser Leitfaden enthält spezielle Anweisungen für die Integration in Azure Pipelines. Diese können jedoch angepasst werden, um IoT Central in eine beliebige andere Releasepipeline einzufügen, die mit Tools wie Tekton, Jenkins, GitLab oder GitHub Actions erstellt wurde.

In diesem Leitfaden erstellen Sie eine Pipeline, die eine IoT Central-Konfiguration lediglich auf eine einzelne Instanz einer IoT Central-Anwendung anwendet. Sie sollten die Schritte in eine größere Pipeline integrieren, die Ihre gesamte Lösung bereitstellt und alle Phasen von der Entwicklung über die Qualitätssicherung und Präproduktion bis zur Produktion mit allen erforderlichen Tests durchläuft.

Die Skripts übertragen derzeit nicht die folgenden Einstellungen zwischen IoT Central-Instanzen: Dashboards, Ansichten, benutzerdefinierte Einstellungen in Gerätevorlagen, Preisplan, Anpassungen der Benutzerfunktionalität, Anwendungsimage, Regeln, geplante Aufträge, gespeicherte Aufträge und Registrierungsgruppen.

Die Skripts entfernen derzeit keine Einstellungen aus der IoT Central-Zielanwendung, die nicht in der Konfigurationsdatei vorhanden sind.

Voraussetzungen

Damit Sie die in diesem Artikel aufgeführten Schritte ausführen können, benötigen Sie Folgendes:

Zwei IoT Central-Anwendungen – eine für Ihre Entwicklungsumgebung und eine für Ihre Produktionsumgebung. Weitere Informationen finden Sie unter Erstellen einer IoT Central-Anwendung.
Zwei Azure Key Vault-Instanzen – eine für Ihre Entwicklungsumgebung und eine für Ihre Produktionsumgebung. Es hat sich bewährt, eine dedizierte Key Vault-Instanz für jede Umgebung zu verwenden. Weitere Informationen finden Sie unter Erstellen einer Azure Key Vault-Instanz über das Azure-Portal.
Ein GitHub-Konto in GitHub.
Eine Azure DevOps-Organisation. Weitere Informationen finden Sie unter Erstellen einer Azure DevOps-Organisation.
PowerShell 7 für Windows, Mac oder Linux. PowerShell herunterladen.
Azure Az PowerShell-Modul, das in Ihrer PowerShell 7-Umgebung installiert ist. Weitere Informationen finden Sie unter Installieren des Azure Az PowerShell-Moduls.
Visual Studio Code oder anderes Tool zum Bearbeiten von PowerShell- und JSON-Dateien. Visual Studio Code herunterladen.
Git-Client. Neueste Version von Git – Downloads (git-scm.com) herunterladen.

Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.
Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.
- Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.
- Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.
- Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Herunterladen des Beispielcodes

Forken Sie als Erstes das IoT Central CI/CD GitHub-Repository, und klonen Sie dann die Fork auf Ihren lokalen Computer:

Öffnen Sie zum Forken des GitHub-Repositorys das IoT Central CI/CD GitHub-Repository, und wählen Sie Fork aus.
Klonen Sie Ihre Fork des Repositorys auf Ihren lokalen Computer, indem Sie ein Konsolen- oder Bash-Fenster öffnen und den folgenden Befehl ausführen.
```
git clone https://github.com/{your GitHub username}/iot-central-CICD-sample
```

Erstellen eines Dienstprinzipals

Während Azure Pipelines direkt mit einem Schlüsseltresor kombiniert werden kann, erfordert Ihre Pipeline für einige dynamische Schlüsseltresorinteraktionen (z. B. zum Abrufen von Geheimnissen für Datenexportziele) einen Dienstprinzipal.

So erstellen Sie einen Dienstprinzipal für Ihr Abonnement:

Führen Sie den folgenden Befehl aus, um einen neuen Dienstprinzipal zu erstellen:

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

Notieren Sie sich password, appId und tenant, da diese Werte später benötigt werden.

Fügen Sie das Dienstprinzipalkennwort als Geheimnis namens SP-Password zum Schlüsseltresor für die Produktion hinzu:

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

Erteilen Sie dem Dienstprinzipal die Berechtigung zum Lesen von Geheimnissen aus dem Schlüsseltresor:

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

Generieren von IoT Central-API-Token

In diesem Leitfaden verwendet die Pipeline für die Interaktion mit den IoT Central-Anwendungen API-Token. Es ist auch möglich, einen Dienstprinzipal zu verwenden.

Hinweis

IoT Central-API-Token laufen nach einem Jahr ab.

Führen Sie die folgenden Schritte für Ihre IoT Central-Entwicklungs- und -Produktionsanwendung aus.

Wählen Sie in Ihrer IoT Central-Anwendung Berechtigungen und dann API-Token aus.
Wählen Sie Neu aus.
Weisen Sie dem Token einen Namen zu, geben Sie die Organisation auf oberster Ebene in Ihrer Anwendung an, und legen Sie die Rolle auf App-Administrator fest.
Notieren Sie sich das API-Token Ihrer IoT Central-Entwicklungsanwendung. Sie verwenden es später, wenn Sie das IoTC-Config.ps1-Skript ausführen.
Speichern Sie das generierte Token der IoT Central-Produktionsanwendung als Geheimnis namens API-Token im Schlüsseltresor für die Produktion:
```
az keyvault secret set --name API-Token --vault-name {your production key vault name} --value '{your production app API token}'
```

Generieren einer Konfigurationsdatei

Die folgenden Schritte erstellen eine JSON-Konfigurationsdatei für Ihre Entwicklungsumgebung basierend auf einer vorhandenen IoT Central-Anwendung. Sie laden auch alle vorhandenen Gerätevorlagen aus der Anwendung herunter.

Führen Sie das folgende PowerShell 7-Skript in der lokalen Kopie des IoT Central-CI/CD-Repositorys aus:
```
cd .\iot-central-CICD-sample\PowerShell\
.\IoTC-Config.ps1
```
Befolgen Sie die Anweisungen, um sich bei Ihrem Azure-Konto anzumelden.
Nach der Anmeldung zeigt das Skript ein Menü mit IoTC-Konfigurationsoptionen an. Das Skript kann eine Konfigurationsdatei aus einer vorhandenen IoT Central-Anwendung generieren und eine Konfiguration auf eine andere IoT Central-Anwendung anwenden.
Wählen Sie Option 1 aus, um eine Konfigurationsdatei zu generieren.
Geben Sie die erforderlichen Parameter ein, und drücken Sie die EINGABETASTE:
- Das API-Token, das Sie für Ihre IoT Central-Entwicklungsanwendung generiert wurde.
- Die Unterdomäne Ihrer IoT Central-Entwicklungsanwendung.
- Geben Sie ..\Config\Dev als Ordner ein, in dem die Konfigurationsdatei und die Gerätevorlagen gespeichert werden sollen.
- Der Namen Ihres Schlüsseltresors für die Entwicklung.
Das Skript erstellt in Ihrer lokalen Kopie des Repositorys einen Ordner namens IoTC Configuration im Ordner Config\Dev. Dieser Ordner enthält eine Konfigurationsdatei und einen Ordner namens Device Models für alle Gerätevorlagen in Ihrer Anwendung.

Ändern der Konfigurationsdatei

Nachdem Sie nun über eine Konfigurationsdatei verfügen, die die Einstellungen für Ihre IoT Central-Entwicklungsanwendungsinstanz enthält, nehmen Sie alle erforderlichen Änderungen vor, bevor Sie diese Konfiguration auf Ihre IoT Central-Produktionsanwendungsinstanz anwenden.

Erstellen Sie eine Kopie des zuvor erstellten Dev-Ordners, und nennen Sie ihn Production.
Öffnen Sie die IoTC-Config.json-Datei im Production-Ordner in einem Text-Editor.

Die Datei umfasst mehrere Abschnitte. Wenn Ihre Anwendung jedoch eine bestimmte Einstellung nicht verwendet, wird der betreffende Abschnitt aus der Datei ausgelassen:

{
  "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": []
  }
}

Wenn Ihre Anwendung Dateiuploads verwendet, erstellt das Skript ein Geheimnis im Schlüsseltresor für die Entwicklung mit dem Wert der connectionString-Eigenschaft. Erstellen Sie im Schlüsseltresor für die Produktion ein Geheimnis mit dem gleichen Namen, das die Verbindungszeichenfolge für Ihr Produktionsspeicherkonto enthält. Zum Beispiel:
```
az keyvault secret set --name FileUpload --vault-name {your production key vault name} --value '{your production storage account connection string}'
```
Wenn Ihre Anwendung verwaltete Identitäten für Datenexportziele verwendet, gibt es keine geheimen Schlüssel, die Sie verwalten können. Sie müssen jedoch die vom System zugewiesene verwaltete Identität für Ihre IoT Central-Produktionsanwendung aktivieren und ihr die erforderlichen Berechtigungen zum Schreiben an das Ziel erteilen.
Wenn Ihre Anwendung Verbindungszeichenfolgen für Datenexportziele verwendet, fügen Sie Geheimnisse für die Ziele zum Produktionsschlüsseltresor hinzu. Die Konfigurationsdatei enthält tatsächlich keine Geheimnisse für Ihr Ziel, die Geheimnisse werden in Ihrem Schlüsseltresor gespeichert.

Aktualisieren Sie die Geheimnisse in der Konfigurationsdatei mit dem Namen des Geheimnisses im Schlüsseltresor.

Zieltyp	Zu ändernde Eigenschaft
Service Bus-Warteschlange	connectionString
Service Bus-Topic	connectionString
Azure-Daten-Explorer	clientSecret
Azure Blob Storage	connectionString
Event Hubs	connectionString
Webhook No Auth	N/V

Zum Beispiel:

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

Um den Configuration-Ordner in Ihr GitHub-Repository hochzuladen, führen Sie die folgenden Befehle im IoTC-CICD-howto-Ordner aus.
```
 git add Config
 git commit -m "Adding config directories and files"
 git push
```

Erstellen einer Pipeline

Öffnen Sie Ihre Azure DevOps-Organisation in einem Webbrowser, indem Sie https://dev.azure.com/{your DevOps organization} aufrufen.
Wählen Sie Neues Projekt aus, um ein neues Projekt zu erstellen.
Geben Sie einen Namen und eine optionale Beschreibung für Ihr Projekt ein, und wählen Sie dann Erstellen aus.
Wählen Sie auf der Begrüßungsseite des Projekts Pipelines und dann Pipeline erstellen aus.
Wählen Sie GitHub als Speicherort für Ihren Code aus.
Wählen Sie Azure Pipelines autorisieren aus, damit Azure Pipelines auf Ihr GitHub-Konto zugreifen darf.
Wählen Sie auf der Seite Repository auswählen ihre Fork des IoT Central CI/CD GitHub-Repositorys aus.
Wählen Sie Genehmigen und installieren aus, wenn Sie aufgefordert werden, sich bei GitHub anzumelden und Azure-Pipelines Zugriffsberechtigungen für das Repository zu gewähren.
Wählen Sie als Erstes auf der Seite Pipeline konfigurieren die Option Starterpipeline aus. Die Datei azure-pipelines.yml wird angezeigt, damit Sie sie bearbeiten können.

Erstellen einer Variablengruppe

Eine einfache Möglichkeit zum Integrieren von Schlüsseltresorgeheimnissen in eine Pipeline sind Variablengruppen. Verwenden Sie eine Variablengruppe, um sicherzustellen, dass die richtigen Geheimnisse für Ihr Bereitstellungsskript verfügbar sind. So erstellen Sie eine Variablengruppe:

Wählen Sie Bibliothek im Abschnitt Pipelines des linken Menüs aus.
Wählen Sie + Variable group (Variablengruppe) aus.
Geben Sie keyvault den Namen für die Variablengruppe ein.
Aktivieren Sie den Umschalter, um Geheimnisse in einem Azure-Schlüsseltresor zu verknüpfen.
Wählen Sie Ihr Azure-Abonnement aus, und autorisieren Sie es. Wählen Sie dann Ihren Namen Ihres Schlüsseltresors für die Produktion aus.
Wählen Sie Hinzufügen aus, um Variablen zur Gruppe hinzuzufügen.
Fügen Sie folgende Geheimnisse hinzu:
- IoT Central-API-Schlüssel für Ihre Produktionsanwendung. Sie haben dieses Geheimnis bei der Erstellung API-Token genannt.
- Kennwort für den Dienstprinzipal, den Sie zuvor erstellt haben. Sie haben dieses Geheimnis bei der Erstellung SP-Password genannt.
Wählen Sie OK aus.
Wählen Sie Speichern aus, um die Variablengruppe zu speichern.

Ihre Pipeline konfigurieren

Konfigurieren Sie jetzt die Pipeline, um Konfigurationsänderungen an Ihre IoT Central-Anwendung zu pushen:

Wählen Sie Pipelines im Abschnitt Pipelines des linken Menüs aus.

Ersetzen Sie den YAML-Code Ihrer Pipeline durch folgenden YAML-Code. Die Konfiguration geht davon aus, dass folgende Geheimnisse in Ihrem Schlüsseltresor für die Produktion enthalten sind:

API-Token für Ihre IoT Central-Produktionsanwendung in einem Geheimnis namens API-Token.
Kennwort des Dienstprinzipals in einem Geheimnis namens SP-Password.

Ersetzen Sie die Werte für -AppName und -KeyVault durch die entsprechenden Werte für Ihre Produktionsinstanzen.

Sie haben sich -AppId und -TenantId beim Erstellen Ihres Dienstprinzipals notiert.

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

Klicken Sie auf Speichern und ausführen.
Weil die YAML-Datei in Ihrem GitHub-Repository gespeichert wird, müssen Sie eine Commitnachricht bereitstellen und dann erneut Speichern und ausführen auswählen.

Ihre Pipeline wird in die Warteschlange eingereiht. Es kann einige Minuten dauern, bevor sie ausgeführt wird.

Bei der ersten Ausführung Ihrer Pipeline werden Sie aufgefordert, der Pipeline Zugriffsberechtigungen für Ihr Abonnement und Ihren Schlüsseltresor zu erteilen. Wählen Sie Zulassen und dann erneut Zulassen für jede Ressource aus.

Melden Sie sich nach der erfolgreichen Durchführung des Pipelineauftrag bei Ihrer IoT Central-Produktionsanwendung an, und überprüfen Sie, ob die Konfiguration wie erwartet übernommen wurde.

Übergeben von Änderungen aus der Entwicklung an die Produktion

Nachdem Sie über eine funktionierende Pipeline verfügen, können Sie Ihre IoT Central-Instanzen direkt über Konfigurationsänderungen verwalten. Sie können neue Gerätevorlagen in den Ordner Device Models hochladen und Änderungen direkt an der Konfigurationsdatei vornehmen. Diese Vorgehensweise bietet die Möglichkeit, die Konfiguration Ihrer IoT Central-Anwendung wie jeden anderen Code zu behandeln.

Nächster Schritt

Nachdem Sie nun wissen, wie Sie IoT Central-Konfigurationen in Ihre CI/CD-Pipelines integrieren, sollten Sie sich als Nächstes mit dem Verwalten und Überwachen von IoT Central-Anwendungen vertraut machen.

Freigeben über