Skip to content

Latest commit

 

History

History
124 lines (82 loc) · 10.1 KB

iot-edge-runtime.md

File metadata and controls

124 lines (82 loc) · 10.1 KB
title description author manager ms.author ms.date ms.topic ms.service services ms.custom
Learn how the runtime manages devices - Azure IoT Edge | Microsoft Docs
Learn how the IoT Edge runtime manages modules, security, communication, and reporting on your devices
kgremban
philmea
kgremban
11/01/2019
conceptual
iot-edge
iot-edge
amqp
mqtt

Understand the Azure IoT Edge runtime and its architecture

The IoT Edge runtime is a collection of programs that turn a device into an IoT Edge device. Collectively, the IoT Edge runtime components enable IoT Edge devices to receive code to run at the edge and communicate the results.

The IoT Edge runtime is responsible for the following functions on IoT Edge devices:

  • Install and update workloads on the device.
  • Maintain Azure IoT Edge security standards on the device.
  • Ensure that IoT Edge modules are always running.
  • Report module health to the cloud for remote monitoring.
  • Manage communication between downstream devices and IoT Edge devices.
  • Manage communication between modules on the IoT Edge device.
  • Manage communication between the IoT Edge device and the cloud.

Runtime communicates insights and module health to IoT Hub

The responsibilities of the IoT Edge runtime fall into two categories: communication and module management. These two roles are performed by two components that are part of the IoT Edge runtime. The IoT Edge hub is responsible for communication, while the IoT Edge agent deploys and monitors the modules.

Both the IoT Edge hub and the IoT Edge agent are modules, just like any other module running on an IoT Edge device. They're sometimes referred to as the runtime modules.

IoT Edge hub

The IoT Edge hub is one of two modules that make up the Azure IoT Edge runtime. It acts as a local proxy for IoT Hub by exposing the same protocol endpoints as IoT Hub. This consistency means that clients (whether devices or modules) can connect to the IoT Edge runtime just as they would to IoT Hub.

Note

IoT Edge hub supports clients that connect using MQTT or AMQP. It does not support clients that use HTTP.

The IoT Edge hub isn't a full version of IoT Hub running locally. IoT Edge hub silently delegates some tasks to IoT Hub. For example, IoT Edge hub forwards authentication requests to IoT Hub when a device first tries to connect. After the first connection is established, security information is cached locally by IoT Edge hub. Future connections from that device are allowed without having to authenticate to the cloud again.

To reduce the bandwidth that your IoT Edge solution uses, the IoT Edge hub optimizes how many actual connections are made to the cloud. IoT Edge hub takes logical connections from modules or downstream devices and combines them for a single physical connection to the cloud. The details of this process are transparent to the rest of the solution. Clients think they have their own connection to the cloud even though they are all being sent over the same connection.

IoT Edge hub is a gateway between physical devices and IoT Hub

IoT Edge hub can determine whether it's connected to IoT Hub. If the connection is lost, IoT Edge hub saves messages or twin updates locally. Once a connection is reestablished, it syncs all the data. The location used for this temporary cache is determined by a property of the IoT Edge hub's module twin. The size of the cache is not capped and will grow as long as the device has storage capacity. For more information, see Offline capabilities.

Module communication

IoT Edge hub facilitates module to module communication. Using IoT Edge hub as a message broker keeps modules independent from each other. Modules only need to specify the inputs on which they accept messages and the outputs to which they write messages. A solution developer can stitch these inputs and outputs together so that the modules process data in the order specific to that solution.

IoT Edge Hub facilitates module-to-module communication

To send data to the IoT Edge hub, a module calls the SendEventAsync method. The first argument specifies on which output to send the message. The following pseudocode sends a message on output1:

ModuleClient client = await ModuleClient.CreateFromEnvironmentAsync(transportSettings);
await client.OpenAsync();
await client.SendEventAsync("output1", message);

To receive a message, register a callback that processes messages coming in on a specific input. The following pseudocode registers the function messageProcessor to be used for processing all messages received on input1:

await client.SetInputMessageHandlerAsync("input1", messageProcessor, userContext);

For more information about the ModuleClient class and its communication methods, see the API reference for your preferred SDK language: C#, C, Python, Java, or Node.js.

The solution developer is responsible for specifying the rules that determine how IoT Edge hub passes messages between modules. Routing rules are defined in the cloud and pushed down to IoT Edge hub in its module twin. The same syntax for IoT Hub routes is used to define routes between modules in Azure IoT Edge. For more information, see Learn how to deploy modules and establish routes in IoT Edge.

Routes between modules go through IoT Edge hub

IoT Edge agent

The IoT Edge agent is the other module that makes up the Azure IoT Edge runtime. It is responsible for instantiating modules, ensuring that they continue to run, and reporting the status of the modules back to IoT Hub. This configuration data is written as a property of the IoT Edge agent module twin.

The IoT Edge security daemon starts the IoT Edge agent on device startup. The agent retrieves its module twin from IoT Hub and inspects the deployment manifest. The deployment manifest is a JSON file that declares the modules that need to be started.

Each item in the deployment manifest contains specific information about a module and is used by the IoT Edge agent for controlling the module's lifecycle. Some of the more interesting properties are:

  • settings.image – The container image that the IoT Edge agent uses to start the module. The IoT Edge agent must be configured with credentials for the container registry if the image is protected by a password. Credentials for the container registry can be configured remotely using the deployment manifest, or on the IoT Edge device itself by updating the config.yaml file in the IoT Edge program folder.

  • settings.createOptions – A string that is passed directly to the Moby container daemon when starting a module's container. Adding options in this property allows for advanced configurations like port forwarding or mounting volumes into a module's container.  

  • status – The state in which the IoT Edge agent places the module. Usually, this value is set to running as most people want the IoT Edge agent to immediately start all modules on the device. However, you could specify the initial state of a module to be stopped and wait for a future time to tell the IoT Edge agent to start a module. The IoT Edge agent reports the status of each module back to the cloud in the reported properties. A difference between the desired property and the reported property is an indicator of a misbehaving device. The supported statuses are:

    • Downloading
    • Running
    • Unhealthy
    • Failed
    • Stopped

  • restartPolicy – How the IoT Edge agent restarts a module. Possible values include:

    • never – The IoT Edge agent never restarts the module.
    • on-failure - If the module crashes, the IoT Edge agent restarts it. If the module shuts down cleanly, the IoT Edge agent doesn't restart it.
    • on-unhealthy - If the module crashes or is considered unhealthy, the IoT Edge agent restarts it.
    • always - If the module crashes, is considered unhealthy, or shuts down in any way, the IoT Edge agent restarts it.

  • imagePullPolicy - Whether the IoT Edge agent attempts to pull the latest image for a module automatically or not. If you don't specify a value, the default is onCreate. Possible values include:

    • on-create - When starting a module or updating a module based on a new deployment manifest, the IoT Edge agent will attempt to pull the module image from the container registry.
    • never - The IoT Edge agent will never attempt to pull the module image from the container registry. With this configuration, then you're responsible for getting the module image onto the device and managing any image updates.

The IoT Edge agent sends runtime response to IoT Hub. Here is a list of possible responses:

  • 200 - OK
  • 400 - The deployment configuration is malformed or invalid.
  • 417 - The device doesn't have a deployment configuration set.
  • 412 - The schema version in the deployment configuration is invalid.
  • 406 - The IoT Edge device is offline or not sending status reports.
  • 500 - An error occurred in the IoT Edge runtime.

For more information, see Learn how to deploy modules and establish routes in IoT Edge.

Security

The IoT Edge agent plays a critical role in the security of an IoT Edge device. For example, it performs actions like verifying a module's image before starting it.

For more information about the Azure IoT Edge security framework, read about the IoT Edge security manager.

Next steps

Understand Azure IoT Edge modules