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

Gäller för: IoT Edge 1.5

Använd Azure CLI för att skapa en automatisk distribution av Azure IoT Edge och hantera distributioner för många enheter samtidigt. Automatiska distributioner för IoT Edge är en del av enhetshanteringsfunktionen i Azure IoT Hub. Med distributioner kan du distribuera flera moduler till flera enheter, spåra status och hälsotillstånd för moduler och göra ändringar när det behövs.

I den här artikeln konfigurerar du Azure CLI och IoT-tillägget. Sedan distribuerar du moduler till en uppsättning IoT Edge-enheter och övervakar förloppet med hjälp av CLI-kommandon.

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. Använd az --version för att kontrollera. 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 de önskade egenskaperna 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 kommer att använda filsökvägen i nästa avsnitt när du kör kommandot för att konfigurera 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
        }
      }
    }
  }
}

Distribution i lager

Lagerimplementeringar är en typ av automatisk implementering som du kan stapla 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.

Du kan skapa och hantera distributioner i flera lager med Azure CLI som vilken automatisk distribution som helst, med bara några få skillnader. När du har skapat en distribution i flera lager 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 är hur du skapar distributionsmanifestet. Standardautomatiska distributioner måste innehålla systemkörningsmoduler och alla användarmoduler. Skiktade distributioner kan 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
        }
      }
    }
  }
}

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

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

Du kan också uttrycka samma sak med följande syntax:

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

Så här 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 skapar en distribution måste du 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

Distribuera moduler till målenheter genom att skapa en distribution som har distributionsmanifestet och andra parametrar.

Kör 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 <priority>

--layered Lägg till flaggan för att skapa en distribution i flera lager.

Kommandot az iot edge deployment create använder följande parametrar:

• --layered: Valfri flagga som identifierar distributionen som en distribution i lager.
• --deployment-id: Namnet på distributionen som skapades i IoT-hubben. Använd ett unikt namn med upp till 128 små bokstäver. 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å IoT-hubben där distributionen skapas. Hubben måste finnas i den aktuella prenumerationen. Ändra din aktuella prenumeration genom att köra az account set -s <subscription-name>.
• --labels: Namn/värde-par som beskriver och hjälper dig att spåra distributioner. Etiketter använder JSON-formatering för namn och värden. Exempel: {"HostPlatform":"Linux", "Version":"3.0.1"}.
• --target-condition: Villkor som avgör vilka enheter som är mål för 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 du inte anger målvillkoret tillämpas inte distributionen på några enheter.
• --priority: Positivt heltal. Om två eller flera distributioner riktar sig mot samma enhet gäller distributionen med högsta prioritet.
• --metrics: Mått som frågar de edgeHub rapporterade egenskaperna för att spåra status för en distribution. Metrik använder 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 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 ändringar:

• 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 någon annan distribution 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 avinstalleras distributionen och den nya tas emot.

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 använder följande parametrar:

• --deployment-id: Namnet på distributionen i IoT-hubben.
• --hub-name: Namnet på den IoT-hubb där distributionen finns. Hubben måste finnas i den aktuella prenumerationen. Om du vill växla till en annan prenumeration kör du az account set -s <subscription-name>.
• --set: Ändra en egenskap i distributionen. Du kan ändra 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 använder enheterna sin näst högsta prioritetsdistribution. Om enheterna inte uppfyller målvillkoret för en annan distribution tas inte modulerna bort när du tar bort distributionen.

Kör 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 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].

Nästa steg

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