Intégrer IoT Central à Azure Pipelines pour l’intégration continue et la livraison continue

  • Article

L’intégration continue et la livraison continue (CI/CD) font référence au processus de développement et de livraison de logiciels dans des cycles courts et fréquents grâce à l’utilisation de pipelines d’automatisation. Cet article montre comment automatiser la génération, le test et le déploiement d’une configuration d’application IoT Central. Cette automatisation permet aux équipes de développement de fournir des mises en production fiables plus fréquemment.

L’intégration continue commence par un commit de votre code sur une branche dans un dépôt de code source. Chaque commit est fusionné avec les commits d’autres développeurs pour s’assurer qu’aucun conflit n’est introduit. Les modifications sont ensuite validées en créant une build et en exécutant des tests automatisés sur cette build. Ce processus aboutit au final à un artefact, ou bundle de déploiement, à déployer sur un environnement cible. Dans le cas présent, la cible est une application Azure IoT Central.

Tout comme IoT Central fait partie de votre solution IoT globale, IoT Central fait partie de votre pipeline CI/CD. Votre pipeline CI/CD doit déployer toute votre solution IoT et toutes les configurations sur chaque environnement du développement à la production :

Diagramme qui montre les phases d’un pipeline CI/CD classique.

IoT Central est une plateforme d’application en tant que service qui a des exigences de déploiement différentes des composants de plateforme en tant que service. Pour IoT Central, vous déployez des configurations et des modèles d’appareil. Ces configurations et modèles d’appareil sont gérés et intégrés dans votre pipeline de mise en production à l’aide d’API.

Bien qu’il soit possible d’automatiser la création d’applications IoT Central, vous devez créer une application dans chaque environnement avant de développer votre pipeline CI/CD.

À l’aide de l’API REST Azure IoT Central, vous pouvez intégrer des configurations d’application IoT Central dans votre pipeline de mise en production.

Ce guide vous accompagne tout au long de la création d’un pipeline qui met à jour une application IoT Central en fonction des fichiers de configuration gérés dans GitHub. Ce guide contient des instructions spécifiques pour l’intégration à Azure Pipelines, mais peut être adapté pour inclure IoT Central dans n’importe quel pipeline de mise en production créé à l’aide d’outils tels que Tekton, Jenkins, GitLab ou GitHub Actions.

Dans ce guide, vous créez un pipeline qui applique uniquement une configuration IoT Central à une seule instance d’une application IoT Central. Vous devez intégrer les étapes dans un pipeline plus grand qui déploie toute votre solution et la promeut du développement vers l’assurance qualité jusqu’à la préproduction et la production, en effectuant tous les tests nécessaires au fil de ces opérations.

Actuellement, les scripts ne transfèrent pas les paramètres suivants entre les instances IoT Central : tableaux de bord, vues, paramètres personnalisés dans les modèles d’appareil, plan tarifaire, personnalisations d’expérience utilisateur, image d’application, règles, travaux planifiés, travaux enregistrés et groupes d’inscription.

Les scripts ne suppriment actuellement pas les paramètres de l’application IoT Central cible qui ne sont pas présents dans le fichier de configuration.

Prérequis

Pour effectuer les étapes indiquées dans ce guide, vous avez besoin des prérequis suivants :

Télécharger l’exemple de code

Pour commencer, dupliquez (fork) le dépôt GitHub CI/CD IoT Central, puis clonez votre duplication sur votre ordinateur local :

  1. Pour dupliquer le dépôt GitHub, ouvrez le dépôt GitHub CI/CD IoT Central, puis sélectionnez Dupliquer.

  2. Clonez votre duplication du dépôt sur votre ordinateur local en ouvrant une fenêtre de console ou Bash et en exécutant la commande suivante.

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

Créer un principal du service

Bien qu’Azure Pipelines puisse s’intégrer directement à un coffre de clés, un pipeline a besoin d’un principal de service pour certaines interactions de coffre de clés dynamiques telles que l’extraction de secrets pour les destinations d’exportation de données.

Pour créer un principal de service limité à votre abonnement :

  1. Exécutez la commande suivante pour créer un principal de service :

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

  2. Notez le mot de passe, l’appId et le locataire, car vous aurez besoin de ces valeurs ultérieurement.

  3. Ajoutez le mot de passe du principal de service comme secret appelé SP-Password à votre coffre de clés de production :

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

  4. Donnez au principal de service l’autorisation de lire les secrets à partir du coffre de clés :

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

Générer des jetons d’API IoT Central

Dans ce guide, votre pipeline utilise des jetons d’API pour interagir avec vos applications IoT Central. Il est également possible d’utiliser un principal de service.

Remarque

Les jetons d’API IoT Central expirent au bout d’un an.

Effectuez les étapes suivantes pour vos applications IoT Central de développement et de production.

  1. Dans votre application IoT Central, sélectionnez Autorisations, puis Jetons d’API.

  2. Cliquez sur Nouveau.

  3. Donnez un nom au jeton, spécifiez l’organisation de niveau supérieur dans votre application et définissez le rôle sur Administrateur d’application.

  4. Notez le jeton d’API de votre application IoT Central de développement. Vous l’utiliserez ultérieurement quand vous exécuterez le script IoTC-Config.ps1.

  5. Enregistrez le jeton généré à partir de l’application IoT Central de production en tant que secret appelé API-Token dans le coffre de clés de production :

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

Générer un fichier de configuration

Ces étapes produisent un fichier de configuration JSON pour votre environnement de développement en fonction d’une application IoT Central existante. Vous téléchargez également tous les modèles d’appareil existants à partir de l’application.

  1. Exécutez le script PowerShell 7 suivant dans la copie locale du dépôt CI/CD IoT Central :

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

  2. Suivez les instructions pour vous connecter à votre compte Azure.

  3. Une fois connecté, le script affiche le menu des options de configuration IoTC. Le script peut générer un fichier de configuration à partir d’une application IoT Central existante et appliquer une configuration à une autre application IoT Central.

  4. Sélectionnez l’option 1 pour générer un fichier de configuration.

  5. Entrez les paramètres nécessaires, puis appuyez sur Entrée :

    • Jeton d’API que vous avez généré pour votre application IoT Central de développement.
    • Sous-domaine de votre application IoT Central de développement.
    • Entrez ..\Config\Dev comme dossier pour stocker le fichier de configuration et les modèles d’appareil.
    • Nom de votre coffre de clés de développement.

  6. Le script crée un dossier appelé Configuration IoTC dans le dossier Config\Dev dans votre copie locale du dépôt. Ce dossier contient un fichier de configuration et un dossier appelé Modèles d’appareil pour tous les modèles d’appareil de votre application.

Modifiez le fichier de configuration

Maintenant que vous disposez d’un fichier de configuration qui représente les paramètres de votre instance d’application IoT Central de développement, apportez toutes les modifications nécessaires avant d’appliquer cette configuration à votre instance d’application IoT Central de production.

  1. Créez une copie du dossier Dev créé précédemment et appelez-la Production.

  2. Ouvrez IoTC-Config.json dans le dossier Production à l’aide d’un éditeur de texte.

  3. Le fichier comporte plusieurs sections. Toutefois, si votre application n’utilise pas de paramètre particulier, cette section est omise du fichier :

    {
  "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. Si votre application utilise des chargements de fichiers, le script crée un secret dans votre coffre de clés de développement avec la valeur indiquée dans la propriété connectionString. Créez un secret portant le même nom dans votre coffre de clés de production qui contient la chaîne de connexion de votre compte de stockage de production. Par exemple :

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

  5. Si votre application utilise des exportations de données, ajoutez des secrets pour les destinations au coffre de clés de production. Le fichier de configuration ne contient pas de secrets réels pour votre destination, les secrets sont stockés dans votre coffre de clés.

  6. Mettez à jour les secrets dans le fichier de configuration avec le nom du secret dans votre coffre de clés.

    Type de destination Propriété à modifier
    File d’attente Service Bus connectionString
    Rubrique Service Bus connectionString
    Explorateur de données Azure clientSecret
    Stockage Blob Azure connectionString
    Event Hubs connectionString
    Webhook sans authentification S/O

    Par exemple :

    "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. Pour charger le dossier Configuration sur votre dépôt GitHub, exécutez les commandes suivantes à partir du dossier IoTC-CICD-howto.

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

Créer un pipeline

  1. Ouvrez votre organisation Azure DevOps dans un navigateur web en accédant à https://dev.azure.com/{your DevOps organization}
  2. Sélectionnez Nouveau projet pour créer un projet.
  3. Donnez un nom et une description facultative à votre projet, puis sélectionnez Créer.
  4. Dans la page Bienvenue dans le projet, sélectionnez Pipelines, puis Créer un pipeline.
  5. Sélectionnez GitHub comme emplacement de votre code.
  6. Sélectionnez Autoriser Azure Pipelines pour autoriser Azure Pipelines à accéder à votre compte GitHub.
  7. Dans la page Sélectionner un dépôt, sélectionnez votre duplication du dépôt GitHub CI/CD IoT Central.
  8. Lorsque vous êtes invité à vous connecter à GitHub et à fournir l’autorisation à Azure Pipelines d’accéder au dépôt, sélectionnez Approuver et installer.
  9. Dans la page Configurer votre pipeline, sélectionnez Pipeline de démarrage pour démarrer. Le fichier azure-pipelines.yml s’affiche et vous pouvez le modifier.

Créer un groupe de variables

Un moyen simple d’intégrer des secrets de coffre de clés dans un pipeline consiste à utiliser des groupes de variables. Utilisez un groupe de variables pour vous assurer que les secrets appropriés sont disponibles pour votre script de déploiement. Pour créer un groupe de variables :

  1. Sélectionnez Bibliothèque dans la section Pipelines du menu de gauche.

  2. Sélectionnez + Groupe de variables.

  3. Entrez keyvault comme nom de votre groupe de variables.

  4. Activez le bouton bascule pour lier des secrets à partir d’un coffre de clés Azure.

  5. Sélectionnez votre abonnement Azure et autorisez-le. Sélectionnez ensuite le nom de votre coffre de clés de production.

  6. Sélectionnez Ajouter pour commencer à ajouter des variables au groupe.

  7. Ajoutez les secrets suivants :

    • Clé API IoT Central pour votre application de production. Vous avez appelé ce secret API-Token lorsque vous l’avez créé.
    • Mot de passe du principal de service que vous avez créé précédemment. Vous avez appelé ce secret SP-Password lorsque vous l’avez créé.

  8. Cliquez sur OK.

  9. Sélectionnez Enregistrer pour enregistrer le groupe de variables.

Configurer votre pipeline

Configurez maintenant le pipeline pour pousser (push) les modifications de configuration vers votre application IoT Central :

  1. Sélectionnez Pipelines dans la section Pipelines du menu de gauche.

  2. Remplacez le contenu du fichier YAML de votre pipeline par le fichier YAML suivant. La configuration suppose que votre coffre de clés de production contient :

    • Jeton d’API pour votre application IoT Central de production dans un secret appelé API-Token.
    • Votre mot de passe de principal de service dans un secret appelé SP-Password.

    Remplacez les valeurs pour -AppName et -KeyVault par les valeurs appropriées pour vos instances de production.

    Vous avez noté -AppId et -TenantId au moment de la création de votre principal de service.

    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. Sélectionnez Enregistrer et exécuter.

  4. Le fichier YAML est enregistré dans votre dépôt GitHub. Vous devez donc fournir un message de validation, puis sélectionner Enregistrer et exécuter une nouvelle fois.

Votre pipeline est mis en file d’attente. Quelques minutes peuvent s’écouler avant son exécution.

La première fois que vous exécutez votre pipeline, vous êtes invité à accorder des autorisations pour que le pipeline accède à votre abonnement et à votre coffre de clés. Sélectionnez Autoriser, puis à nouveau Autoriser pour chaque ressource.

Une fois votre travail de pipeline terminé, connectez-vous à votre application IoT Central de production et vérifiez que la configuration a été appliquée comme prévu.

Promouvez les modifications du développement à la production

Maintenant que vous disposez d’un pipeline opérationnel, vous pouvez gérer vos instances IoT Central directement à l’aide de modifications de configuration. Vous pouvez charger de nouveaux modèles d’appareil dans le dossier Modèles d’appareil et apporter des modifications directement au fichier de configuration. Cette approche vous permet de traiter la configuration de votre application IoT Central de la même façon que tout autre code.

Étape suivante

Maintenant que vous savez comment intégrer des configurations IoT Central dans vos pipelines CI/CD, une étape suivante suggérée consiste à découvrir comment gérer et superviser des applications IoT Central.