Deploying IoT Edge Modules
This document provides a comprehensive guide to deploying and managing modules on your Azure IoT Edge devices. Learn how to create deployment manifests, target specific devices, and monitor the status of your deployments.
What are IoT Edge Deployments?
An IoT Edge deployment is a set of instructions that tell an IoT Edge device what modules to run, how to configure them, and the desired properties for the module twins. Deployments allow you to manage modules at scale across your fleet of IoT Edge devices.
Key components of a deployment include:
- Modules: The containerized applications that run on your IoT Edge devices.
- Module Twins: Representations of your modules in the cloud, used to synchronize state and configurations.
- Device Twins: Representations of your IoT Edge devices in the cloud. Deployments can target specific device twins or groups of device twins.
- Routes: Define how messages flow between modules and between modules and IoT Hub.
Creating a Deployment Manifest
A deployment manifest is a JSON file that defines the modules to be deployed, their configurations, and routing information. You can create these manifests using the Azure portal, Azure CLI, or programmatically.
Example Deployment Manifest (deployment.json):
{
"content": {
"modulesContent": {
"$edgeAgent": {
"properties.desired": {
"schemaVersion": "1.0",
"runtime": {
"type": "docker",
"settings": {
"minDockerVersion": "v1.25"
}
},
"systemModules": {
"edgeAgent": {
"type": "docker",
"version": "1.0",
"env": {}
},
"edgeHub": {
"type": "docker",
"version": "1.0",
"status": "running",
"restartPolicy": "always",
"env": {
"experimentalFeatures.propertylist": " 1 ",
"MqttBroker.Property.MaxTopicLength": "128",
"MqttBroker.Property.MaxMessagesPerConnection": "100",
"MqttBroker.Property.MaxConnectionsPerIpAddress": "100"
}
}
},
"modules": {
"tempSensor": {
"version": "1.0",
"type": "docker",
"env": {},
"status": "running",
"restartPolicy": "always"
},
"azureIotHubModule": {
"version": "1.0",
"type": "docker",
"status": "running",
"restartPolicy": "always",
"env": {}
}
}
}
},
"tempSensor": {
"properties.desired": {
"temp": 25,
"interval": 5000
}
}
},
"registryCredentials": {
"registryA": {
"username": "your_registry_username",
"password": "your_registry_password",
"address": "your_registry_address.azurecr.io"
}
}
},
"deploymentProperties": {
"deploymentPriority": 0,
"metrics": {},
"targetCondition": "tags.environment='production'"
}
}Types of Deployments
There are two main types of deployments:
- Automatic Device Management (ADM) Deployments: These deployments are applied automatically to devices based on tags and conditions defined in the deployment. They are ideal for large-scale deployments and ongoing management.
- Direct Method Calls: While not a deployment type, direct methods can be used to trigger module actions on a device, offering immediate control.
Creating and Managing Deployments in Azure Portal
The Azure portal offers a user-friendly interface for creating and managing IoT Edge deployments:
- Navigate to your IoT Hub.
- Select Automatic device management from the left-hand menu.
- Click + Create to start a new deployment.
- Deployment type: Choose between Edge Managed or IoT Edge module.
- Deployment configuration: Upload your deployment manifest or configure modules directly.
- Target devices: Specify the devices or device groups to target using tags.
- Add metrics (optional): Define custom metrics for monitoring.
- Review + create: Finalize and create your deployment.
Deploying Custom Modules
To deploy your own custom modules, you'll need to:
- Containerize your application using Docker.
- Push the container image to a container registry (e.g., Azure Container Registry).
- Reference the image URI and credentials in your deployment manifest.
Deployment Priorities and Labels
When multiple deployments target the same device, the deployment with the highest priority (a lower integer value indicates higher priority) takes precedence. Labels can be used to group and organize deployments.
Monitoring Deployments
Monitor the status of your deployments to ensure modules are running correctly on your edge devices.
- Deployment Status: View overall deployment success rates.
- Device Status: Check the status of individual devices receiving the deployment.
- Module Status: Verify that specific modules are running as expected.
- Metrics: Use custom metrics to track operational data from your edge modules.
Troubleshooting Deployments
Common issues include:
- Incorrect container image URIs or credentials.
- Network connectivity problems preventing module image pulls.
- Mismatched schema versions in the deployment manifest.
- Module conflicts or misconfigurations.
Refer to the IoT Edge agent and IoT Edge hub logs on the device for detailed error information.