Distribuera och övervaka IoT Edge-moduler i stor skala med hjälp av Azure CLI

Gäller för: IoT Edge 1.5 IoT Edge 1.4

Viktigt!

IoT Edge 1.5 LTS och IoT Edge 1.4 LTS stöds. IoT Edge 1.4 LTS upphör den 12 november 2024. Om du har en tidigare version läser du Uppdatera IoT Edge.

Skapa en automatisk Distribution av Azure IoT Edge med hjälp av Azure CLI för att hantera pågående distributioner för många enheter samtidigt. Automatiska distributioner för IoT Edge är en del av enhetshanteringsfunktionen i Azure IoT Hub. Distributioner är dynamiska processer som gör att du kan distribuera flera moduler till flera enheter, spåra status och hälsa för modulerna och göra ändringar vid behov.

I den här artikeln konfigurerar du Azure CLI och IoT-tillägget. Sedan får du lära dig hur du distribuerar moduler till en uppsättning IoT Edge-enheter och övervakar förloppet med hjälp av de tillgängliga CLI-kommandona.

Förutsättningar

• En IoT-hubb i din Azure-prenumeration.

• En eller flera IoT Edge-enheter.

  Om du inte har konfigurerat en IoT Edge-enhet kan du skapa en på en virtuell Azure-dator. Följ stegen i någon av de här snabbstartsartiklarna: Skapa en virtuell Linux-enhet eller Skapa en virtuell Windows-enhet.

• Azure CLI i din miljö. Azure CLI-versionen måste vara 2.0.70 eller senare. Validera med az --version. Den här versionen har stöd för az-tilläggskommandon och introducerar kommandoramverket Knack.

• IoT-tillägget för Azure CLI.

Konfigurera ett distributionsmanifest

Ett distributionsmanifest är ett JSON-dokument som beskriver vilka moduler som ska distribueras, hur data flödar mellan modulerna och önskade egenskaper för modultvillingarna. Mer information finns i Lär dig hur du distribuerar moduler och etablerar vägar i IoT Edge.

Om du vill distribuera moduler med hjälp av Azure CLI sparar du distributionsmanifestet lokalt som en .txt fil. Du använder filsökvägen i nästa avsnitt när du kör kommandot för att tillämpa konfigurationen på enheten.

Här är ett grundläggande distributionsmanifest med en modul som exempel:

{
  "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
        }
      }
    }
  }
}

Kommentar

Det här exempeldistributionsmanifestet använder schemaversion 1.1 för IoT Edge-agenten och hubben. Schemaversion 1.1 släpptes tillsammans med IoT Edge version 1.0.10. Det möjliggör funktioner som startordning för moduler och vägprioritering.

Distribution i lager

Lagerdistributioner är en typ av automatisk distribution som kan staplas ovanpå varandra. Mer information om distributioner i flera lager finns i Förstå automatiska IoT Edge-distributioner för enskilda enheter eller i stor skala.

Distributioner i flera lager kan skapas och hanteras med Azure CLI som alla automatiska distributioner, med bara några få skillnader. När en distribution i flera lager har skapats fungerar Azure CLI för distributioner i flera lager på samma sätt som för alla distributioner. Om du vill skapa en distribution i flera lager lägger du till --layered flaggan i kommandot create.

Den andra skillnaden gäller konstruktionen av distributionsmanifestet. Medan automatisk standarddistribution måste innehålla systemkörningsmoduler utöver alla användarmoduler, kan distributioner i lager endast innehålla användarmoduler. Lagerdistributioner behöver också en standardbaserad automatisk distribution på en enhet för att tillhandahålla nödvändiga komponenter för varje IoT Edge-enhet, till exempel systemkörningsmodulerna.

Här är ett grundläggande lagerdistributionsmanifest med en modul som exempel:

{
  "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
        }
      }
    }
  }
}

Kommentar

Det här distributionsmanifestet i lager har ett något annorlunda format än ett standarddistributionsmanifest. De önskade egenskaperna för runtime-modulerna komprimeras och använder punkt notation. Den här formateringen krävs för att Azure-portalen ska kunna identifiera en distribution i flera lager. Till exempel:

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

I föregående exempel visades skiktad distributionsinställning properties.desired för en modul. Om den här lagerdistributionen riktade sig mot en enhet där samma modul redan tillämpades skulle den skriva över alla befintliga önskade egenskaper. Om du vill uppdatera önskade egenskaper i stället för att skriva över dem kan du definiera ett nytt underavsnitt. Till exempel:

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

Samma sak kan också uttryckas med:

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

Kommentar

För närvarande måste alla lagerdistributioner innehålla ett edgeAgent objekt som ska anses vara giltigt. Även om en lagerbaserad distribution endast uppdaterar modulegenskaperna inkluderar du ett tomt objekt. Exempel: "$edgeAgent":{}. En lagerdistribution med ett tomt edgeAgent objekt visas som mål i modultvillingen edgeAgent , inte tillämpad.

Sammanfattningsvis skapar du en distribution i flera lager:

• --layered Lägg till flaggan i azure CLI create-kommandot.
• Inkludera inte systemmoduler.
• Använd fullständig punkt notation under $edgeAgent och $edgeHub.

Mer information om hur du konfigurerar modultvillingar i lagerdistributioner finns i Lagerdistribution.

Identifiera enheter med hjälp av taggar

Innan du kan skapa en distribution måste du kunna ange vilka enheter du vill påverka. Azure IoT Edge identifierar enheter med hjälp av taggar i enhetstvillingen.

Varje enhet kan ha flera taggar som du definierar på alla sätt som passar din lösning. Om du till exempel hanterar ett campus med smarta byggnader kan du lägga till följande taggar på en enhet:

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

Mer information om enhetstvillingar och taggar finns i Förstå och använda enhetstvillingar i IoT Hub.

Skapa en distribution

Du distribuerar moduler till dina målenheter genom att skapa en distribution som består av distributionsmanifestet och andra parametrar.

Använd kommandot az iot edge deployment create för att skapa en distribution:

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

Använd samma kommando med --layered flaggan för att skapa en distribution i flera lager.

Kommandot create för distribution tar följande parametrar:

• --lager. En valfri flagga för att identifiera distributionen som en distribution i flera lager.
• --deployment-id. Namnet på distributionen som ska skapas i IoT-hubben. Ge distributionen ett unikt namn som är upp till 128 gemener. Undvik blanksteg och följande ogiltiga tecken: & ^ [ ] { } \ | " < > /. Den här parametern krävs.
• --content. Filsökväg till distributionsmanifestet JSON. Den här parametern krävs.
• --hub-name. Namnet på den IoT-hubb där distributionen ska skapas. Hubben måste finnas i den aktuella prenumerationen. Ändra din aktuella prenumeration med hjälp az account set -s [subscription name] av kommandot .
• --etiketter. Namn/värde-par som beskriver och hjälper dig att spåra dina distributioner. Etiketter tar JSON-formatering för namn och värden. Exempel: {"HostPlatform":"Linux", "Version:"3.0.1"}.
• --target-condition. Villkoret som avgör vilka enheter som ska riktas mot den här distributionen. Villkoret baseras på enhetstvillingtaggar eller rapporterade egenskaper för enhetstvillingar och ska matcha uttrycksformatet. Exempel: tags.environment='test' and properties.reported.devicemodel='4000x'. Om målvillkoret inte har angetts tillämpas inte distributionen på några enheter.
• --prioritet. Ett positivt heltal. Om två eller flera distributioner riktas mot samma enhet tillämpas distributionen med det högsta numeriska värdet för prioritet.
• --metrics. Mått som kör frågor mot rapporterade edgeHub egenskaper för att spåra status för en distribution. Mått tar JSON-indata eller en filsökväg. Exempel: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

Information om hur du övervakar en distribution med hjälp av Azure CLI finns i Övervaka IoT Edge-distributioner.

Kommentar

När en ny IoT Edge-distribution skapas kan det ibland ta upp till 5 minuter för IoT Hub att bearbeta den nya konfigurationen och sprida de nya önskade egenskaperna till målenheterna.

Ändra en distribution

När du ändrar en distribution replikeras ändringarna omedelbart till alla målenheter.

Om du uppdaterar målvillkoret sker följande uppdateringar:

• Om en enhet inte uppfyllde det gamla målvillkoret men uppfyller det nya målvillkoret, och den här distributionen är den högsta prioriteten för den enheten, tillämpas den här distributionen på enheten.
• Om en enhet som för närvarande kör den här distributionen inte längre uppfyller målvillkoret avinstallerar den distributionen och tar på sig den näst högsta prioritetsdistributionen.
• Om en enhet som för närvarande kör den här distributionen inte längre uppfyller målvillkoret och inte uppfyller målvillkoret för andra distributioner sker ingen ändring på enheten. Enheten fortsätter att köra sina aktuella moduler i sitt aktuella tillstånd men hanteras inte längre som en del av den här distributionen. När enheten uppfyller målvillkoret för en annan distribution avinstallerar den den här distributionen och tar på sig den nya.

Du kan inte uppdatera innehållet i en distribution, som innehåller de moduler och vägar som definieras i distributionsmanifestet. Om du vill uppdatera innehållet i en distribution skapar du en ny distribution som riktar sig till samma enheter med högre prioritet. Du kan ändra vissa egenskaper för en befintlig modul, inklusive målvillkor, etiketter, mått och prioritet.

Använd kommandot az iot edge deployment update för att uppdatera en distribution:

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

Kommandot för distributionsuppdatering tar följande parametrar:

• --deployment-id. Namnet på distributionen som finns i IoT-hubben.
• --hub-name. Namnet på den IoT-hubb där distributionen finns. Hubben måste finnas i den aktuella prenumerationen. Växla till önskad prenumeration med hjälp av kommandot az account set -s [subscription name].
• --set. Uppdatera en egenskap i distributionen. Du kan uppdatera följande egenskaper:
  • targetCondition (till exempel targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add. Lägg till en ny egenskap i distributionen, inklusive målvillkor eller etiketter.
• --remove. Ta bort en befintlig egenskap, inklusive målvillkor eller etiketter.

Ta bort en distribution

När du tar bort en distribution får alla enheter sin näst högsta prioritetsdistribution. Om dina enheter inte uppfyller målvillkoret för någon annan distribution tas modulerna inte bort när distributionen tas bort.

Använd kommandot az iot edge deployment delete för att ta bort en distribution:

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

Kommandot deployment delete tar följande parametrar:

• --deployment-id. Namnet på distributionen som finns i IoT-hubben.
• --hub-name. Namnet på den IoT-hubb där distributionen finns. Hubben måste finnas i den aktuella prenumerationen. Växla till önskad prenumeration med hjälp av kommandot az account set -s [subscription name].

Nästa steg

Läs mer om att distribuera moduler till IoT Edge-enheter.