Understand the Azure IoT Edge runtime and its architecture - preview

The IoT Edge runtime is a collection of programs that need to be installed on a device for it to be considered an IoT Edge device. Collectively, the components of the IoT Edge runtime enable IoT Edge devices to receive code to run at the edge, and communicate the results.

The IoT Edge runtime performs the following functions on IoT Edge devices:

  • Installs and updates workloads on the device.
  • Maintains Azure IoT Edge security standards on the device.
  • Ensures that IoT Edge modules are always running.
  • Reports module health to the cloud for remote monitoring.
  • Facilitates communication between downstream leaf devices and the IoT Edge device.
  • Facilitates communication between modules on the IoT Edge device.
  • Facilitates communication between the IoT Edge device and the cloud.

IoT Edge runtime communicates insights and module health to IoT Hub

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

Both the Edge agent and the Edge hub are modules, just like any other module running on an IoT Edge device. For more information about how modules work, see lnk-modules.

IoT Edge hub

The 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

During public preview Edge Hub only supports clients that connect using MQTT.

The Edge hub is not a full version of IoT Hub running locally. There are some things that the Edge hub silently delegates to IoT Hub. For example, 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 Edge hub. Subsequent connections from that device are allowed without having to authenticate to the cloud.

Note

During public preview the runtime must be connected every time it tries to authenticate a device.

To reduce the bandwidth your IoT Edge solution uses, the Edge hub optimizes how many actual connections are made to the cloud. Edge hub takes logical connections from clients like modules or leaf 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.

Edge hub acts as a gateway between multiple physical devices and the cloud

Edge hub can determine whether it's connected to IoT Hub. If the connection is lost, 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 Edge hub’s module twin. The size of the cache is not capped and will grow as long as the device has storage capacity.

Note

Adding control over additional caching parameters will be added to the product before it enters general availability.

Module communication

Edge Hub facilitates module to module communication. Using 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 then stitches these inputs and outputs together so that the modules process data in the order specific to that solution.

Edge Hub facilitates module-to-module communication

To send data to the 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:

DeviceClient client = new DeviceClient.CreateFromConnectionString(moduleConnectionString, settings); 
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.SetEventHandlerAsync(“input1”, messageProcessor, userContext);

The solution developer is responsible for specifying the rules that determine how Edge hub passes messages between modules. Routing rules are defined in the cloud and pushed down to Edge hub in its device twin. The same syntax for IoT Hub routes is used to define routes between modules in Azure IoT Edge.

Routes between modules

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. Just like any other module, the Edge agent uses its module twin to store this configuration data.

To begin execution of the Edge agent, run the azure-iot-edge-runtime-ctl.py start command. The agent retrieves its module twin from IoT Hub and inspects the modules dictionary. The modules dictionary is the collection of modules that need to be started.

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

  • settings.image – The container image that the Edge agent uses to start the module. The Edge agent must be configured with credentials for the container registry if the image is protected by a password. To configure the Edge agent, use the following command: azure-iot-edge-runtime-ctl.py –configure
  • settings.createOptions – A string that is passed directly to the Docker daemon when starting a module’s container. Adding Docker options in this property allows for advanced options like port forwarding or mounting volumes into a module’s container.
  • status – The state in which the Edge agent places the module. This value is usually set to running as most people want the 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 Edge agent to start a module. The 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 or a misbehaving device. The supported statuses are:
    • Downloading
    • Running
    • Unhealthy
    • Failed
    • Stopped
  • restartPolicy – How the Edge agent restarts a module. Possible values include:
    • Never – The Edge agent never restarts the module.
    • onFailure - If the module crashes, the Edge agent restarts it. If the module shuts down cleanly, the Edge agent does not restart it.
    • Unhealthy - If the module crashes or is deemed unhealthy, the Edge agent restarts it.
    • Always - If the module crashes, is deemed unhealthy, or shuts down in any way, the Edge agent restarts it.

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 does not have a deployment configuration set.
  • 412 - The schema version in the deployment configuration is invalid.
  • 406 - The edge device is offline or not sending status reports.
  • 500 - An error occurred in the edge runtime.

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. These features will be added at general availability of V2 features.

Next steps