Merge pull request #290686 from v-thepet/iot2

Freshness Edit: IoT-hub-device 2

Author: denrea

articles/iot-hub-device-update/create-device-update-account.md

@@ -1,124 +1,143 @@
 ---
-title: Create an account for Device Update for Azure IoT Hub
-description: Create a device update account and instance in Device Update for Azure IoT Hub using the Azure portal or CLI.
+title: Create Azure Device Update for IoT Hub resources
+description: Create an Azure Device Update for Iot Hub account and instance by using the Azure portal or Azure CLI.
 author: eshashah-msft
 ms.author: eshashah
-ms.date: 10/30/2022
+ms.date: 12/06/2024
 ms.topic: how-to
 ms.service: azure-iot-hub
 ms.subservice: device-update
 ---
 
-# Create Device Update for IoT Hub resources
+# Create Azure Device Update for IoT Hub resources
 
-To get started with Device Update, create a Device Update account and instance, and then set access control roles.
+To get started with Azure Device Update for IoT Hub, you create a Device Update account and instance, and then [assign access control roles and permissions](configure-access-control-device-update.md) necessary to use those resources. This article describes how to create and configure the Device Update resources by using the Azure portal or Azure CLI.
 
-A Device Update account is a resource in your Azure subscription. A Device Update instance is a logical container within an account that is associated with a specific IoT hub. An instance contains updates and deployments associated with its IoT hub. You can create multiple instances within an account. For more information, see [Device Update resources](device-update-resources.md).
+A Device Update *account* is a resource in your Azure subscription. A Device Update *instance* is a logical container within the account that's associated with a specific IoT hub. You can create multiple Device Update instances within an account.
+
+A Device Update instance contains updates and deployments associated with its IoT hub. For more information, see [Device Update resources](device-update-resources.md).
 
 ## Prerequisites
 
 # [Azure portal](#tab/portal)
 
-An IoT hub. It's required that you use an S1 (Standard) tier or above.
+- A Standard (S1) or higher instance of [Azure IoT Hub](/azure/iot-hub/create-hub?tabs=portal).
+- If you opt to store diagnostic logs, an Azure Storage account to store diagnostics logs for your Device Update instance.
 
 # [Azure CLI](#tab/cli)
 
-* An IoT hub. It's required that you use an S1 (Standard) tier or above.
+- A Standard (S1) or higher instance of [Azure IoT Hub](/azure/iot-hub/create-hub?tabs=portal).
+- The Bash environment in [Azure Cloud Shell](/azure/cloud-shell/quickstart) for running Azure CLI commands. Select **Launch Cloud Shell** to open Cloud Shell now, or select the Cloud Shell icon in the top toolbar of the Azure portal.
 
-* An Azure CLI environment:
+  :::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":::
 
-  * Use the Bash environment in [Azure Cloud Shell](../cloud-shell/quickstart.md).
+  If you prefer, you can run the Azure CLI commands locally:
+  
+  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.
+  1. Sign in to Azure by running [az login](/cli/azure/reference-index#az-login).
+  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`.
 
-    :::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":::
+---
 
-  * Or, if you prefer to run CLI reference commands locally, [install the Azure CLI](/cli/azure/install-azure-cli)
+## Create a Device Update account and instance
 
-    * Sign in to the Azure CLI by using the [az login](/cli/azure/reference-index#az-login) command.
+# [Azure portal](#tab/portal)
 
-    * 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).
- 
-    * 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.
+1. In the [Azure portal](https://portal.azure.com), search for and select **Device Update for IoT Hubs**.
+1. On the **Device Update for IoT Hubs** screen, select **Create** or **Create Device Update for IoT Hub**.
 
----
+   :::image type="content" source="media/create-device-update-account/device-update-marketplace.png" alt-text="Screenshot of Device Update for IoT Hub resource.":::
 
-## Create an account and instance
+1. On the **Basics** tab of the **Create Device Update** screen, provide the following information:
 
-# [Azure portal](#tab/portal)
+   - **Subscription**: Select the name of the Azure subscription for your Device Update account.
+   - **Resource group**: Select an existing resource group or create a new one.
+   - **Name**: Provide a name for your Device Update account.
+   - **Location**: Select the Azure region for your account. For more information, see [Products available by region](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/).
+   - **SKU**: Select **Standard**.
+   - **Grant Access to Account**
+     - If you have **Owner** or **User Access Administrator** permissions in your Azure subscription, you can select the **Assign Device Update Administrator role** checkbox to assign yourself the **Device Update Administrator** role for this account.
+     - If you don't have these permissions, contact your administrator after resource creation to get the necessary permissions to work with these resources. For more information, see [Configure access control roles for Device Update resources](configure-access-control-device-update.md).
+   - **Instance Name**: Provide a name for your Device Update instance.
+   - **IoT Hub Name**: Select the IoT Hub you want to link to your Device Update instance.
+   - **Grant Access to IoT Hub**: Device Update setup automatically assigns IoT Hub Data Contributor role to the Device Update service principal.
 
-1. In the [Azure portal](https://portal.azure.com), select **Create a Resource** and search for "Device Update for IoT Hub"
+   :::image type="content" source="media/create-device-update-account/account-details.png" alt-text="Screenshot of account details for a new Device Update account.":::
 
-2. Select **Create** > **Device Update for IoT Hub**
+1. Optionally, select **Next: Diagnostics** or the **Diagnostics** tab to configure diagnostics logging as part of the instance creation process. Enabling Microsoft diagnostics allows Microsoft to collect, store, and analyze diagnostic log files from your devices if they encounter an update failure.
 
-   :::image type="content" source="media/create-device-update-account/device-update-marketplace.png" alt-text="Screenshot of Device Update for IoT Hub resource." lightbox="media/create-device-update-account/device-update-marketplace.png":::
+   If you don't want to enable diagnostics logging now, select the **Networking** tab.
 
-3. On the **Basics** tab, provide the following information for your Device Update account and instance:
+1. To configure diagnostics logging, on the **Diagnostics** tab, slide the toggle to **Microsoft diagnostics logging Enabled**.
 
-   * **Subscription**: The Azure subscription to be associated with your Device Update account.
-   * **Resource group**: An existing or new resource group.
-   * **Name**: A name for your account.
-   * **Location**: The Azure region where your account will be located. For information about which regions support Device Update for IoT Hub, see [Azure Products-by-region page](https://azure.microsoft.com/global-infrastructure/services/?products=iot-hub).
-   * Check the box to assign the Device Update administrator role to yourself. You can also use the steps listed in the [Configure access control roles](configure-access-control-device-update.md) section to provide a combination of roles to users and applications for the right level of access. You need to have Owner or User Access Administrator permissions in your subscription to manage roles.
-   * **Instance Name**: A name for your instance.
-   * **IoT Hub Name**: Select the IoT Hub you want to link to your Device Update instance
-   * Check the box to grant the right access to Azure Device Update service principal in the IoT Hub to set up and operate the Device Update Service. You need to have the right permissions to add access. 
-   > [!NOTE]
-   > If you are unable to grant access to Azure Device Update service principal during resource creation, refer to [configure the access control for users and Azure Device Update service principal](configure-access-control-device-update.md) . If this access is not set you will not be able to run deployment, device management and diagnostic operations. Learn more about the [Azure Device Update service principal access](device-update-control-access.md#configuring-access-for-azure-device-update-service-principal-in-the-iot-hub).
+1. Select **Select Azure Storage Account** and then select an Azure Blob storage account to link to your Device Update instance for remote diagnostic log collection. The Storage account details update automatically.
 
-   :::image type="content" source="media/create-device-update-account/account-details.png" alt-text="Screenshot of account details for a new Device Update account." lightbox="media/create-device-update-account/account-details.png":::
+   :::image type="content" source="media/create-device-update-account/account-diagnostics.png" alt-text="Screenshot of diagnostic details.":::
 
-4. Select **Next: Diagnostics**. Enabling Microsoft diagnostics, gives Microsoft permission to collect, store, and analyze diagnostic log files from your devices when they encounter an update failure. In order to enable remote log collection for diagnostics, you need to link your Device Update instance to your Azure Blob storage account. Selecting the Azure Storage account will automatically update the storage details.
+1. Select the **Networking** tab or **Next: Networking**.
 
-   :::image type="content" source="media/create-device-update-account/account-diagnostics.png" alt-text="Screenshot of diagnostic details." lightbox="media/create-device-update-account/account-diagnostics.png":::
+1. On the **Networking** tab, you can choose the endpoints that devices use to connect to your Device Update instance. For this example, select **Public access**. Public access is acceptable for development and testing purposes, but for production scenarios, you should choose **Private access** and [configure private endpoint connections](configure-private-endpoints.md).
 
-5. On the **Networking** tab, to continue creating Device Update account and instance.
-   Choose the endpoints that devices can use to connect to your Device Update instance. Accept the default setting, Public access, for this example.
+1. Select **Review**.
 
-   :::image type="content" source="media/create-device-update-account/account-networking.png" alt-text="Screenshot of networking details." lightbox="media/create-device-update-account/account-networking.png":::
+   :::image type="content" source="media/create-device-update-account/account-networking.png" alt-text="Screenshot of networking details.":::
 
-6. Select **Next: Review + Create**. After validation, select **Create**.
+1. On the **Review** tab, review the details, and when validation passes, select **Create**.
 
-   :::image type="content" source="media/create-device-update-account/account-review.png" alt-text="Screenshot of account review." lightbox="media/create-device-update-account/account-review.png":::
+   :::image type="content" source="media/create-device-update-account/account-review.png" alt-text="Screenshot of account review.":::
 
-7. You'll see that your deployment is in progress. The deployment status will change to "complete" in a few minutes. When it does, select **Go to resource**
+1. The screen changes to show that your deployment is in progress. When the deployment completes, select **Go to resource**.
 
 # [Azure CLI](#tab/cli)
 
-Use the [az iot du account create](/cli/azure/iot/du/account#az-iot-du-account-create) command to create a new Device Update account.
+1. Run [az iot du account create](/cli/azure/iot/du/account#az-iot-du-account-create) to create a new Device Update account.
+
+   ```azurecli
+   az iot du account create --resource-group <resource_group> --account <account_name> --location <region>
+   ```
 
-Replace the following placeholders with your own information:
+   In the command, replace the following placeholders with your own information:
 
-* *\<resource_group>*: An existing resource group in your subscription.
-* *\<account_name>*: A name for your Device Update account.
-* *\<region>*: The Azure region where your account will be located. For information about which regions support Device Update for IoT Hub, see [Azure Products-by-region page](https://azure.microsoft.com/global-infrastructure/services/?products=iot-hub). If no region is provided, the resource group's location is used.
+   - `<resource_group>`: An existing resource group in your subscription.
+   - `<account_name>`: A name for your Device Update account.
+   - `<region>`: The Azure region for your account. For more information, see [Products available by region](https://azure.microsoft.com/explore/global-infrastructure/products-by-region/). If you don't provide a region, setup uses the resource group location.
 
-   > [!NOTE]
-   > Your Device Update account doesn't need to be in the same region as your IoT hubs, but for better performance it is recommended that you keep them geographically close.
+     > [!NOTE]
+     > Your Device Update account doesn't need to be in the same region as your IoT hub, but for better performance it should be geographically close.
 
-```azurecli-interactive
-az iot du account create --resource-group <resource_group> --account <account_name> --location <region>
-```
+1. If prompted, respond `y` to install the `azure-iot` Azure CLI extension.
 
-Use the [az iot du instance create](/cli/azure/iot/du/instance#az-iot-du-instance-create) command to create a Device Update instance.
+1. A Device Update instance is associated with a single IoT hub. Run [az iot du instance create](/cli/azure/iot/du/instance#az-iot-du-instance-create) to create a Device Update instance and specify the IoT hub to use with the instance.
 
-An *instance* of Device Update is associated with a single IoT hub. Select the IoT hub that will be used with Device Update. When you link an IoT hub to a Device Update instance, a new shared access policy is automatically created give Device Update permissions to work with IoT Hub (registry write and service connect). This policy ensures that access is only limited to Device Update.
+   ```azurecli
+   az iot du instance create --account <account_name> --instance <instance_name> --iothub-ids <iothub_id>
+   ```
 
-Replace the following placeholders with your own information:
 
-* *\<account_name>*: The name of the Device Update account that this instance will be associated with.
-* *\<instance_name>*: A name for this instance.
-* *\<iothub_id>*: The resource ID for the IoT hub that will be linked to this instance. You can retrieve your IoT hub resource ID by using the [az iot hub show](/cli/azure/iot/hub#az-iot-hub-show) command and querying for the ID value: `az iot hub show -n <iothub_name> --query id`.
+   In the command, replace the following placeholders with your own information:
 
-```azurecli-interactive
-az iot du instance create --account <account_name> --instance <instance_name> --iothub-ids <iothub_id>
-```
+   - `<account_name>`: The name of the Device Update account for this instance.
+   - `<instance_name>`: A name for this instance.
+   - `<iothub_id>`: The fully qualified resource ID for the IoT hub to link to this instance, such as `"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Devices/IotHubs/<iothub_name>"`.
 
->[!TIP]
->As part of the instance creation process, you can also configure diagnostics logging. For more information, see [Remotely collect diagnostic logs from devices](device-update-log-collection.md).
+     To get your IoT hub resource ID, run [az iot hub show](/cli/azure/iot/hub#az-iot-hub-show) and query for the ID value.
+
+     ```azurecli
+     az iot hub show -n <iothub_name> --query id
+     ```
+
+You can also configure diagnostics logging as part of the instance creation process. You must have an Azure Blob Storage account to store the diagnostic logs. For more information, see [Remotely collect diagnostic logs from devices](device-update-log-collection.md?tabs=cli).
 
 ---
 
 ## Next steps
 
-Once you have created your Device Update resources, [configure the access control for users and Azure Device Update service principal](configure-access-control-device-update.md).
+Device Update setup automatically assigns **IoT Hub Data Contributor** role to the Device Update service principal. This role allows only this Device Update instance to connect and write to the linked IoT hub to run update deployment, device management, and diagnostic operations.
+
+If you have **Owner** or **User Access Administrator** permissions in your Azure subscription, you can configure access control by providing users and applications the necessary level of access to the Device Update resources you created. If you don't have **Owner** or **User Access Administrator** permissions, ask your Device Update administrator to grant you the access and permissions you need to perform Device Update update, management, and diagnostic operations. For more information, see [Configure access control roles for Device Update resources](configure-access-control-device-update.md).
+
+## Related content
+
+- [Device Update accounts and instances](device-update-resources.md)
+- [Device Update access control roles](device-update-control-access.md)
 
-Or, learn more about [Device Update accounts and instances](device-update-resources.md) or [Device Update access control roles](device-update-control-access.md).