Distribuire e monitorare i moduli IoT Edge su larga scala usando l'interfaccia della riga di comando di Azure

Si applica a: IoT Edge 1.4

Importante

IoT Edge 1.4 è la versione supportata. Se si usa una versione precedente, vedere Aggiornare IoT Edge.

Creare una distribuzione automatica di Azure IoT Edge usando l'interfaccia della riga di comando di Azure per gestire le distribuzioni in corso per più dispositivi contemporaneamente. Le distribuzioni automatiche per IoT Edge fanno parte della funzionalità di gestione dei dispositivi di hub IoT di Azure. Le distribuzioni sono processi dinamici che consentono di distribuire più moduli in più dispositivi, di tenere traccia dello stato e dell'integrità dei moduli, nonché di apportare modifiche all'occorrenza.

In questo articolo viene configurata l'interfaccia della riga di comando di Azure e l'estensione IoT. Si apprenderà quindi come distribuire moduli in un set di dispositivi IoT Edge e monitorare lo stato di avanzamento usando i comandi disponibili dell'interfaccia della riga di comando.

Prerequisiti

• Un hub IoT nella sottoscrizione di Azure.

• Uno o più dispositivi IoT Edge.

  Se non è configurato un dispositivo IoT Edge, è possibile crearne uno in una macchina virtuale di Azure. Seguire la procedura descritta in uno di questi articoli di avvio rapido: Creare un dispositivo Linux virtuale o Creare un dispositivo Windows virtuale.

• Interfaccia della riga di comando di Azure nell'ambiente in uso. La versione dell'interfaccia della riga di comando di Azure deve essere 2.0.70 o successiva. Usare il comando az --version per verificare. Questa versione supporta i comandi dell'estensione az e introduce il framework dei comandi Knack.

• Estensione IoT per l'interfaccia della riga di comando di Azure.

Configurare un manifesto della distribuzione

Un manifesto della distribuzione è un documento JSON contenente la descrizione dei moduli da distribuire, dei flussi di dati esistenti tra i moduli e delle proprietà desiderate dei moduli gemelli. Per altre informazioni, vedere Informazioni su come distribuire moduli e definire route in IoT Edge.

Per distribuire i moduli usando l'interfaccia della riga di comando di Azure, salvare il manifesto della distribuzione in locale come file con estensione txt. Il percorso del file verrà usato nella sezione successiva quando si eseguirà il comando per applicare la configurazione al dispositivo.

Di seguito è riportato un esempio di manifesto della distribuzione di base con un solo modulo:

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.1",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.1",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.1",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.0",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota

Questo manifesto della distribuzione di esempio usa lo schema versione 1.1 per l'agente e l'hub di IoT Edge. La versione dello schema 1.1 è stata rilasciata insieme a IoT Edge versione 1.0.10. Abilita funzionalità come l'ordine di avvio del modulo e la definizione delle priorità di route.

Distribuzione a livelli

Le distribuzioni a livelli sono un tipo di distribuzioni automatiche che possono essere sovrapposte l'una sull'altra. Per altre informazioni sulle distribuzioni a livelli, vedere Informazioni sulle distribuzioni automatiche di IoT Edge per singoli dispositivi o su vasta scala.

Le distribuzioni a livelli possono essere create e gestite con l'interfaccia della riga di comando di Azure come qualsiasi distribuzione automatica, con alcune differenze. Dopo aver creato una distribuzione a più livelli, l'interfaccia della riga di comando di Azure funziona per le distribuzioni a più livelli come per qualsiasi distribuzione. Per creare una distribuzione a livelli, aggiungere il flag --layered al comando Crea.

La seconda differenza consiste nella costruzione del manifesto della distribuzione. Mentre la distribuzione automatica standard deve contenere i moduli di runtime di sistema oltre a qualsiasi modulo utente, le distribuzioni a più livelli possono contenere solo moduli utente. Le distribuzioni a più livelli richiedono anche una distribuzione automatica standard in un dispositivo per fornire i componenti necessari di ogni dispositivo IoT Edge, ad esempio i moduli di runtime di sistema.

Di seguito è riportato un esempio di manifesto della distribuzione a livelli di base con un solo modulo:

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.0"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota

Questo manifesto della distribuzione a più livelli ha un formato leggermente diverso rispetto a un manifesto della distribuzione standard. Le proprietà desiderate dei moduli di runtime vengono compresse e usano la notazione punto. Questa formattazione è necessaria per il portale di Azure per riconoscere una distribuzione a più livelli. Ad esempio:

• properties.desired.modules.<module_name>
• properties.desired.routes.<route_name>

Nell'esempio precedente è stata illustrata l'impostazione properties.desired di distribuzione a più livelli per un modulo. Se questa distribuzione a livelli è destinata a un dispositivo in cui è già stato applicato lo stesso modulo, eventuali proprietà desiderate esistenti verranno sovrascritte. Per aggiornare le proprietà desiderate anziché sovrascriverle, è possibile definire una nuova sottosezione. Ad esempio:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

Lo stesso può essere espresso anche con:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

Nota

Attualmente, tutte le distribuzioni a più livelli devono includere un edgeAgent oggetto da considerare valido. Anche se una distribuzione a più livelli aggiorna solo le proprietà del modulo, includere un oggetto vuoto. Ad esempio: "$edgeAgent":{}. Una distribuzione a più livelli con un oggetto vuoto edgeAgent verrà visualizzata come destinazione nel edgeAgent modulo gemello, non applicata.

In sintesi, per creare una distribuzione a più livelli:

• Aggiungere il --layered flag al comando create dell'interfaccia della riga di comando di Azure.
• Non includere moduli di sistema.
• Usare la notazione punto completo in $edgeAgent e $edgeHub.

Per altre informazioni sulla configurazione dei moduli gemelli nelle distribuzioni a più livelli, vedere Distribuzione a più livelli.

Identificare i dispositivi usando i tag

Prima di poter creare una distribuzione, è necessario essere in grado di specificare i dispositivi a cui la si vuole applicare. Azure IoT Edge identifica i dispositivi usando i tag nel dispositivo gemello.

Ogni dispositivo può avere più tag, che è possibile definire in qualsiasi modo risulti appropriato per una soluzione specifica. Ad esempio, il responsabile di un complesso di edifici intelligenti potrebbe aggiungere a un dispositivo i tag seguenti:

"tags":{
  "location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

Per altre informazioni sui dispositivi gemelli e i tag, vedere Comprendere e usare dispositivi gemelli nell'hub IoT.

Creare una distribuzione

I moduli vengono distribuiti nei dispositivi di destinazione creando una distribuzione costituita dal manifesto della distribuzione e da altri parametri.

Per creare una distribuzione, usare il comando az iot edge deployment create:

az iot edge deployment create --deployment-id [deployment id] --hub-name [hub name] --content [file path] --labels "[labels]" --target-condition "[target query]" --priority [int]

Per creare una distribuzione a livelli, usare lo stesso comando con il flag --layered.

Il comando create per la distribuzione accetta i parametri seguenti:

• - a più livelli. Flag facoltativo per identificare la distribuzione come distribuzione a più livelli.
• --deployment-id. Nome della distribuzione che verrà creata nell'hub IoT. Assegnare alla distribuzione un nome univoco con un massimo di 128 lettere minuscole. Evitare gli spazi e i seguenti caratteri non validi: & ^ [ ] { } \ | " < > /. Questo parametro è obbligatorio.
• --content. Percorso del file nel file JSON del manifesto della distribuzione. Questo parametro è obbligatorio.
• --hub-name. Nome dell'hub IoT in cui verrà creata la distribuzione. L'hub deve trovarsi nella sottoscrizione corrente. Modificare la sottoscrizione corrente usando il az account set -s [subscription name] comando .
• --labels. Coppie nome/valore che descrivono e aiutano a tenere traccia delle distribuzioni. Le etichette richiedono la formattazione JSON per nomi e valori. Ad esempio: {"HostPlatform":"Linux", "Version:"3.0.1"}.
• --target-condition. Condizione che determina quali dispositivi saranno destinati a questa distribuzione. La condizione si basa sui tag del dispositivo gemello o sulle proprietà segnalate del dispositivo gemello e deve corrispondere al formato dell'espressione. Ad esempio: tags.environment='test' and properties.reported.devicemodel='4000x'. Se la condizione di destinazione non viene specificata, la distribuzione non viene applicata ad alcun dispositivo.
• --priority. Numero intero positivo. Se due o più distribuzioni sono destinate allo stesso dispositivo, verrà applicata la distribuzione con il valore numerico più alto per la priorità.
• --metrics. Metriche che eseguono query sulle edgeHub proprietà segnalate per tenere traccia dello stato di una distribuzione. Le metriche accettano l'input JSON o un percorso di file. Ad esempio: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

Per monitorare una distribuzione usando l'interfaccia della riga di comando di Azure, vedere Monitorare le distribuzioni di IoT Edge.

Nota

Quando viene creata una nuova distribuzione di IoT Edge, a volte possono essere necessari fino a 5 minuti prima che il hub IoT elabori la nuova configurazione e propaga le nuove proprietà desiderate ai dispositivi di destinazione.

Modificare una distribuzione

Quando si modifica una distribuzione, le modifiche vengono replicate immediatamente in tutti i dispositivi di destinazione.

Se si aggiorna la condizione di destinazione, vengono eseguiti gli aggiornamenti seguenti:

• Se un dispositivo non soddisfa la condizione di destinazione precedente, ma soddisfa la nuova condizione di destinazione e questa distribuzione ha la priorità più alta per il dispositivo, la distribuzione viene applicata al dispositivo.
• Se un dispositivo attualmente in esecuzione questa distribuzione non soddisfa più la condizione di destinazione, disinstalla questa distribuzione e assume la distribuzione con priorità più alta successiva.
• Se un dispositivo che esegue la distribuzione non soddisfa più la condizione di destinazione e non soddisfa la condizione di destinazione di tutte le altre distribuzioni, nel dispositivo non viene apportata alcuna modifica. Il dispositivo continua a eseguire i moduli correnti nello stato corrente, ma non è più gestito come parte di questa distribuzione. Dopo che il dispositivo soddisfa la condizione di destinazione di qualsiasi altra distribuzione, disinstalla questa distribuzione e assume quella nuova.

Non è possibile aggiornare il contenuto di una distribuzione, che include i moduli e le route definiti nel manifesto della distribuzione. Se si vuole aggiornare il contenuto di una distribuzione, creare una nuova distribuzione destinata agli stessi dispositivi con priorità più alta. È possibile modificare determinate proprietà di un modulo esistente, tra cui la condizione di destinazione, le etichette, le metriche e la priorità.

Per aggiornare una distribuzione, usare il comando az iot edge deployment update:

az iot edge deployment update --deployment-id [deployment id] --hub-name [hub name] --set [property1.property2='value']

Il comando Aggiorna distribuzione accetta i parametri seguenti:

• --deployment-id. Nome della distribuzione esistente nell'hub IoT.
• --hub-name. Nome dell'hub IoT in cui è presente la distribuzione. L'hub deve trovarsi nella sottoscrizione corrente. Passare alla sottoscrizione desiderata usando il comando az account set -s [subscription name].
• --set. Aggiornare una proprietà nella distribuzione. È possibile aggiornare le proprietà seguenti:
  • targetCondition (ad esempio, targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add. Aggiungere una nuova proprietà alla distribuzione, incluse le condizioni o le etichette di destinazione.
• --remove. Rimuovere una proprietà esistente, incluse le condizioni o le etichette di destinazione.

Eliminare una distribuzione

Quando si elimina una distribuzione, tutti i dispositivi assumono la distribuzione con priorità più alta successiva. Se i dispositivi non soddisfano la condizione di destinazione di altre distribuzioni, i moduli non vengono rimossi quando la distribuzione viene eliminata.

Per eliminare una distribuzione, usare il comando az iot edge deployment delete:

az iot edge deployment delete --deployment-id [deployment id] --hub-name [hub name]

Il deployment delete comando accetta i parametri seguenti:

• --deployment-id. Nome della distribuzione esistente nell'hub IoT.
• --hub-name. Nome dell'hub IoT in cui è presente la distribuzione. L'hub deve trovarsi nella sottoscrizione corrente. Passare alla sottoscrizione desiderata usando il comando az account set -s [subscription name].

Passaggi successivi

Altre informazioni sulla distribuzione di moduli nei dispositivi IoT Edge.