Run MaestroHub as an Azure IoT Edge Module

This guide deploys MaestroHub as a module on an Azure IoT Edge device, so it can exchange messages with other modules and with Azure IoT Hub through the device's edge hub. Running as a module lets the Azure IoT Edge connector use IoT Edge runtime authentication: the runtime supplies MaestroHub's identity, signs its tokens and gives it the edge CA, and nothing secret is stored in MaestroHub.

Prerequisites

• An IoT Edge device running Azure IoT Edge 1.6, registered in an IoT Hub on the Free or Standard tier. The Basic tiers support neither IoT Edge nor module twins and direct methods.
• The MaestroHub container image in a registry the device can pull from, and that registry's credentials.
• Permission to set modules on the device in IoT Hub (for example the IoT Hub Registry Contributor role, or the registryReadWrite policy).

1. Add the MaestroHub module to the deployment

Add a module named maestrohub to the device's deployment, in the Azure portal (IoT Edge → your device → Set modules) or in the deployment manifest you apply with az iot edge set-modules. The module name becomes MaestroHub's module identity.

In a deployment manifest, the module sits under $edgeAgent → properties.desired → modules:

"maestrohub": {
  "version": "1.0",
  "type": "docker",
  "status": "running",
  "restartPolicy": "always",
  "settings": {
    "image": "<your-registry>/maestrohub:<version>",
    "createOptions": "{\"HostConfig\":{\"Binds\":[\"maestrohub-data:/data\"],\"PortBindings\":{\"8080/tcp\":[{\"HostPort\":\"8080\"}]}},\"StopTimeout\":40}"
  }
}

• Binds keeps MaestroHub's data (connections, pipelines, Store & Forward buffers) in the maestrohub-data volume, so it survives module updates and restarts.
• PortBindings publishes the web UI and API on the device's port 8080. Change the host port if 8080 is taken.
• StopTimeout gives MaestroHub 40 seconds to shut down cleanly; MaestroHub takes up to 30 seconds to finish in-flight work on stop.

Add the registry's credentials under $edgeAgent → properties.desired → runtime.settings.registryCredentials if the registry is private.

You do not set any IOTEDGE_* variables yourself: the IoT Edge agent gives every module its identity and the address of the workload API when it starts it.

2. Route messages to and from MaestroHub

The edge hub delivers a module's messages only where a route sends them. Routes go under $edgeHub → properties.desired → routes. Examples:

"routes": {
  "maestrohubToCloud": "FROM /messages/modules/maestrohub/outputs/telemetry INTO $upstream",
  "maestrohubToAnalytics": "FROM /messages/modules/maestrohub/outputs/features INTO BrokeredEndpoint(\"/modules/analytics/inputs/features\")",
  "alertsToMaestrohub": "FROM /messages/modules/analytics/outputs/alerts INTO BrokeredEndpoint(\"/modules/maestrohub/inputs/alerts\")"
}

• A Send to Output node on output telemetry reaches IoT Hub through the first route.
• A Receive on Input function with input alerts receives what the analytics module sends on its output alerts.

A message whose output no route matches is dropped by the edge hub, and MaestroHub cannot see the routes. Check each output name you use against this list.

3. Choose how long the edge hub keeps messages offline

While the device is offline from Azure, the edge hub keeps messages for $upstream for a time to live, 7200 seconds (2 hours) by default, then drops them. If outages can last longer, raise it under $edgeHub → properties.desired:

"storeAndForwardConfiguration": {
  "timeToLiveSecs": 86400
}

MaestroHub's own Store & Forward is a separate buffer: it covers the edge hub itself being unreachable, for example while it restarts.

4. Create the connection in MaestroHub

Open MaestroHub on the device (port 8080), go to Connections → New Connection → Azure IoT Edge, and keep Authentication Method at IoT Edge runtime. There is nothing else to fill in. Test Connection shows the identity MaestroHub runs as (<hub>/<device>/maestrohub), the edge hub it reached, and when the edge CA expires.

If IoT Edge runtime is shown disabled, MaestroHub is not running as a module: the IoT Edge environment variables are missing. Check that the module was deployed by the IoT Edge agent rather than started by hand.

Create only one Azure IoT Edge connection with a given module identity: the edge hub keeps one session per identity, and MaestroHub refuses a second connection that would use the same one.

5. Update or redeploy

Updating the image or the createOptions restarts the module; the maestrohub-data volume keeps its data. A redeployed module gets a new generation from the runtime, and MaestroHub picks up the new identity when it starts.

Running MaestroHub next to IoT Edge instead

If MaestroHub runs on another machine, or on the device but not as a module, use Module key authentication: create a module identity for it in IoT Hub (IoT Edge → your device → + Add module identity, or az iot hub module-identity create), and enter the IoT Hub hostname, device ID, module ID, the module's key, the edge device's host name, and the edge CA certificate in the connection form. You can paste the module's connection string into the form to fill in the identity fields.