Condividi tramite

Integrare IoT Central con Azure Pipelines per l'integrazione continua e il recapito continuo

  • Articolo

L'integrazione continua e il recapito continuo (CI/CD) si riferisce al processo di sviluppo e distribuzione di software in brevi cicli frequenti tramite pipeline di automazione. Questo articolo illustra come automatizzare la compilazione, il test e la distribuzione di una configurazione dell'applicazione IoT Central. Questa automazione consente ai team di sviluppo di offrire versioni affidabili più frequentemente.

L'integrazione continua inizia con un commit del codice in un ramo in un repository di codice sorgente. Ogni commit viene unito con commit di altri sviluppatori per assicurarsi che non vengano introdotti conflitti. Le modifiche vengono convalidate ulteriormente creando una compilazione ed eseguendo test automatizzati su tale compilazione. Questo processo comporta in definitiva un artefatto, o un bundle di distribuzione, per la distribuzione in un ambiente di destinazione. In questo caso, la destinazione è un'applicazione Azure IoT Central.

Proprio come IoT Central fa parte della soluzione IoT più grande, IoT Central fa parte della pipeline CI/CD. La pipeline CI/CD deve distribuire l'intera soluzione IoT e tutte le configurazioni in ogni ambiente dallo sviluppo all'ambiente di produzione:

Diagramma che mostra le fasi di una tipica pipeline CI/CD.

IoT Central è una piattaforma applicativa distribuita come servizio che presenta requisiti di distribuzione diversi rispetto ai componenti della piattaforma distribuita come servizio. Per IoT Central si distribuiscono configurazioni e modelli di dispositivo. Queste configurazioni e i modelli di dispositivo vengono gestiti e integrati nella pipeline di versione usando le API.

Anche se è possibile automatizzare la creazione di app IoT Central, è necessario creare un'app in ogni ambiente prima di sviluppare la pipeline CI/CD.

Usando l'API REST di Azure IoT Central, è possibile integrare le configurazioni delle app IoT Central nella pipeline di versione.

Questa guida illustra la creazione di una nuova pipeline che aggiorna un'applicazione IoT Central in base ai file di configurazione gestiti in GitHub. Questa guida include istruzioni specifiche per l'integrazione con Azure Pipelines, ma può essere adattata per includere IoT Central in qualsiasi pipeline di versione compilata usando strumenti come Tekton, Jenkins, GitLab o GitHub Actions.

In questa guida viene creata una pipeline che applica solo una configurazione IoT Central a una singola istanza di un'applicazione IoT Central. È necessario integrare i passaggi in una pipeline più grande che distribuisce l'intera soluzione e la promuove dallo sviluppo al controllo di qualità alla preproduzione alla produzione, eseguendo tutti i test necessari lungo il percorso.

Gli script attualmente non trasferiscono le impostazioni seguenti tra istanze di IoT Central: dashboard, visualizzazioni, impostazioni personalizzate nei modelli di dispositivo, piano tariffario, personalizzazioni dell'esperienza utente, immagine dell'applicazione, regole, processi pianificati, processi salvati e gruppi di registrazione.

Gli script attualmente non rimuovono le impostazioni dall'applicazione IoT Central di destinazione che non sono presenti nel file di configurazione.

Prerequisiti

Per completare i passaggi descritti in questa guida, sono necessari i prerequisiti seguenti:

Scaricare il codice di esempio

Per iniziare, creare una copia tramite fork del repository GitHub CI/CD di IoT Central e quindi clonare il fork nel computer locale:

  1. Per eseguire il fork del repository GitHub, aprire il repository GitHub CI/CD di IoT Central e selezionare Fork.

  2. Clonare il fork del repository nel computer locale aprendo una console o una finestra bash ed eseguendo il comando seguente.

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

Creare un'entità servizio

Anche se Azure Pipelines può integrarsi direttamente con un insieme di credenziali delle chiavi, una pipeline richiede un'entità servizio per alcune interazioni dinamiche dell'insieme di credenziali delle chiavi, ad esempio il recupero di segreti per le destinazioni di esportazione dei dati.

Per creare un'entità servizio con ambito nella sottoscrizione:

  1. Eseguire il comando seguente per creare una nuova entità servizio:

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

  2. Prendere nota della password, di appId e del tenant, perché questi valori sono necessari in un secondo momento.

  3. Aggiungere la password dell'entità servizio come segreto denominato SP-Password all'insieme di credenziali delle chiavi di produzione:

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

  4. Concedere all'entità servizio l'autorizzazione per leggere i segreti dall'insieme di credenziali delle chiavi:

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

Generare token API IoT Central

In questa guida la pipeline usa token API per interagire con le applicazioni IoT Central. È anche possibile usare un'entità servizio.

Nota

I token DELL'API IoT Central scadono dopo un anno.

Completare i passaggi seguenti sia per le app di sviluppo che per le app IoT Central di produzione.

  1. Nell'app IoT Central selezionare Autorizzazioni e successivamente token API.

  2. Selezionare Nuovo.

  3. Assegnare un nome al token, specificare l'organizzazione di primo livello nell'app e impostare il ruolo su Amministratore app.

  4. Prendere nota del token API dall'applicazione IoT Central di sviluppo. Verrà usato in un secondo momento quando si esegue lo script IoTC-Config.ps1.

  5. Salvare il token generato dall'applicazione IoT Central di produzione come segreto denominato API-Token nell'insieme di credenziali delle chiavi di produzione:

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

Generare un file di configurazione

Questi passaggi producono un file di configurazione JSON per l'ambiente di sviluppo in base a un'applicazione IoT Central esistente. È anche possibile scaricare tutti i modelli di dispositivo esistenti dall'applicazione.

  1. Eseguire lo script di PowerShell 7 seguente nella copia locale del repository CI/CD di IoT Central:

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

  2. Seguire le istruzioni per accedere all'account Azure.

  3. Dopo l'accesso, lo script visualizza il menu Opzioni di configurazione IoTC. Lo script può generare un file di configurazione da un'applicazione IoT Central esistente e applicare una configurazione a un'altra applicazione IoT Central.

  4. Selezionare l'opzione 1 per generare un file di configurazione.

  5. Immettere i parametri necessari e premere Invio:

    • Token API generato per l'applicazione IoT Central di sviluppo.
    • Sottodominio dell'applicazione IoT Central di sviluppo.
    • Immettere .. \Config\Dev come cartella in cui archiviare il file di configurazione e i modelli di dispositivo.
    • Nome dell'insieme di credenziali delle chiavi di sviluppo.

  6. Lo script crea una cartella denominata Configurazione IoTC nella cartella Config\Dev nella copia locale del repository. Questa cartella contiene un file di configurazione e una cartella denominata Modelli di dispositivo per tutti i modelli di dispositivo nell'applicazione.

Modificare il file di configurazione

Dopo aver creato un file di configurazione che rappresenta le impostazioni per l'istanza dell'applicazione IoT Central di sviluppo, apportare le modifiche necessarie prima di applicare questa configurazione all'istanza dell'applicazione IoT Central di produzione.

  1. Creare una copia della cartella Dev creata in precedenza e chiamarla Production.

  2. Aprire IoTC-Config.json nella cartella Production usando un editor di testo.

  3. Il file include più sezioni. Tuttavia, se l'applicazione non usa un'impostazione specifica, tale sezione viene omessa dal file:

    {
  "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. Se l'applicazione usa caricamenti di file, lo script crea un segreto nell'insieme di credenziali delle chiavi di sviluppo con il valore visualizzato nella proprietà connectionString. Creare un segreto con lo stesso nome nell'insieme di credenziali delle chiavi di produzione che contiene la stringa di connessione per l'account di archiviazione di produzione. Ad esempio:

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

  5. Se l'applicazione usa identità gestite per le destinazioni di esportazione dei dati, non sono presenti segreti da gestire. È tuttavia necessario abilitare l'identità gestita assegnata dal sistema per l'applicazione IoT Central di produzione e concedere le autorizzazioni necessarie per scrivere nella destinazione.

  6. Se l'applicazione usa stringhe di connessione per le destinazioni di esportazione dei dati, aggiungere segreti per le destinazioni all'insieme di credenziali delle chiavi di produzione. Il file di configurazione non contiene segreti effettivi per la destinazione, i segreti vengono archiviati nell'insieme di credenziali delle chiavi.

  7. Aggiornare i segreti nel file di configurazione con il nome del segreto nell'insieme di credenziali delle chiavi.

    Tipo destinazione Proprietà da modificare
    coda del bus di servizio connectionString
    Argomento del bus di servizio connectionString
    Esplora dati di Azure clientSecret
    Archiviazione BLOB di Azure connectionString
    Hub eventi connectionString
    Webhook Nessuna autenticazione N/D

    Ad esempio:

    "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. Per caricare la cartella Configuration nel repository GitHub, eseguire i comandi seguenti dalla cartella IoTC-CICD-howto.

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

Creare una pipeline

  1. Aprire l'organizzazione di Azure DevOps in un Web browser passando a https://dev.azure.com/{your DevOps organization}
  2. Selezionare Nuovo progetto per creare un nuovo progetto.
  3. Assegnare un nome al progetto e una descrizione facoltativa quindi selezionare Crea.
  4. Nella pagina Benvenuto nel progetto selezionare Pipeline e successivamente Crea pipeline.
  5. Selezionare GitHub come percorso del codice.
  6. Selezionare Autorizza AzurePipelines per autorizzare Azure Pipelines ad accedere all'account GitHub.
  7. Nella pagina Selezionare un repository selezionare il fork del repository GitHub CI/CD di IoT Central.
  8. Quando viene richiesto di accedere a GitHub e fornire l'autorizzazione per Azure Pipelines per accedere al repository, selezionare Approva e installa.
  9. Nella pagina Configura la pipeline selezionare Pipeline di base per iniziare. azure-pipelines.yml viene visualizzato per la modifica.

Creare un gruppo di variabili

Un modo semplice per integrare i segreti dell'insieme di credenziali delle chiavi in una pipeline consiste nell'usare gruppi di variabili. Usare un gruppo di variabili per assicurarsi che i segreti corretti siano disponibili per lo script di distribuzione. Per creare un gruppo di variabili:

  1. Selezionare Libreria nella sezione Pipeline del menu a sinistra.

  2. Selezionare + Gruppo di variabili.

  3. Immettere keyvault come nome per il gruppo di variabili.

  4. Abilitare l'interruttore per collegare i segreti da un insieme di credenziali delle chiavi di Azure.

  5. Selezionare la sottoscrizione di Azure e autorizzarla. Selezionare quindi il nome dell'insieme di credenziali delle chiavi di produzione.

  6. Selezionare Aggiungi per iniziare ad aggiungere variabili al gruppo.

  7. Aggiungere i segreti seguenti:

    • Chiave API di IoT Central per l'app di produzione. Questo segreto è stato chiamato API-Token al momento della creazione.
    • Password per l'entità servizio creata in precedenza. Questo segreto è stato chiamato SP-Password al momento della creazione.

  8. Seleziona OK.

  9. Selezionare Salva per salvare il gruppo di variabili.

Configura la pipeline

Configurare ora la pipeline per eseguire il push delle modifiche alla configurazione nell'applicazione IoT Central:

  1. Selezionare Pipeline nella sezione Pipeline del menu a sinistra.

  2. Sostituire il contenuto della pipeline YAML con il codice YAML seguente. La configurazione presuppone che l'insieme di credenziali delle chiavi di produzione contenga:

    • Token API per l'app IoT Central di produzione in un segreto denominato API-Token.
    • Password dell'entità servizio in un segreto denominato SP-Password.

    Sostituire i valori di -AppName e -KeyVault con i valori appropriati per le istanze di produzione.

    Si è preso nota di -AppId e -TenantId quando è stata creata l'entità servizio.

    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. Seleziona Salva ed Esegui.

  4. Il file YAML viene salvato nel repository GitHub, per cui è necessario fornire un messaggio di commit e selezionare nuovamente Salva ed esegui.

La pipeline è in coda. Potrebbero essere necessari alcuni minuti prima dell'esecuzione.

La prima volta che si esegue la pipeline, viene richiesto di concedere le autorizzazioni per la pipeline per accedere alla sottoscrizione e per accedere all'insieme di credenziali delle chiavi. Selezionare Consenti quindi nuovamente Consentire per ogni risorsa.

Al termine del processo della pipeline, accedere all'applicazione IoT Central di produzione e verificare che la configurazione sia stata applicata come previsto.

Promuovere le modifiche dallo sviluppo alla produzione

Ora che è disponibile una pipeline di lavoro, è possibile gestire le istanze di IoT Central direttamente usando le modifiche di configurazione. È possibile caricare nuovi modelli di dispositivo nella cartella Modelli di dispositivo e apportare modifiche direttamente al file di configurazione. Questo approccio consente di gestire la configurazione dell'applicazione IoT Central come qualsiasi altro codice.

Passaggio successivo

Ora che si è appreso come integrare le configurazioni di IoT Central nelle pipeline CI/CD, un passaggio successivo consigliato consiste nell'apprendere come gestire e monitorare le applicazioni IoT Central.