Pipeline overloading the poor $edgeAgent

Azure IoT Edge order of deployment operations

This post was most recently updated on July 27th, 2022.

3 min read.

This article tries to bridge a gap in Microsoft’s documentation for the Azure IoT Edge deployment model. Namely – all different ways to deploy modules or module configurations to your Azure IoT Edge devices, and which takes precedence over which.


The documentation for Azure IoT Edge is surprisingly immature. As you go about your first projects, you will run into all kinds of gaps. One of the things I ran into that definitely required some clarification was which deployment takes priority when you deploy your modules multiple different ways.


In which order do different deployments take action in Azure IoT Edge? The list below aims to answer that question!

Time needed: 10 minutes

How to deploy/overwrite/not mess up your IoT Edge Module configuration?

  1. Runtime instantiation

    Installing your runtime will provide you with $edgeAgent and $edgeHub, but with no custom modules.

    You can modify these using the Azure Portal UI (not reversible, but can always be redone), an actual base/single-device deployment (irreversible and will take priority over the former), or theoretically also by generating a Single-Device deployment from VS Code (I wouldn’t really do this for any production environments, though!)

  2. Base deployment

    Creating a “base deployment” initiates a “baseline” deployment for your device. You can deploy using Az CLI or the Azure Portal (in which case it’ll be a “base deployment” that you can target many devices.

    At the time of writing this (Jan 2022), as long as you’re using a “full” deployment manifest schema, any deployment you’ll create using Az CLI (no matter whether you’re using the –layered switch or not) will be a base deployment.

    You can modify $edgeAgent and $edgeHub, as well as your modules and routes.

    This configuration will automatically overwrite any changes to modules that you might want to do using Azure Portal UI afterward, so be mindful of what you’re deploying! You might not be able to remove it. Ever.

  3. Layered deployments

    Each layered deployment (a deployment that uses the layered deployment manifest file schema AND is deployed with –layered switch) will take precedence over any earlier layered deployments with equal or lower priority, and be incremental over any base deployment or runtime configuration you have created.

  4. A “Configuration” deployment

    You can create a configuration deployment from the Azure Portal UI under “IoT Hub > Device Managements > Configurations”.

    You can use this to overwrite configurations for both Devices and Modules. You can overwrite contents in their Digital Twins, such as “properties.desired.settings”.

  5. Adding new modules using Azure Portal UI (such as using “Set Modules”)

    I know, I know – it’s getting convoluted! But you can also add the new modules from the Azure Portal UI, by using “Set Modules”.

    This view makes it possible for you to add a new module (well, container) details and it’ll be added to your IoT Edge host (.. Docker host, that is).

    How to set modules on Azure IoT Hub's Edge Device configuration

    Any module configurations will (probably?) be overwritten by any deployments that match them (i.e. the targetCondition matches and there’s a module or a system module (“runtime settings” in the screenshot above) configuration that differs from your settings here.

  6. Modifying runtime values using Azure Portal UI (such as using the “Module Identity” editor)

    You can modify the digital twin values and environment variables using the “Set Modules” option, or from the “Module Identity” editor directly.

    Module twin values (and probably any environment variables) will be overwritten to whatever is provisioned in the deployments, though – so any layered or base deployment WILL take precedence (after a minute or two), and any Configuration will take precedence (possibly a bit slower – no idea why).

There are some other interesting things to blog about in the whole IoT Edge space – and I’ll probably be documenting them in the future as and when I encounter them!

Got an issue I haven’t run into yet? Let me know in the comments -section below, and we’ll see if we can crack it together!

5 2 votes
Article Rating
Notify of

Inline Feedbacks
View all comments