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

Si applica a: IoT Edge 1.5 IoT Edge 1.4

Importante

IoT Edge 1.5 LTS e IoT Edge 1.4 LTS sono versioni supportate. IoT Edge 1.4 LTS raggiungerà la fine del servizio il 12 novembre 2024. 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 rientrano nella funzionalità di gestione dei dispositivi dell'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 vengono configurate l'interfaccia della riga di comando di Azure e l'estensione IoT. Vengono quindi fornite informazioni su come distribuire moduli in un set di dispositivi IoT Edge e monitorare i progressi 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 si dispone di un dispositivo IoT Edge configurato, è possibile crearne uno in una macchina virtuale di Azure. Seguire la procedura descritta in uno di questi argomenti 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 tramite 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.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota

Questo manifesto della distribuzione di esempio usa la versione dello schema 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 dei modulo e la definizione della priorità delle 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. Una volta creata una distribuzione a livelli, l'interfaccia della riga di comando di Azure funziona per le distribuzioni a livelli come per qualsiasi altra distribuzione. Per creare una distribuzione a livelli, aggiungere il flag --layered al comando Crea.

La seconda differenza consiste nella costruzione del manifesto della distribuzione. Sebbene la distribuzione automatica standard debba contenere i moduli di runtime di sistema oltre a eventuali moduli utente, le distribuzioni a livelli possono contenere solo moduli utente. Le distribuzioni a livelli richiedono inoltre una distribuzione automatica standard in un dispositivo, per fornire i componenti necessari di ogni dispositivo IoT Edge, come 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.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota

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

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

L'esempio precedente illustra l'impostazione properties.desired di una distribuzione a 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, anziché sovrascrivere, le proprietà desiderate, è 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 livelli devono includere un oggetto edgeAgent per essere considerate valide. Anche se una distribuzione a livelli aggiorna solo le proprietà del modulo, includere un oggetto vuoto. Ad esempio: "$edgeAgent":{}. Una distribuzione a livelli con un oggetto edgeAgent vuoto verrà visualizzata come di destinazione nel modulo gemello edgeAgent, non come applicata.

In sintesi, per creare una distribuzione a livelli:

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

Per altre informazioni sulla configurazione di moduli gemelli nelle distribuzioni a livelli, vedere Distribuzioni a livelli.

Identificare i dispositivi tramite 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 tramite 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

Per distribuire moduli nei dispositivi di destinazione, si crea una distribuzione costituita dall'apposito manifesto 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 di creazione per la distribuzione accetta i parametri seguenti:

• --layered. Flag facoltativo per identificare la distribuzione come distribuzione a livelli.
• --deployment-id. Nome della distribuzione che verrà creata nell'hub IoT. Assegnare alla distribuzione un nome univoco contenente al massimo 128 lettere minuscole. Evitare gli spazi e i seguenti caratteri non validi: & ^ [ ] { } \ | " < > /. Questo parametro è obbligatorio.
• --content. Percorso file del manifesto della distribuzione JSON. 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 con il comando az account set -s [subscription name].
• --labels. Coppie nome-valore che descrivono la distribuzione 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 i dispositivi di destinazione di questa distribuzione. La condizione è basata sui tag o sulle proprietà segnalate dei dispositivi gemelli e deve corrispondere al formato di 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 hanno lo stesso dispositivo di destinazione, verrà applicata quella con il valore di priorità più alto.
• --metrics. Metriche che eseguono query sulle proprietà segnalate da edgeHub per tenere traccia dello stato di una distribuzione. Le metriche accettano input JSON o un percorso file. Ad esempio: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

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

Nota

Quando viene creata una nuova distribuzione di IoT Edge, a volte possono essere necessari fino a 5 minuti prima che l'hub IoT elabori la nuova configurazione e propaghi 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 che esegue la distribuzione non soddisfa più la condizione di destinazione, disinstalla questa distribuzione e riceve la distribuzione successiva nell'ordine di priorità.
• 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. Quando soddisfa la condizione di destinazione di qualsiasi altra distribuzione, il dispositivo disinstalla questa distribuzione e riceve quella nuova.

Non è possibile aggiornare il contenuto di una distribuzione, che include i moduli e le route definiti nel manifesto della distribuzione. Per aggiornare il contenuto di una distribuzione, creare una nuova distribuzione destinata agli stessi dispositivi con una 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 si trova la distribuzione. L'hub deve trovarsi nella sottoscrizione corrente. Per passare alla sottoscrizione desiderata, usare il comando az account set -s [subscription name].
• --set. Permette di aggiornare una proprietà nella distribuzione. È possibile aggiornare le proprietà seguenti:
  • targetCondition (ad esempio, targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add. Permette di aggiungere una nuova proprietà alla distribuzione, incluse condizioni di destinazione o etichette.
• --remove. Permette di rimuovere una proprietà esistente, incluse condizioni di destinazione o etichette.

Eliminare una distribuzione

Quando si elimina una distribuzione, tutti i dispositivi ricevono la distribuzione successiva nell'ordine di priorità. Se i dispositivi non soddisfano la condizione di destinazione di qualsiasi altra distribuzione, i moduli non vengono rimossi in seguito all'eliminazione della distribuzione.

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 comando deployment delete accetta i parametri seguenti:

• --deployment-id. Nome della distribuzione esistente nell'hub IoT.
• --hub-name. Nome dell'hub IoT in cui si trova la distribuzione. L'hub deve trovarsi nella sottoscrizione corrente. Per passare alla sottoscrizione desiderata, usare il comando az account set -s [subscription name].

Passaggi successivi

Leggere altre informazioni sulla distribuzione di moduli nei dispositivi IoT Edge.