| title | description | services | keywords | author | manager | ms.author | ms.date | ms.topic | ms.service |
|---|---|---|---|---|---|---|---|---|---|
Deploy modules for Azure IoT Edge | Microsoft Docs |
Learn about how modules get deployed to edge devices |
iot-edge |
kgremban |
timlt |
kgremban |
10/05/2017 |
article |
iot-edge |
Azure IoT Edge devices follow a device lifecycle that is similar to other types of IoT devices:
- IoT Edge devices are provisioned, which involves imaging a device with an OS and installing the IoT Edge runtime.
- The devices are configured to run IoT Edge modules, and then monitored for health.
- Finally, devices may be retired when they are replaced or become obsolete.
Azure IoT Edge provides two ways to configure the modules to run on IoT Edge devices: one for development and fast iterations on a single device (that you used in the Azure IoT Edge tutorials), and one for managing large fleets of IoT Edge devices. Both of these approaches are available in the Azure Portal and programmatically.
This article focuses on the configuration and monitoring stages for fleets of devices, collectively referred to as IoT Edge deployments. The overall deployment steps are as follows:
- An operator defines a deployment that describes a set of modules as well as the target devices. Each deployment has a deployment manifest that reflects this information.
- The IoT Hub service communicates with all targeted devices to configure them with the desired modules.
- The IoT Hub service retrieves status from the IoT Edge devices and surfaces those for the operator to monitor. For example, an operator can see when an Edge device is not configured successfully or if a module fails during runtime.
- At any time, new IoT Edge devices that meet the targeting conditions are configured for the deployment. For example, a deployment that targets all IoT Edge devices in Washington State automatically configures a new IoT Edge device once it is provisioned and added to the Washington State device group. This article walks through each component involved in configuring and monitoring a deployment. For a walkthrough of creating and updating a deployment, see Deploy and monitor IoT Edge modules at scale.
A deployment assigns IoT Edge module images to run as instances on a targeted set of IoT Edge devices. It works by configuring an IoT Edge deployment manifest to include a list of modules with the corresponding initialization parameters. A deployment can be assigned to a single device (usually based on Device Id) or to a group of devices (based on tags). Once an IoT Edge device receives a deployment manifest, it downloads and installs the module container images from the respective container repositories, and configures them accordingly. Once a deployment is created, an operator can monitor the deployment status to see whether targeted devices are correctly configured.
Devices need to be provisioned as IoT Edge devices to be configured with a deployment. The following are prerequisites, and are not included in the deployment:
- The base operating system
- Docker
- Provisioning of the IoT Edge runtime
A deployment manifest is a JSON document that describes the modules to be configured on the targeted IoT Edge devices. It contains the configuration metadata for all the modules, including the required system modules (specifically the IoT Edge agent and IoT Edge hub).
The configuration metadata for each module includes:
- Version
- Type
- Status (e.g. Running or Stopped)
- Re-start policy
- Image and container repository
- Routes for data input and output
Targeting conditions specify whether an IoT Edge device should be under the scope of a deployment. Targeting conditions are based on device twin tags.
A priority defines whether a deployment should be applied to a targeted device relative to other deployments. A deployment priority is a positive integer, with larger numbers denoting higher priority. If an IoT Edge device is targeted by more than one deployment, the deployment with the highest priority applies. Deployments with lower priorities are not applied, nor are they merged. If a device is targeted with two or more deployments with equal priority, the most recently created deployment (determined by the creation timestamp) applies.
Labels are string key/value pairs that you can use to filter and group of deployments. A deployment may have multiple labels. Labels are optional and do no impact the actual configuration of IoT Edge devices.
A deployment can be monitored to determine whether it applied successfully for any targeted IoT Edge device. A targeted Edge device will appear in one or more of the following status categories:
- Target shows the IoT Edge devices that match the Deployment targeting condition.
- Actual shows the targeted IoT Edge devices that are not targeted by another deployment of higher priority.
- Healthy shows the IoT Edge devices that have reported back to the service that the modules have been deployed successfully.
- Unhealthy shows the IoT Edge devices have reported back to the service that one or modules have not been deployed successfully. To further investigate the error, connect remotely to that devices and view the log files.
- Unknown shows the IoT Edge devices that did not report any status pertaining this deployment. To further investigate, view service info and log files.
A phased rollout is an overall process whereby an operator deploys changes to a broadening set of IoT Edge devices. The goal is to make changes gradually to reduce the risk of making wide scale breaking changes.
A phased rollout is executed in the following phases and steps:
- Establish a test environment of IoT Edge devices by provisioning them and setting a device twin tag like
tag.environment='test'. The test environment should mirror the production environment that the deployment will eventually target. - Create a deployment including the desired modules and configurations. The targeting condition should target the test IoT Edge device environment.
- Validate the new module configuration in the test environment.
- Update the deployment to include a subset of production IoT Edge devices by adding a new tag to the targeting condition. Also, ensure that the priority for the deployment is higher than other deployments currently targeted to those devices
- Verify that the deployment succeeded on the targeted IoT Devices by viewing the deployment status.
- Update the deployment to target all remaining production IoT Edge devices.
Deployments can be rolled back in case of errors or misconfigurations. Because a deployment defines the absolute module configuration for an IoT Edge device, an additional deployment must also be targeted to the same device at a lower priority even if the goal is to remove all modules.
Perform rollbacks in the following sequence:
- Confirm that a second deployment is also targeted at the same device set. If the goal of the rollback is to remove all modules, the second deployment should not include any modules.
- Modify or remove the target condition expression of the deployment you wish to roll back so that the devices no longer meet the targeting condition.
- Verify that the rollback succeeded by viewing the deployment status.
- The rolled-back deployment should no longer show status for the devices that were rolled back.
- The second deployment should now include deployment status for the devices that were rolled back.
- Walk through the steps to create, update, or delete a deployment in Deploy and monitor IoT Edge modules at scale.
- Learn more about other IoT Edge concepts like the IoT Edge runtime and IoT Edge modules.