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

Gäller för: IoT Edge 1,1 IoT Edge 1,2

Skapa en Azure IoT Edge automatisk distribution med hjälp av Kommandoradsgränssnittet i Azure för att hantera pågående distributioner för många enheter samtidigt. Automatiska distributioner för IoT Edge ingår i funktionen för automatisk enhetshantering i Azure IoT Hub. Distributioner är dynamiska processer som gör att du kan distribuera flera moduler till flera enheter, spåra modulers status och hälsotillstånd och göra ändringar när det behövs.

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

Förutsättningar

• En IoT-hubb i din Azure-prenumeration.

• En eller flera IoT Edge enheter.

  Om du inte har en IoT Edge enhet kan du skapa en på en virtuell Azure-dator. Följ stegen i någon av dessa snabbstartsartiklar: Skapa en virtuell Linux-enhet eller Skapa en virtuell Windows enhet.

• Azure CLI i din miljö. Din Azure CLI-version 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.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
        }
      }
    }
  }
}

Skiktad distribution

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

Du kan skapa och hantera flerlagersdistributioner med Azure CLI på samma sätt som med andra automatiska distributioner, med några få skillnader. När en flerlagersdistribution 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 flerlagersdistribution lägger du --layered till flaggan i kommandot create.

Den andra skillnaden är att distributionsmanifestet byggs. Standard automatisk distribution måste innehålla moduler för systemkörning utöver användarmoduler, men skiktad distribution kan bara innehålla användarmoduler. Flerlagersdistributioner behöver också en automatisk standarddistribution på en enhet för att tillhandahålla nödvändiga komponenter för varje IoT Edge enhet, t.ex. systemkörningsmodulerna.

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

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

I föregående exempel visades inställningen för distribution i flera properties.desired lager för en modul. Om den här nivådistributionen riktas mot en enhet där samma modul redan har tillämpats, 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. Ett 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
}

Sammanfattningsvis skapar du en skiktad distribution:

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

Mer information om hur du konfigurerar modultvillingarna i lagerdistributioner finns i Skiktad distribution.

Identifiera enheter med hjälp av taggar

Innan du kan skapa en distribution måste du kunna ange vilka enheter som 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å ett sätt som är logiskt för din lösning. Om du till exempel hanterar ett campus med smarta byggnader kan du lägga till följande taggar till en enhet:

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

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

Skapa en distribution

Du distribuerar moduler till målenheterna 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 flaggan --layered för att skapa en skiktad distribution.

Create-kommandot för distribution tar följande parametrar:

• --layered. En valfri flagga för att identifiera distributionen som en skiktad distribution.
• --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 JSON-distributionsmanifestet. 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 av az account set -s [subscription name] kommandot .
• --labels. Namn/värde-par som beskriver och hjälper dig att spåra dina distributioner. Etiketterna använder 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 vara mål för den här distributionen. Villkoret baseras på taggar för enhetstvillingar eller rapporterade egenskaper för enhetstvillingen, och det bör matcha uttrycksformatet. Exempel: tags.environment='test' and properties.reported.devicemodel='4000x'.
• --priority. Ett positivt heltal. Om två eller flera distributioner riktas mot samma enhet gäller distributionen med det högsta numeriska värdet för prioritet.
• --metrics. Mått som frågar de rapporterade edgeHub egenskaperna 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.

Ä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 uppfyller det gamla målvillkoret men uppfyller det nya målvillkoret, och den här distributionen är den högsta prioriteten för enheten, tillämpas den här distributionen på enheten.
• Om en enhet som kör den här distributionen inte längre uppfyller målvillkoret avinstallerar den här distributionen och får distributionen med näst högsta prioritet.
• Om en enhet som 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 deras 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 avinstalleras den här distributionen och den nya.

Du kan inte uppdatera innehållet i en distribution, som innehåller de moduler och vägar som definierats 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']

Distributionsuppdateringskommandot använder 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.