Skip to content

Commit 1745d61

Browse files
v-thepetv-thepet
committed
deploy update
1 parent 72dad6e commit 1745d61

File tree

2 files changed

+90
-85
lines changed

2 files changed

+90
-85
lines changed

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

Lines changed: 90 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,127 +1,125 @@
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 an IoT device 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/07/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 a device update by using Device Update for Azure 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 an IoT device 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.
21+
- An [imported update for the provisioned device](import-update.md).
22+
- Membership of the device in at least one [user-created update group](create-update-group.md) or default group.
4923

5024
## Deploy the update
5125

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

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

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

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":::
34+
:::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":::
5935

60-
1. Select the **Groups and Deployments** tab at the top of the page. For more information, see [Device groups](device-update-groups.md).
36+
1. Select the **Groups and Deployments** tab at the top of the page, and view the [update compliance chart](device-update-compliance.md) and [device group list](device-update-groups.md). You should see a new update available for your device group. You might need to refresh the view.
6137

6238
:::image type="content" source="media/deploy-update/updated-view.png" alt-text="Screenshot that shows the Groups and Deployments tab." lightbox="media/deploy-update/updated-view.png":::
6339

64-
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).
65-
66-
1. Select Deploy next to the **one or more updates available**, and confirm that the descriptive label you added when importing is present and looks correct.
40+
1. Under **Status** in the group list, select **Deploy** next to **One or more new updates are available for this group**.
6741

68-
1. Confirm that the correct group is selected as the target group and select **Deploy**.
69-
70-
1. To start the deployment, go to the **Current deployment** tab. Select the **Deploy** link next to the desired update from the **Available updates** section. The best available update for a given group is denoted with a **Best** highlight.
42+
1. On the **Group details** page, confirm that the correct group and imported update appear. To start the deployment, on the **Current deployment** tab, select the **Deploy** link next to the desired update from the **Available updates** section. The best available update for a given group is denoted with a **Best** highlight.
7143

7244
:::image type="content" source="media/deploy-update/select-update.png" alt-text="Screenshot that shows Best highlighted." lightbox="media/deploy-update/select-update.png":::
7345

74-
1. Schedule your deployment to start immediately or in the future.
46+
1. On the **Create deployment** page, schedule your deployment to start immediately or at a future time. Create an automatic rollback policy if necessary, and then select **Create**.
7547

48+
<!-- > [!TIP]
49+
> 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.
50+
-->
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.
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

81-
1. Create an automatic rollback policy if needed. Then select **Create**.
82-
8356
1. In the deployment details, **Status** turns to **Active**. The deployed update is marked with **(deploying)**.
8457

8558
:::image type="content" source="media/deploy-update/deployment-active.png" alt-text="Screenshot that shows deployment as Active." lightbox="media/deploy-update/deployment-active.png":::
8659

87-
1. View the compliance chart to see that the update is now in progress.
60+
1. On the **Updates** page, view the compliance chart to see that the update is now in progress.
8861

8962
:::image type="content" source="media/deploy-update/update-in-progress.png" alt-text="Screenshot that shows Updates in progress." lightbox="media/deploy-update/update-in-progress.png":::
9063

91-
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.
9265

9366
:::image type="content" source="media/deploy-update/update-succeeded.png" alt-text="Screenshot that shows the update succeeded." lightbox="media/deploy-update/update-succeeded.png":::
9467

9568
# [Azure CLI](#tab/cli)
9669

97-
70+
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.
9871

99-
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:
72+
:::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":::
10073

101-
* `--account`: The Device Update account name.
102-
* `--instance`: The Device Update instance name.
103-
* `--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.
104-
* `--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.
105-
* `--resource-group -g': Device Update account resource group name.
106-
* '--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.
74+
Or, if you prefer, you can run the Azure CLI commands locally:
10775

108-
```azurecli
109-
az iot du device group list \
110-
--account <Device Update account name> \
111-
--instance <Device Update instance name>\
112-
--gid <device group id>\
113-
--best-updates {false, true}
76+
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.
77+
1. Sign in to Azure by running [az login](/cli/azure/reference-index#az-login).
78+
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`.
79+
80+
>[!TIP]
81+
>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.
82+
83+
### Verify the update
84+
85+
1. Use the [`az iot du device group list`](/cli/azure/iot/du/device/group#az-iot-du-device-group-list) command to find your device group information.
86+
87+
```azurecli
88+
az iot du device group list \
89+
--account <Device Update account name> \
90+
--instance <Device Update instance name>\
11491
```
11592

116-
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.
93+
1. Then use [`az iot du device group show`](/cli/azure/iot/du/device/group#az-iot-du-device-group-show) to verify the best available update for your group. The command takes the following arguments:
94+
95+
- `--account`: The Device Update account name.
96+
- `--instance`: The Device Update instance name.
97+
- `--resource-group`: Device Update account resource group name.
98+
- `--group-id`: The device group ID that you're targeting with this deployment, either the value of the `ADUGroup` tag, or `$default` for devices with no tag.
99+
- `--best-updates`: Fetches the best available updates for the device group, including a count of how many devices need each update.
100+
- `--update-compliance`: Fetches 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.
101+
102+
Run the command as follows:
103+
104+
```azurecli
105+
az iot du device group show \
106+
--account <Device Update account name> \
107+
--instance <Device Update instance name>\
108+
--gid <device group id>\
109+
--best-updates
110+
```
111+
112+
### Create the deployment
117113

118-
The `device deployment create` command takes the following arguments:
114+
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:
119115

120-
* `--account`: The Device Update account name.
121-
* `--instance`: The Device Update instance name.
122-
* `--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.
123-
* `--deployment-id`: An ID to identify this deployment.
124-
* `--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.
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, either 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`: The parameters that define the `updateId` object, a unique identifier for the update in this deployment.
121+
122+
Run the command as follows:
125123

126124
```azurecli
127125
az iot du device deployment create \
@@ -134,13 +132,17 @@ az iot du device deployment create \
134132
--update-version <update version>
135133
```
136134

137-
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)
135+
### Use optional arguments
136+
137+
Optional arguments allow you to 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).
138138

139-
If you want to create an automatic rollback policy, add the following parameters:
139+
To create an automatic rollback policy, add the following parameters:
140140

141-
* `--failed-count`: The number of failed devices in a deployment that will trigger a rollback.
142-
* `--failed-percentage`: The percentage of failed devices in a deployment that will trigger a rollback.
143-
* `--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.
141+
- `--failed-count`: The number of failed devices in a deployment that triggers a rollback.
142+
- `--failed-percentage`: The percentage of failed devices in a deployment that triggers a rollback.
143+
- `--rollback-update-name`, `--rollback-update-provider`, `--rollback-update-version`: The parameters for the update to use if a rollback is initiated.
144+
145+
Run the command as follows:
144146

145147
```azurecli
146148
az iot du device deployment create \
@@ -158,7 +160,7 @@ az iot du device deployment create \
158160
--rollback-update-version <rollback update version>
159161
```
160162

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

163165
```azurecli
164166
az iot du device deployment create \
@@ -174,25 +176,27 @@ az iot du device deployment create \
174176

175177
---
176178

177-
## Monitor an update deployment
179+
## Monitor deployment status
178180

179181
# [Azure portal](#tab/portal)
180182

181-
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
183+
1. On the **Groups and Deployments** tab of the **Updates** page, select the group you deployed to.
184+
185+
1. On the **Group details** page, go to the **Current deployment** or **Deployment history** tab to confirm that a deployment is in progress.
182186

183187
:::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":::
184188

185-
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.
189+
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.
186190

187191
:::image type="content" source="media/deploy-update/deployment-details.png" alt-text="Screenshot that shows deployment details." lightbox="media/deploy-update/deployment-details.png":::
188192

189193
1. Select **Refresh** to view the latest status details.
190194

191-
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
195+
1. Go to the **Group basics** tab of the **Group details** page to search the status for a particular device, or filter to view devices that failed the deployment.
192196

193197
# [Azure CLI](#tab/cli)
194198

195-
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.
199+
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.
196200

197201
```azurecli
198202
az iot du device deployment list \
@@ -226,7 +230,7 @@ az iot du device deployment show \
226230

227231
## Retry an update deployment
228232

229-
If your deployment fails for some reason, you can retry the deployment for failed devices.
233+
If your deployment fails, you can retry the deployment for failed devices.
230234

231235
# [Azure portal](#tab/portal)
232236

@@ -253,6 +257,7 @@ az iot du device deployment retry \
253257

254258
---
255259

256-
## Next steps
260+
## Related content
257261

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

‎articles/iot-hub-device-update/media/deploy-update/device-update-iot-hub.png

-194 KB
Loading

0 commit comments

Comments
 (0)