Skip to content

Commit a60a2d0

Browse files
Court72Court72
authored
Merge pull request #292781 from v-thepet/iot7
Freshness Edit: IoT-hub-device 7
2 parents f1fb648 + dbf8136 commit a60a2d0

File tree

6 files changed

+217
-221
lines changed

6 files changed

+217
-221
lines changed

‎articles/iot-hub-device-update/create-update-group.md

Lines changed: 93 additions & 98 deletions
Large diffs are not rendered by default.

‎articles/iot-hub-device-update/deploy-update.md

Lines changed: 97 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,149 +1,153 @@
11
---
2-
title: Deploy an update by using Device Update for Azure IoT Hub | Microsoft Docs
3-
description: Deploy an update by using Device Update for Azure IoT Hub.
2+
title: Deploy an update by using Azure Device Update for IoT Hub | Microsoft Docs
3+
description: Learn how to deploy an update to IoT devices by using Azure Device Update for IoT Hub in the Azure portal or with Azure CLI.
44
author: vimeht
55
ms.author: vimeht
6-
ms.date: 10/31/2022
6+
ms.date: 01/24/2025
77
ms.topic: how-to
88
ms.service: azure-iot-hub
99
ms.custom: devx-track-azurecli
1010
ms.subservice: device-update
1111
---
1212

13-
# Deploy an update by using Device Update for Azure IoT Hub
13+
# Deploy an update by using Azure Device Update for IoT Hub
1414

15-
Learn how to deploy an update to an IoT device by using Device Update for Azure IoT Hub.
15+
In this article, you learn how to deploy an update to IoT devices by using Azure Device Update for IoT Hub in the Azure portal or with Azure CLI.
1616

1717
## Prerequisites
1818

19-
* Access to [an IoT Hub with Device Update for IoT Hub enabled](create-device-update-account.md). We recommend that you use an S1 (Standard) tier or above for your IoT Hub.
20-
* An [imported update for the provisioned device](import-update.md).
21-
* An IoT device (or simulator) provisioned for Device Update within IoT Hub.
22-
* The device is part of at least one default group or [user-created update group](create-update-group.md).
23-
24-
# [Azure portal](#tab/portal)
25-
26-
Supported browsers:
27-
28-
* [Microsoft Edge](https://www.microsoft.com/edge)
29-
* Google Chrome
30-
31-
# [Azure CLI](#tab/cli)
32-
33-
An Azure CLI environment:
34-
35-
* Use the Bash environment in [Azure Cloud Shell](../cloud-shell/quickstart.md).
36-
37-
:::image type="icon" source="~/reusable-content/ce-skilling/azure/media/cloud-shell/launch-cloud-shell-button.png" alt-text="Button to launch the Azure Cloud Shell." border="false" link="https://shell.azure.com":::
38-
39-
* Or, if you prefer to run CLI reference commands locally, [install the Azure CLI](/cli/azure/install-azure-cli)
40-
41-
1. Sign in to the Azure CLI by using the [az login](/cli/azure/reference-index#az-login) command.
42-
2. Run [az version](/cli/azure/reference-index#az-version) to find the version and dependent libraries that are installed. To upgrade to the latest version, run [az upgrade](/cli/azure/reference-index#az-upgrade).
43-
3. When prompted, install Azure CLI extensions on first use. The commands in this article use the **azure-iot** extension. Run `az extension update --name azure-iot` to make sure you're using the latest version of the extension.
44-
45-
>[!TIP]
46-
>The Azure CLI commands in this article use the backslash `\` character for line continuation so that the command arguments are easier to read. This syntax works in Bash environments. If you're running these commands in PowerShell, replace each backslash with a backtick `\``, or remove them entirely.
47-
48-
---
19+
- A Standard (S1) or higher instance of [Azure IoT Hub](/azure/iot-hub/create-hub?tabs=portal) with [Device Update for IoT Hub enabled](create-device-update-account.md).
20+
- An IoT device or simulator [provisioned for Device Update](device-update-agent-provisioning.md) within the IoT hub. The provisioned device can be a member of a [user-created device group](create-update-group.md) or the default group.
21+
- An [imported update for the provisioned device](import-update.md).
4922

5023
## Deploy the update
5124

25+
This section describes how to deploy the update by using the Azure portal or Azure CLI.
26+
5227
# [Azure portal](#tab/portal)
5328

5429
1. In the [Azure portal](https://portal.azure.com), navigate to your IoT hub.
5530

56-
1. Select **Updates** from the navigation menu to open the **Device Update** page of your IoT Hub instance.
31+
1. Select **Updates** under **Device management** in the left navigation.
5732

58-
:::image type="content" source="media/deploy-update/device-update-iot-hub.png" alt-text="Screenshot that shows the Get started with the Device Update for IoT Hub page." lightbox="media/deploy-update/device-update-iot-hub.png":::
33+
:::image type="content" source="media/deploy-update/device-update-iot-hub.png" alt-text="Screenshot that shows the Get started with the Device Update for IoT Hub page." lightbox="media/deploy-update/device-update-iot-hub.png":::
5934

60-
1. Select the **Groups and Deployments** tab at the top of the page. For more information, see [Device groups](device-update-groups.md).
35+
1. On the **Updates** page, select the **Groups and Deployments** tab and view the [update compliance chart](device-update-compliance.md) and [device group list](device-update-groups.md). You might need to refresh the view to see recently imported updates available for your device group.
6136

62-
![Screenshot of the compliance view for Groups and Deployments.](media/deploy-update/compliance-1.png)
63-
64-
37+
1. Under **Status** in the group list, select **Deploy** next to **One or more new updates are available for this group**.
38+
39+
:::image type="content" source="media/deploy-update/compliance-1.png" alt-text="Screenshot of the compliance view for Groups and Deployments." lightbox="media/deploy-update/compliance-1.png":::
6540

6641
1. View the update compliance chart and group list. You should see a new update available for your tag based or default group. You might need to refresh once. For more information, see [Device Update compliance](device-update-compliance.md).
6742

68-
1. Select Deploy next to the **one or more updates available** status.
43+
1. Select **Deploy** next to the **one or more updates available** status.
6944

7045
1. From the list on the right, select the desired update to deploy.
7146

72-
![Screenshot of the deployment view for selecting updates.](media/deploy-update/deploy-3.png)
47+
:::image type="content" source="media/deploy-update/deploy-3.png" alt-text="Screenshot of the deployment view for selecting updates." lightbox="media/deploy-update/deploy-3.png":::
7348

7449
1. Schedule your deployment to start immediately or in the future.
7550

7651
> [!TIP]
77-
> By default, the **Start** date and time is set to Immediately. Be sure to select a different date and time if you want the deployment to begin later.
52+
> By default, the **Start** date and time is 24 hours from your current time. Be sure to select a different date and time if you want the deployment to begin sooner or later.
7853
7954
:::image type="content" source="media/deploy-update/create-deployment.png" alt-text="Screenshot that shows the Create deployment screen" lightbox="media/deploy-update/create-deployment.png":::
8055

8156
1. Create an automatic rollback policy if needed. Then select **Create**.
8257

83-
1. In the Current Updates tab, you can view the status of your deployment.
58+
1. In the **Current updates** tab, you can view the status of your deployment.
8459

85-
![A screenshot of the Current Updates view.](media/deploy-update/current-updates-4.png)
60+
:::image type="content" source="media/deploy-update/current-updates-4.png" alt-text="A screenshot of the Current updates view." lightbox="media/deploy-update/current-updates-4.png":::
8661

87-
1. In the Groups Basics view, the compliance chart shows that the update is now in progress.
62+
1. In the **Group basics** view, the compliance chart shows that the update is now in progress.
8863

89-
1. After your device is successfully updated, you see that your compliance chart and deployment details updated to reflect the same.
64+
After your device successfully updates, your compliance chart and deployment details update to reflect that status.
9065

9166
# [Azure CLI](#tab/cli)
9267

93-
68+
You can use the Bash environment in [Azure Cloud Shell](/azure/cloud-shell/quickstart) to run the following commands. Select **Launch Cloud Shell** to open Cloud Shell, or select the Cloud Shell icon in the top toolbar of the Azure portal.
9469

95-
The [`az iot du device group list`](/cli/azure/iot/du/device/group#az-iot-du-device-group-list) to verify the best available update for your group. The command takes the following arguments:
70+
:::image type="icon" source="~/reusable-content/ce-skilling/azure/media/cloud-shell/launch-cloud-shell-button.png" alt-text="Button to launch the Azure Cloud Shell." border="false" link="https://shell.azure.com":::
9671

97-
* `--account`: The Device Update account name.
98-
* `--instance`: The Device Update instance name.
99-
* `--group-id`: The device group ID that you're targeting with this deployment. This ID is the value of the **ADUGroup** tag, or `$default` for devices with no tag.
100-
* `--best-updates`: This flag indicates the command should fetch the best available updates for the device group including a count of how many devices need each update.
101-
* `--resource-group -g': Device Update account resource group name.
102-
* '--update-compliance': This flag indicates the command should fetch device group update compliance information such as how many devices are on their latest update, how many need new updates, and how many are in progress on receiving a new update.
72+
Or, if you prefer, you can run the Azure CLI commands locally:
10373

104-
```azurecli
105-
az iot du device group list \
106-
--account <Device Update account name> \
107-
--instance <Device Update instance name>\
108-
--gid <device group id>\
109-
--best-updates {false, true}
110-
```
74+
1. [Install Azure CLI](/cli/azure/install-azure-cli). Run [az version](/cli/azure/reference-index#az-version) to see the installed Azure CLI version and dependent libraries, and run [az upgrade](/cli/azure/reference-index#az-upgrade) to install the latest version.
75+
1. Sign in to Azure by running [az login](/cli/azure/reference-index#az-login).
76+
1. Install the `azure-iot` extension when prompted on first use. To make sure you're using the latest version of the extension, run `az extension update --name azure-iot`.
77+
78+
>[!TIP]
79+
>The Azure CLI commands in this article use the backslash \\ character for line continuation so that the command arguments are easier to read. This syntax works in Bash environments. If you run these commands in PowerShell, replace each backslash with a backtick \`, or remove them entirely.
11180
112-
Use [az iot du device deployment create](/cli/azure/iot/du/device/deployment#az-iot-du-device-deployment-create) to create a deployment for a device group.
81+
### Verify update availability
11382

114-
The `device deployment create` command takes the following arguments:
83+
1. Use the [`az iot du device group list`](/cli/azure/iot/du/device/group#az-iot-du-device-group-list) command to identify your device group.
11584

116-
* `--account`: The Device Update account name.
117-
* `--instance`: The Device Update instance name.
118-
* `--group-id`: The device group ID that you're targeting with this deployment. This ID is the value of the **ADUGroup** tag, or `$default` for devices with no tag.
119-
* `--deployment-id`: An ID to identify this deployment.
120-
* `--update-name`, `--update-provider`, and `--update-version`: These three parameters define the **updateId** object that is a unique identifier for the update that you're using in this deployment.
85+
```azurecli
86+
az iot du device group list \
87+
--account <Device Update account name> \
88+
--instance <Device Update instance name>\
89+
```
90+
91+
1. Then use [`az iot du device group show`](/cli/azure/iot/du/device/group#az-iot-du-device-group-show) to show the best available update for your group. The command takes the following arguments:
92+
93+
- `--account`: The Device Update account name.
94+
- `--instance`: The Device Update instance name.
95+
- `--group-id`: The device group ID that you're targeting with this deployment, which is either the value of the `ADUGroup` tag, or `$default` for devices with no tag.
96+
- `--resource-group`: The Device Update account resource group name.
97+
- `--best-updates`: Returns the best available updates for the device group, including a count of how many devices need each update.
98+
- `--update-compliance`: Returns device group update compliance information, such as how many devices are on their latest update, how many need new updates, and how many are currently receiving a new update.
99+
100+
To verify the best available update for your group, run the command as follows:
101+
102+
```azurecli
103+
az iot du device group show \
104+
--account <Device Update account name> \
105+
--instance <Device Update instance name>\
106+
--group-id <device group ID>\
107+
--best-updates
108+
```
109+
110+
### Create the deployment
111+
112+
Use [`az iot du device deployment create`](/cli/azure/iot/du/device/deployment#az-iot-du-device-deployment-create) to create a deployment for the device group. The command takes the following arguments:
113+
114+
- `--account`: The Device Update account name.
115+
- `--instance`: The Device Update instance name.
116+
- `--group-id`: The device group ID that you're targeting with this deployment, which is either the value of the `ADUGroup` tag, or `$default` for devices with no tag.
117+
- `--deployment-id`: An ID to identify this deployment.
118+
- `--update-name`, `--update-provider`, and `--update-version`: The parameters that define the `updateId` object, a unique identifier for the update in this deployment.
119+
120+
Run the command as follows:
121121

122122
```azurecli
123123
az iot du device deployment create \
124124
--account <Device Update account name> \
125125
--instance <Device Update instance name> \
126-
--group-id <device group id> \
127-
--deployment-id <deployment id> \
126+
--group-id <device group ID> \
127+
--deployment-id <deployment ID> \
128128
--update-name <update name> \
129129
--update-provider <update provider> \
130130
--update-version <update version>
131131
```
132132

133-
Optional arguments allow you to configure the deployment. For the full list, see [Optional parameters](/cli/azure/iot/du/device/deployment#az-iot-du-device-deployment-create-optional-parameters)
133+
### Use optional arguments
134134

135-
If you want to create an automatic rollback policy, add the following parameters:
135+
Optional arguments allow you to further configure the deployment. For the full list of optional arguments, see [Optional parameters](/cli/azure/iot/du/device/deployment#az-iot-du-device-deployment-create-optional-parameters).
136136

137-
* `--failed-count`: The number of failed devices in a deployment that will trigger a rollback.
138-
* `--failed-percentage`: The percentage of failed devices in a deployment that will trigger a rollback.
139-
* `--rollback-update-name`, `--rollback-update-provider`, `--rollback-update-version`: The updateID for the update that the device group will use if a rollback is initiated.
137+
To create an automatic rollback policy, add the following parameters:
138+
139+
- `--failed-count`: The number of failed devices in a deployment that triggers a rollback.
140+
- `--failed-percentage`: The percentage of failed devices in a deployment that triggers a rollback.
141+
- `--rollback-update-name`, `--rollback-update-provider`, `--rollback-update-version`: The parameters for the update to use if a rollback is initiated.
142+
143+
Run the command as follows:
140144

141145
```azurecli
142146
az iot du device deployment create \
143147
--account <Device Update account name> \
144148
--instance <Device Update instance name> \
145-
--group-id <device group id> \
146-
--deployment-id <deployment id> \
149+
--group-id <device group ID> \
150+
--deployment-id <deployment ID> \
147151
--update-name <update name> \
148152
--update-provider <update provider> \
149153
--update-version <update version> \
@@ -154,7 +158,7 @@ az iot du device deployment create \
154158
--rollback-update-version <rollback update version>
155159
```
156160

157-
If you want the deployment to start in the future, use the `--start-time` parameter to provide the target datetime for the deployment.
161+
To set the deployment start time, use the `--start-time` parameter to provide the target date and time for the deployment, as follows:
158162

159163
```azurecli
160164
az iot du device deployment create \
@@ -170,25 +174,27 @@ az iot du device deployment create \
170174

171175
---
172176

173-
## Monitor an update deployment
177+
## Monitor deployment status
174178

175179
# [Azure portal](#tab/portal)
176180

177-
1. Select the group you deployed to, and go to the **Current updates** or **Deployment history** tab to confirm that the deployment is in progress
181+
1. On the **Groups and Deployments** tab of the **Updates** page, select the group you deployed to.
178182

179-
:::image type="content" source="media/deploy-update/deployments-history.png" alt-text="Screenshot that shows the Deployment history tab." lightbox="media/deploy-update/deployments-history.png":::
183+
1. On the **Group details** page, go to the **Current deployment** or **Deployment history** tab to confirm that a deployment is in progress.
180184

181-
1. Select **Details** next to the deployment you created. Here you can view the deployment details, update details, and target device class details. You can optionally add a friendly name for the device class.
185+
:::image type="content" source="media/deploy-update/deployments-history.png" alt-text="Screenshot that shows the Deployment history tab." lightbox="media/deploy-update/deployments-history.png":::
182186

183-
:::image type="content" source="media/deploy-update/deployment-details.png" alt-text="Screenshot that shows deployment details." lightbox="media/deploy-update/deployment-details.png":::
187+
1. Select **Details** next to a deployment to view the deployment details, update details, and target device class details. You can optionally add a friendly name for the device class.
184188

185189
1. Select **Refresh** to view the latest status details.
186190

187-
1. You can go to the group basics view to search the status for a particular device, or filter to view devices that have failed the deployment
191+
:::image type="content" source="media/deploy-update/deployment-details.png" alt-text="Screenshot that shows deployment details." lightbox="media/deploy-update/deployment-details.png":::
192+
193+
Go to the **Group basics** tab of the **Group details** page to search for the status of a particular device, or filter to view devices that failed the deployment.
188194

189195
# [Azure CLI](#tab/cli)
190196

191-
Use [az iot du device deployment list](/cli/azure/iot/du/device/deployment#az-iot-du-device-deployment-list) to view all deployment for a device group.
197+
Use [az iot du device deployment list](/cli/azure/iot/du/device/deployment#az-iot-du-device-deployment-list) to view all deployments for a device group.
192198

193199
```azurecli
194200
az iot du device deployment list \
@@ -222,14 +228,12 @@ az iot du device deployment show \
222228

223229
## Retry an update deployment
224230

225-
If your deployment fails for some reason, you can retry the deployment for failed devices.
231+
If your deployment fails, you can retry the deployment for failed devices.
226232

227233
# [Azure portal](#tab/portal)
228234

229235
1. Go to the **Current deployment** tab on the **Group details** screen.
230236

231-
:::image type="content" source="media/deploy-update/deployment-active.png" alt-text="Screenshot that shows the deployment as Active." lightbox="media/deploy-update/deployment-active.png":::
232-
233237
1. Select **Retry failed devices** and acknowledge the confirmation notification.
234238

235239
# [Azure CLI](#tab/cli)
@@ -249,6 +253,7 @@ az iot du device deployment retry \
249253

250254
---
251255

252-
## Next steps
256+
## Related content
253257

254-
[Troubleshoot common issues](troubleshoot-device-update.md)
258+
- [Device Update deployments](device-update-deployments.md)
259+
- [Device Update Troubleshooting Guide](troubleshoot-device-update.md)

0 commit comments

Comments
 (0)