Understand Azure IoT Edge modules
Applies to: IoT Edge 1.5
Important
IoT Edge 1.5 LTS is the supported release. IoT Edge 1.4 LTS is end of life as of November 12, 2024. If you are on an earlier release, see Update IoT Edge.
Azure IoT Edge lets you deploy and manage business logic on edge devices using modules. Azure IoT Edge modules are the smallest unit of computation managed by IoT Edge, and can contain Azure services (such as Azure Stream Analytics) or your own solution-specific code. To understand how modules are developed, deployed, and maintained, consider the four conceptual elements of a module:
- A module image is a package containing the software that defines a module.
- A module instance is the specific unit of computation running the module image on an IoT Edge device. The module instance is started by the IoT Edge runtime.
- A module identity is a piece of information (including security credentials) stored in IoT Hub that is associated to each module instance.
- A module twin is a JSON document stored in IoT Hub that contains state information for a module instance, including metadata, configurations, and conditions.
Module images and instances
IoT Edge module images contain applications that take advantage of the management, security, and communication features of the IoT Edge runtime. You can develop your own module images, or export one from a supported Azure service, such as Azure Stream Analytics. The images exist in the cloud, and you can update, change, and deploy them in different solutions. For example, a module using machine learning to predict production line output is a separate image from a module using computer vision to control a drone.
Each time the IoT Edge runtime deploys and starts a module image on a device, it creates a new instance of that module. Two devices in different parts of the world could use the same module image. However, each device would have its own module instance when the module is started on the device.
In implementation, modules images exist as container images in a repository, and module instances are containers on devices.
Module identities
When the IoT Edge runtime creates a new module instance, it assigns a corresponding module identity. IoT Hub stores the module identity, which serves as the addressing and security scope for all local and cloud communications for the module instance.
The module instance's identity depends on the device's identity and the name you assign to the module in your solution. For example, if you name a module insight
and deploy it on a device called Hannover01
, the IoT Edge runtime creates a corresponding module identity called /devices/Hannover01/modules/insight
.
In scenarios where you need to deploy one module image multiple times on the same device, you can deploy it with different names.
Module twins
Each module instance has a corresponding module twin you use to configure it. The module identity links the instance and the twin.
A module twin is a JSON document that stores module information and configuration properties. This concept parallels the device twin concept from IoT Hub. A module twin's structure is the same as a device twin's. The APIs for interacting with both types of twins are the same. The only difference between the two is the identity used to instantiate the client SDK.
// Create a ModuleClient object. This ModuleClient will act on behalf of a
// module since it is created with a module's connection string instead
// of a device connection string.
ModuleClient client = new ModuleClient.CreateFromEnvironmentAsync(settings);
await client.OpenAsync();
// Get the module twin
Twin twin = await client.GetTwinAsync();
Offline capabilities
Azure IoT Edge modules operate offline indefinitely after syncing with IoT Hub once. IoT Edge devices can also extend this offline capability to other IoT devices. For more information, see Understand extended offline capabilities for IoT Edge devices, modules, and downstream devices.