Skip to main content

How to create a Deployment Manifest

Define the structure​

Begin by creating a deployment manifest that contains only the IoT Edge runtime ($edgeAgent and $edgeHub). This is a valid starting point. You can add up to 50 additional modules to run on an IoT Edge device. The structure of the deployment manifest should follow the following format:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": {
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules, and to IoT Hub
      }
    },
    "module1": {  
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

Configure Modules​

Define how the IoT Edge runtime installs the modules in your deployment. This includes the configuration parameters for the IoT Edge agent itself and all modules. The $edgeAgent module twin contains the configuration and management information for all modules.

Module Configuration and Management​

The desired properties list of the IoT Edge agent is where you define which modules are deployed to an IoT Edge device and how they should be configured and managed. Every module has a settings property that contains the module image, an address for the container image in a container registry, and any createOptions to configure the image on startup.

Set Module Properties​

The edgeHub module and custom modules have three properties that tell the IoT Edge agent how to manage them: Status, RestartPolicy, and StartupOrder. Changes to a module's properties will result in that module restarting. If no module property is changed, the module will not restart.

Declare Routes​

The $edgeHub module twin contains a desired property called routes that declares how messages are passed within a deployment. You can have multiple routes within the same deployment. Routes are declared in the $edgeHub desired properties with the following syntax:

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

Remember to replace <source>, <condition>, and <sink> with the correct information for your routes.

Finalize and Deploy Manifest​

After configuring all the modules and setting up the routes, validate your manifest and deploy it to your IoT Edge device. A newly installed IoT Edge runtime reports an error code until configured with a valid manifest.

A manifest in the context of Azure IoT Edge is a JSON document that describes which modules (containers) to deploy to an IoT Edge device and how to configure these modules. It essentially forms the blueprint for an IoT Edge device. A module in IoT Edge is the smallest unit of computation managed by IoT Edge and can contain Azure services, third-party services, or your own solution-specific code.

When you create a deployment manifest, you're defining:

  • Which modules to run on your IoT Edge device. These could include built-in system modules like IoT Edge Hub and IoT Edge Agent, as well as custom modules for specific tasks such as data processing, data filtering, data transformation, etc.
  • The Docker images to use for each module.
  • Configuration settings for each module, such as the desired properties of the module and the Docker create options for the module.
  • How the modules interact with each other, including which routes to set up for messages between modules.

Why do we create a manifest?​

The purpose of creating and deploying manifests in an IoT Edge device is to enable cloud deployment and management of edge computing devices. With a deployment manifest:

  • You can easily replicate a deployment across multiple IoT Edge devices. This can greatly simplify the process of scaling out your IoT solution across numerous edge devices.

  • You can centrally manage and monitor your IoT Edge devices from the cloud, providing an overview of the health of your IoT Edge devices and allowing for remote troubleshooting and updates.

  • You have the ability to manage your devices securely by enforcing desired properties on the modules and setting routes for data flow between modules, which can help prevent unauthorized access or changes.

  • You can update a module, add a new module, or remove a module from an IoT Edge device by simply updating the manifest and deploying it, reducing the need for physical access to the IoT Edge device.

Components of a Deployment Manifest​

Each IoT Edge device runs at least two modules: $edgeAgent and $edgeHub, which are part of the IoT Edge runtime. A deployment manifest is a JSON document that describes the configuration of these modules and any additional modules you wish to add. This configuration includes the container image for each module, the credentials to access private container registries, and instructions for how each module should be created and managed.