|
| 1 | +--- |
| 2 | +title: Deploy modules at scale using Visual Studio Code - Azure IoT Edge |
| 3 | +description: Use the IoT extension for Visual Studio Code to create automatic deployments for groups of IoT Edge devices. |
| 4 | +keywords: |
| 5 | +author: kgremban |
| 6 | +manager: philmea |
| 7 | +ms.author: kgremban |
| 8 | +ms.date: 1/8/2020 |
| 9 | +ms.topic: conceptual |
| 10 | +ms.service: iot-edge |
| 11 | +services: iot-edge |
| 12 | +--- |
| 13 | + |
| 14 | +# Deploy IoT Edge modules at scale using Visual Studio Code |
| 15 | + |
| 16 | +You can create an **IoT Edge automatic deployment** using Visual Studio Code to manage ongoing deployments for many devices at once. Automatic deployments for IoT Edge are part of the [automatic device management](/azure/iot-hub/iot-hub-automatic-device-management) feature of IoT Hub. Deployments are dynamic processes that enable you to deploy multiple modules to multiple devices. You can also track the status and health of the modules, and make changes when necessary. |
| 17 | + |
| 18 | +For more information, see [Understand IoT Edge automatic deployments for single devices or at scale](module-deployment-monitoring.md). |
| 19 | + |
| 20 | +In this article, you set up Visual Studio Code and the IoT extension. You then learn how to deploy modules to a set of IoT Edge devices. |
| 21 | + |
| 22 | +## Prerequisites |
| 23 | + |
| 24 | +* An [IoT hub](../iot-hub/iot-hub-create-through-portal.md) in your Azure subscription. |
| 25 | +* An [IoT Edge device](how-to-register-device.md#register-with-visual-studio-code) with the IoT Edge runtime installed. |
| 26 | +* [Visual Studio Code](https://code.visualstudio.com/). |
| 27 | +* [Azure IoT Tools](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-tools#overview) for Visual Studio Code. |
| 28 | + |
| 29 | +## Sign in to access your IoT hub |
| 30 | + |
| 31 | +You can use the Azure IoT extensions for Visual Studio Code to do operations with your Hub. For these operations to work, you need to sign into your Azure account and select the IoT hub that you are working on. |
| 32 | + |
| 33 | +1. In Visual Studio Code, open the **Explorer** view. |
| 34 | + |
| 35 | +1. At the bottom of the Explorer, expand the **Azure IoT Hub** section. |
| 36 | + |
| 37 | +1. Click on the **...** in the **Azure IoT Hub** section header. If you don't see the ellipsis, hover over the header. |
| 38 | + |
| 39 | +1. Choose **Select IoT Hub**. |
| 40 | + |
| 41 | +1. If you are not signed into your Azure account, follow the prompts to do so. |
| 42 | + |
| 43 | +1. Select your Azure subscription. |
| 44 | + |
| 45 | +1. Select your IoT hub. |
| 46 | + |
| 47 | +## Configure a deployment manifest |
| 48 | + |
| 49 | +A deployment manifest is a JSON document that describes which modules to deploy. It also describes how data flows between the modules, and desired properties of the module twins. For more information, see [Learn how to deploy modules and establish routes in IoT Edge](module-composition.md). |
| 50 | + |
| 51 | +To deploy modules using Visual Studio Code, save the deployment manifest locally as a .JSON file. You will need to provide its location when you run the command to apply the configuration to your device. |
| 52 | + |
| 53 | +Here's a basic deployment manifest with one module as an example: |
| 54 | + |
| 55 | +```json |
| 56 | +{ |
| 57 | + "content": { |
| 58 | + "modulesContent": { |
| 59 | + "$edgeAgent": { |
| 60 | + "properties.desired": { |
| 61 | + "schemaVersion": "1.0", |
| 62 | + "runtime": { |
| 63 | + "type": "docker", |
| 64 | + "settings": { |
| 65 | + "minDockerVersion": "v1.25", |
| 66 | + "loggingOptions": "", |
| 67 | + "registryCredentials": {} |
| 68 | + } |
| 69 | + }, |
| 70 | + "systemModules": { |
| 71 | + "edgeAgent": { |
| 72 | + "type": "docker", |
| 73 | + "settings": { |
| 74 | + "image": "mcr.microsoft.com/azureiotedge-agent:1.0", |
| 75 | + "createOptions": "{}" |
| 76 | + } |
| 77 | + }, |
| 78 | + "edgeHub": { |
| 79 | + "type": "docker", |
| 80 | + "status": "running", |
| 81 | + "restartPolicy": "always", |
| 82 | + "settings": { |
| 83 | + "image": "mcr.microsoft.com/azureiotedge-hub:1.0", |
| 84 | + "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}" |
| 85 | + } |
| 86 | + } |
| 87 | + }, |
| 88 | + "modules": { |
| 89 | + "SimulatedTemperatureSensor": { |
| 90 | + "version": "1.0", |
| 91 | + "type": "docker", |
| 92 | + "status": "running", |
| 93 | + "restartPolicy": "always", |
| 94 | + "settings": { |
| 95 | + "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0", |
| 96 | + "createOptions": "{}" |
| 97 | + } |
| 98 | + } |
| 99 | + } |
| 100 | + } |
| 101 | + }, |
| 102 | + "$edgeHub": { |
| 103 | + "properties.desired": { |
| 104 | + "schemaVersion": "1.0", |
| 105 | + "routes": { |
| 106 | + "upstream": "FROM /messages/* INTO $upstream" |
| 107 | + }, |
| 108 | + "storeAndForwardConfiguration": { |
| 109 | + "timeToLiveSecs": 7200 |
| 110 | + } |
| 111 | + } |
| 112 | + }, |
| 113 | + "SimulatedTemperatureSensor": { |
| 114 | + "properties.desired": { |
| 115 | + "SendData": true, |
| 116 | + "SendInterval": 5 |
| 117 | + } |
| 118 | + } |
| 119 | + } |
| 120 | + } |
| 121 | +} |
| 122 | +``` |
| 123 | + |
| 124 | +If you need to determine which IoT Edge devices you can currently configure, run the **IoT Edge: Get Device Info** command. |
| 125 | + |
| 126 | +## Identify devices with target conditions |
| 127 | + |
| 128 | +To identify the IoT Edge devices that are to receive the deployment, you must specify a target condition. A target condition is met when specified criteria is matched by a deviceId, tag value, or a reported property value. |
| 129 | + |
| 130 | +You configure tags in the device twin. Here is an example of a device twin that has tags: |
| 131 | + |
| 132 | +```json |
| 133 | +"tags":{ |
| 134 | + "location":{ |
| 135 | + "building": "20", |
| 136 | + "floor": "2" |
| 137 | + }, |
| 138 | + "roomtype": "conference", |
| 139 | + "environment": "prod" |
| 140 | +} |
| 141 | +``` |
| 142 | + |
| 143 | +This device will receive a deployment if the target condition for the deployment contains an expression that matches one of the tag's values, such as `tag.location.building = '20'`. |
| 144 | + |
| 145 | +If you want to target a specific device regardless of its tags or other values, just specify the `deviceId` for the target condition. |
| 146 | + |
| 147 | +Here are some more examples: |
| 148 | + |
| 149 | +* deviceId ='linuxprod1' |
| 150 | +* deviceId = 'linuxprod1' OR deviceId = 'linuxprod2' OR deviceId = 'linuxprod3' |
| 151 | +* tags.environment ='prod' |
| 152 | +* tags.environment = 'prod' AND tags.location = 'westus2' |
| 153 | +* tags.environment = 'prod' OR tags.location = 'westus2' |
| 154 | +* tags.operator = 'John' AND tags.environment = 'prod' AND NOT deviceId = 'linuxprod1' |
| 155 | + |
| 156 | +See [target condition](module-deployment-monitoring.md#target-condition) for details. For more information about device twins and tags, see [Understand and use device twins in IoT Hub](../iot-hub/iot-hub-devguide-device-twins.md). |
| 157 | + |
| 158 | +### Edit the device twin |
| 159 | + |
| 160 | +You can edit the device twin in Visual Studio Code to configure the tags. From the **View** menu, select **Command Palette** and run the **IoT Edge: Edit Device Twin** command. Select your IoT Edge device and the device twin appears. |
| 161 | + |
| 162 | +In this example, no tags have been defined. Replace the current empty section `"tags": {}` with your own tags definition. |
| 163 | + |
| 164 | +```json |
| 165 | +{ |
| 166 | + "deviceId": "myEdgeDevice", |
| 167 | + "etag": "AAAAAAAAAAE=", |
| 168 | + "deviceEtag": "NTgwMDg5MDAz", |
| 169 | + "status": "enabled", |
| 170 | + "statusUpdateTime": "0001-01-01T00:00:00Z", |
| 171 | + "connectionState": "Disconnected", |
| 172 | + "lastActivityTime": "0001-01-01T00:00:00Z", |
| 173 | + "cloudToDeviceMessageCount": 0, |
| 174 | + "authenticationType": "sas", |
| 175 | + "x509Thumbprint": { |
| 176 | + "primaryThumbprint": null, |
| 177 | + "secondaryThumbprint": null |
| 178 | + }, |
| 179 | + "version": 2, |
| 180 | + "properties": { |
| 181 | + "desired": { |
| 182 | + "$metadata": { |
| 183 | + "$lastUpdated": "2019-12-29T00:58:49.9315265Z" |
| 184 | + }, |
| 185 | + "$version": 1 |
| 186 | + }, |
| 187 | + "reported": { |
| 188 | + "$metadata": { |
| 189 | + "$lastUpdated": "2019-12-29T00:58:49.9315265Z" |
| 190 | + }, |
| 191 | + "$version": 1 |
| 192 | + } |
| 193 | + }, |
| 194 | + "capabilities": { |
| 195 | + "iotEdge": true |
| 196 | + }, |
| 197 | + "deviceScope": "ms-azure-iot-edge://myEdgeDevice-637131779299315265", |
| 198 | + "tags": {} |
| 199 | +} |
| 200 | +``` |
| 201 | + |
| 202 | +After you save the local file, run the **IoT Edge: Update Device Twin** command. |
| 203 | + |
| 204 | +## Create deployment at scale |
| 205 | + |
| 206 | +After you have configured the deployment manifest and configured tags in the device twin, you're ready to deploy. |
| 207 | + |
| 208 | +1. From the **View** menu, select **Command Palette** and select the **Azure IoT Edge: Create Deployment at Scale** command. |
| 209 | + |
| 210 | +1. Navigate to the deployment manifest JSON file that you want to use, and click **Select Edge Deployment Manifest**. |
| 211 | + |
| 212 | +1. Provide values as prompted, starting with the **deployment id**. |
| 213 | + |
| 214 | +  |
| 215 | + |
| 216 | + Specify values for these parameters: |
| 217 | + |
| 218 | + | Parameter | Description | |
| 219 | + | --- | --- | |
| 220 | + | Deployment id | The name of the deployment that will be created in the IoT hub. Give your deployment a unique name that is up to 128 lowercase letters. Avoid spaces and the following invalid characters: `& ^ [ ] { } \ | " < > /`. | |
| 221 | + | Target condition | Enter a target condition to determine which devices will be targeted with this deployment. The condition is based on device twin tags or device twin reported properties and should match the expression format. For example, `tags.environment='test' and properties.reported.devicemodel='4000x'`. | |
| 222 | + | Priority | A positive integer. If two or more deployments are targeted at the same device, the deployment with the highest numerical value for Priority will apply. | |
| 223 | + |
| 224 | + After specifying the priority, the terminal should display output similar to the following depiction: |
| 225 | + |
| 226 | + ```cmd |
| 227 | + [Edge] Start deployment with deployment id [{specified-value}] and target condition [{specified-value}] |
| 228 | + [Edge] Deployment with deployment id [{specified-value}] succeeded. |
| 229 | + ``` |
| 230 | + |
| 231 | +## Monitoring and modifying deployments |
| 232 | + |
| 233 | +Use the [Azure CLI](how-to-deploy-monitor-cli.md#monitor-a-deployment) or the [Azure portal](how-to-deploy-monitor.md#monitor-a-deployment) to monitor, modify, and delete deployments. Both provide metrics on your deployments. |
| 234 | + |
| 235 | +## Next steps |
| 236 | + |
| 237 | +Learn more about [Deploying modules to IoT Edge devices](module-deployment-monitoring.md). |
0 commit comments