IoT Edge-modules op schaal implementeren en bewaken met behulp van de Azure CLI

Van toepassing op: IoT Edge 1.5 IoT Edge 1.4

Belangrijk

IoT Edge 1.5 LTS en IoT Edge 1.4 LTS worden ondersteund releases. IoT Edge 1.4 LTS eindigt op 12 november 2024. Raadpleeg IoT Edge bijwerken als u een eerdere versie hebt.

Maak een automatische implementatie van Azure IoT Edge met behulp van de Azure CLI om doorlopende implementaties voor veel apparaten tegelijk te beheren. Automatische implementaties voor IoT Edge maken deel uit van de functie voor apparaatbeheer van Azure IoT Hub. Implementaties zijn dynamische processen waarmee u meerdere modules op meerdere apparaten kunt implementeren, de status en status van de modules kunt bijhouden en zo nodig wijzigingen kunt aanbrengen.

In dit artikel stelt u de Azure CLI en de IoT-extensie in. Vervolgens leert u hoe u modules implementeert op een set IoT Edge-apparaten en hoe u de voortgang bewaakt met behulp van de beschikbare CLI-opdrachten.

Vereisten

• Een IoT-hub in uw Azure-abonnement.

• Een of meer IoT Edge-apparaten.

  Als u geen IoT Edge-apparaat hebt ingesteld, kunt u er een maken in een virtuele Azure-machine. Volg de stappen in een van deze quickstart-artikelen: Een virtueel Linux-apparaat maken of een virtueel Windows-apparaat maken.

• De Azure CLI in uw omgeving. Uw Azure CLI-versie moet 2.0.70 of hoger zijn. Gebruik az --version om de versie te valideren. In deze versie worden az-extensie-opdrachten ondersteund en is voor het eerst het Knack-opdrachtframework opgenomen.

• De IoT-extensie voor Azure CLI.

Een implementatiemanifest configureren

Een implementatiemanifest is een JSON-document waarin wordt beschreven welke modules moeten worden geïmplementeerd, hoe gegevens stromen tussen de modules en de gewenste eigenschappen van de moduledubbels. Zie Meer informatie over het implementeren van modules en het tot stand brengen van routes in IoT Edge.

Als u modules wilt implementeren met behulp van de Azure CLI, slaat u het implementatiemanifest lokaal op als een .txt-bestand. U gebruikt het bestandspad in de volgende sectie wanneer u de opdracht uitvoert om de configuratie op uw apparaat toe te passen.

Hier volgt een basisimplementatiemanifest met één module als voorbeeld:

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

Notitie

In dit voorbeeldimplementatiemanifest wordt schemaversie 1.1 gebruikt voor de IoT Edge-agent en -hub. Schemaversie 1.1 is uitgebracht samen met IoT Edge versie 1.0.10. Het maakt functies mogelijk, zoals opstartvolgorde van modules en prioriteitstelling van routes.

Gelaagde implementatie

Gelaagde implementaties zijn een type automatische implementatie dat bovenop elkaar kan worden gestapeld. Zie Informatie over automatische implementaties van IoT Edge voor afzonderlijke apparaten of op schaal voor meer informatie over gelaagde implementaties.

Gelaagde implementaties kunnen worden gemaakt en beheerd met de Azure CLI, net als elke automatische implementatie, met slechts enkele verschillen. Nadat een gelaagde implementatie is gemaakt, werkt de Azure CLI voor gelaagde implementaties hetzelfde als voor elke implementatie. Als u een gelaagde implementatie wilt maken, voegt u de --layered vlag toe aan de opdracht maken.

Het tweede verschil is in de constructie van het implementatiemanifest. Terwijl de standaard automatische implementatie de systeemruntimemodules moet bevatten naast alle gebruikersmodules, kunnen gelaagde implementaties alleen gebruikersmodules bevatten. Gelaagde implementaties hebben ook een standaard automatische implementatie op een apparaat nodig om de vereiste onderdelen van elk IoT Edge-apparaat te leveren, zoals de systeemruntimemodules.

Hier volgt een eenvoudig gelaagd implementatiemanifest met één module als voorbeeld:

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

Notitie

Dit gelaagde implementatiemanifest heeft een iets andere indeling dan een standaardimplementatiemanifest. De gewenste eigenschappen van de runtimemodules worden samengevouwen en gebruiken punt notatie. Deze opmaak is vereist voor het herkennen van een gelaagde implementatie in Azure Portal. Voorbeeld:

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

In het vorige voorbeeld is de gelaagde implementatie-instelling properties.desired voor een module getoond. Als deze gelaagde implementatie is gericht op een apparaat waarop dezelfde module al is toegepast, worden alle bestaande gewenste eigenschappen overschreven. Als u de gewenste eigenschappen wilt bijwerken in plaats van ze te overschrijven, kunt u een nieuwe subsectie definiëren. Voorbeeld:

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

Hetzelfde kan ook worden uitgedrukt met:

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

Notitie

Op dit moment moeten alle gelaagde implementaties een edgeAgent object bevatten dat als geldig moet worden beschouwd. Zelfs als een gelaagde implementatie alleen module-eigenschappen bijwerken, neemt u een leeg object op. Voorbeeld: "$edgeAgent":{}. Een gelaagde implementatie met een leeg edgeAgent object wordt weergegeven als gericht in de edgeAgent moduledubbel, niet toegepast.

Kortom, om een gelaagde implementatie te maken:

• Voeg de --layered vlag toe aan de azure CLI-opdracht voor maken.
• Neem geen systeemmodules op.
• Gebruik de volledige punt notatie onder $edgeAgent en $edgeHub.

Zie Gelaagde implementatie voor meer informatie over het configureren van moduledubbels in gelaagde implementaties.

Apparaten identificeren met behulp van tags

Voordat u een implementatie kunt maken, moet u kunnen opgeven welke apparaten u wilt beïnvloeden. Azure IoT Edge identificeert apparaten met behulp van tags in de apparaatdubbel.

Elk apparaat kan meerdere tags bevatten die u definieert op elke manier die zinvol is voor uw oplossing. Als u bijvoorbeeld een campus met slimme gebouwen beheert, kunt u de volgende tags toevoegen aan een apparaat:

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

Zie Apparaatdubbels en tags begrijpen en gebruiken in IoT Hub voor meer informatie over apparaatdubbels.

Een implementatie maken

U implementeert modules op uw doelapparaten door een implementatie te maken die bestaat uit het implementatiemanifest en andere parameters.

Gebruik de opdracht az iot edge deployment create om een implementatie te maken:

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

Gebruik dezelfde opdracht met de --layered vlag om een gelaagde implementatie te maken.

De opdracht voor maken voor implementatie heeft de volgende parameters:

• --gelaagd. Een optionele vlag om de implementatie te identificeren als een gelaagde implementatie.
• --deployment-id. De naam van de implementatie die wordt gemaakt in de IoT-hub. Geef uw implementatie een unieke naam die maximaal 128 kleine letters bevat. Vermijd spaties en de volgende ongeldige tekens: & ^ [ ] { } \ | " < > /. Deze parameter is vereist.
• --content. Bestandspad naar het JSON-implementatiemanifest. Deze parameter is vereist.
• --hub-name. Naam van de IoT-hub waarin de implementatie wordt gemaakt. De hub moet zich in het huidige abonnement bevinden. Wijzig uw huidige abonnement met behulp van de az account set -s [subscription name] opdracht.
• --labels. Naam-/waardeparen die uw implementaties beschrijven en bijhouden. Labels hebben JSON-opmaak voor de namen en waarden. Voorbeeld: {"HostPlatform":"Linux", "Version:"3.0.1"}.
• --target-condition. De voorwaarde waarmee wordt bepaald op welke apparaten deze implementatie wordt toegepast. De voorwaarde is gebaseerd op gerapporteerde eigenschappen van apparaatdubbels of apparaatdubbels en moet overeenkomen met de expressie-indeling. Voorbeeld: tags.environment='test' and properties.reported.devicemodel='4000x'. Als de doelvoorwaarde niet is opgegeven, wordt de implementatie niet toegepast op apparaten.
• --prioriteit. Een positief geheel getal. Als twee of meer implementaties op hetzelfde apparaat zijn gericht, is de implementatie met de hoogste numerieke waarde voor prioriteit van toepassing.
• --metrische gegevens. Metrische gegevens die een query uitvoeren op de edgeHub gerapporteerde eigenschappen om de status van een implementatie bij te houden. Metrische gegevens nemen JSON-invoer of een bestandspad. Voorbeeld: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

Zie IoT Edge-implementaties bewaken om een implementatie te bewaken met behulp van de Azure CLI.

Notitie

Wanneer er een nieuwe IoT Edge-implementatie wordt gemaakt, kan het soms tot vijf minuten duren voordat de IoT Hub de nieuwe configuratie verwerkt en de nieuwe gewenste eigenschappen doorgeeft aan de doelapparaten.

Een implementatie wijzigen

Wanneer u een implementatie wijzigt, worden de wijzigingen onmiddellijk gerepliceerd naar alle doelapparaten.

Als u de doelvoorwaarde bijwerkt, worden de volgende updates uitgevoerd:

• Als een apparaat niet voldoet aan de oude doelvoorwaarde, maar voldoet aan de nieuwe doelvoorwaarde en deze implementatie de hoogste prioriteit voor dat apparaat is, wordt deze implementatie toegepast op het apparaat.
• Als een apparaat waarop deze implementatie momenteel wordt uitgevoerd, niet meer voldoet aan de doelvoorwaarde, wordt deze implementatie verwijderd en wordt de implementatie met de hoogste prioriteit uitgevoerd.
• Als een apparaat waarop deze implementatie momenteel wordt uitgevoerd, niet meer voldoet aan de doelvoorwaarde en niet voldoet aan de doelvoorwaarde van andere implementaties, vindt er geen wijziging plaats op het apparaat. Het apparaat blijft de huidige modules in de huidige status uitvoeren, maar wordt niet meer beheerd als onderdeel van deze implementatie. Nadat het apparaat voldoet aan de doelvoorwaarde van een andere implementatie, wordt deze implementatie verwijderd en wordt de nieuwe geïmplementeerd.

U kunt de inhoud van een implementatie niet bijwerken, waaronder de modules en routes die zijn gedefinieerd in het implementatiemanifest. Als u de inhoud van een implementatie wilt bijwerken, maakt u een nieuwe implementatie die gericht is op dezelfde apparaten met een hogere prioriteit. U kunt bepaalde eigenschappen van een bestaande module wijzigen, waaronder de doelvoorwaarde, labels, metrische gegevens en prioriteit.

Gebruik de opdracht az iot edge deployment update om een implementatie bij te werken:

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

De opdracht voor het bijwerken van de implementatie heeft de volgende parameters:

• --deployment-id. De naam van de implementatie die bestaat in de IoT-hub.
• --hub-name. De naam van de IoT-hub waarin de implementatie bestaat. De hub moet zich in het huidige abonnement bevinden. Schakel over naar het gewenste abonnement met behulp van de opdracht az account set -s [subscription name].
• --set. Werk een eigenschap bij in de implementatie. U kunt de volgende eigenschappen bijwerken:
  • targetCondition (bijvoorbeeld, targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add. Voeg een nieuwe eigenschap toe aan de implementatie, inclusief doelvoorwaarden of labels.
• --verwijderen. Verwijder een bestaande eigenschap, inclusief doelvoorwaarden of labels.

Een implementatie verwijderen

Wanneer u een implementatie verwijdert, nemen alle apparaten hun implementatie met de hoogste prioriteit door. Als uw apparaten niet voldoen aan de doelvoorwaarde van een andere implementatie, worden de modules niet verwijderd wanneer de implementatie wordt verwijderd.

Gebruik de opdracht az iot edge deployment delete om een implementatie te verwijderen:

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

De deployment delete opdracht gebruikt de volgende parameters:

• --deployment-id. De naam van de implementatie die bestaat in de IoT-hub.
• --hub-name. De naam van de IoT-hub waarin de implementatie bestaat. De hub moet zich in het huidige abonnement bevinden. Schakel over naar het gewenste abonnement met behulp van de opdracht az account set -s [subscription name].

Volgende stappen

Meer informatie over het implementeren van modules op IoT Edge-apparaten.