|
| 1 | +--- |
| 2 | +title: How to migrate an IoT hub |
| 3 | +titleSuffix: Azure IoT Hub |
| 4 | +description: Use the Azure CLI iot hub state command group to migrate an IoT hub to a new region, a new tier, or a new configuration |
| 5 | +author: kgremban |
| 6 | + |
| 7 | +ms.author: kgremban |
| 8 | +ms.service: iot-hub |
| 9 | +ms.topic: how-to |
| 10 | +ms.date: 03/02/2023 |
| 11 | +--- |
| 12 | + |
| 13 | +# How to automatically migrate an IoT hub using the Azure CLI |
| 14 | + |
| 15 | +Use the Azure CLI to migrate an IoT hub to a new region, a new tier, or a new configuration. |
| 16 | + |
| 17 | +The steps in this article are useful if you want to: |
| 18 | + |
| 19 | +* Upgrade from the free tier to a basic or standard tier IoT hub. |
| 20 | +* Move an IoT hub to a new region. |
| 21 | +* Export IoT hub state information to have as a backup. |
| 22 | +* Increase the number of partitions for an IoT hub. |
| 23 | + |
| 24 | +## Compare automatic and manual migration steps |
| 25 | + |
| 26 | +The outcome of this article is similar to [How to clone an Azure IoT hub to another region](iot-hub-how-to-clone.md), but with a different process. Before you begin, decide which process is right for your scenario. |
| 27 | + |
| 28 | +* The Azure CLI process: |
| 29 | + * Migrates your device registry, your routing and endpoint information, and additional configuration details like IoT Edge deployments or automatic device management configurations. |
| 30 | + * Is easier for migrating small numbers of devices (for example, up to 10,000). |
| 31 | + * Doesn't require an Azure Storage account. |
| 32 | + * Collects connection strings for routing and file upload endpoints and includes them in the ARM template output. |
| 33 | +* The manual process: |
| 34 | + * Migrates your device registry and your routing and endpoint information. You have to manually recreate additional configuration details in the new IoT hub. |
| 35 | + * Is faster for migrating large numbers of devices (for example, more than 100,000). |
| 36 | + * Uses an Azure Storage account to transfer the device registry. |
| 37 | + * Scrubs connection strings for routing and file upload endpoints from the ARM template output, and you need to manually add them back in. |
| 38 | + |
| 39 | +## Prerequisites |
| 40 | + |
| 41 | +* Azure CLI |
| 42 | + |
| 43 | + The features described in this article require version 0.20.0 or newer of the **azure-iot** extension. To check your extension version, run `az version`. To update your extension, run `az extension update --name azure-iot`. |
| 44 | + |
| 45 | + If you still have the legacy **azure-cli-iot-ext** extension installed, remove that extension before adding the **azure-iot** extension. |
| 46 | + |
| 47 | +## IoT Hub state |
| 48 | + |
| 49 | +When we talk about migrating the state of an IoT hub, we're referring to a combination of three aspects: |
| 50 | + |
| 51 | +* **Azure Resource Manager (ARM) resources.** This aspect is everything that can be defined in a resource template, and is the same information you'd get if you exported the resource template from your IoT hub in the Azure portal. Information captured as part of the ARM aspect includes: |
| 52 | + |
| 53 | + * Built-in event hub's retention time |
| 54 | + * Certificates |
| 55 | + * Cloud-to-device properties |
| 56 | + * Disable device SAS |
| 57 | + * Disable local auth |
| 58 | + * Enable file upload notifications |
| 59 | + * File upload storage endpoint |
| 60 | + * Identities |
| 61 | + * User-assigned identities |
| 62 | + * System-assigned identities (enabled or disabled) |
| 63 | + * Network rule sets |
| 64 | + * Routing |
| 65 | + * Custom endpoints |
| 66 | + * Fallback route |
| 67 | + * Routes |
| 68 | + * Tags |
| 69 | + |
| 70 | +* **Configurations.** This aspect is for aspects of an IoT hub that aren't represented in an ARM template. Specifically, this aspect covers automatic device management configurations and IoT Edge deployments. |
| 71 | + |
| 72 | +* **Devices.** This aspect represents the information in your device registry, which includes: |
| 73 | + |
| 74 | + * Device identities and twins |
| 75 | + * Module identities and twins |
| 76 | + |
| 77 | +Any IoT Hub property or configuration not listed here may not be exported or imported correctly. |
| 78 | + |
| 79 | +## Export the state of an IoT hub |
| 80 | + |
| 81 | +Use the [az iot hub state export](/cli/azure/iot/hub/state#az-iot-hub-state-export) command to export the state of an IoT hub to a file. |
| 82 | + |
| 83 | +If you want to run both the export and import steps in one command, refer to the section later in this article to [Migrate an IoT hub](#migrate-an-iot-hub). |
| 84 | + |
| 85 | +When you export the state of an IoT hub, you can choose which aspects to export. |
| 86 | + |
| 87 | +| Parameter | Details | |
| 88 | +| --------- | ------- | |
| 89 | +| `--aspects` | The state aspects to export. Specify one or more of the accepted values: **arm**, **configurations**, or **devices**. If this parameter is left out, then all three aspects will be exported. | |
| 90 | +| `--state-file`, `-f` | The path to the file where the state information will be written. | |
| 91 | +| `--replace`, `-r` | If this parameter is included, then the export command will overwrite the contents of the state file. | |
| 92 | + |
| 93 | +### Export endpoints |
| 94 | + |
| 95 | +If you choose to export the Azure Resource Manager aspect of an IoT hub, the export command will retrieve the connection strings for any endpoints that have key-based authentication and include them in the output ARM template. |
| 96 | + |
| 97 | +The export command also checks all endpoints to verify that the resource it connects to still exists. If not, then that endpoint and any routes using that endpoint won't be exported. |
| 98 | + |
| 99 | +## Import the state of an IoT hub |
| 100 | + |
| 101 | +Use the [az iot hub state import](/cli/azure/iot/hub/state#az-iot-hub-state-import) command to import state information from an exported file to a new or existing IoT hub. |
| 102 | + |
| 103 | +If you want to run both the export and import steps in one command, refer to the section later in this article to [Migrate an IoT hub](#migrate-an-iot-hub). |
| 104 | + |
| 105 | +| Parameter | Details | |
| 106 | +| --------- | ------- | |
| 107 | +| `--aspects` | The state aspects to import. Specify one or more of the accepted values: **arm**, **configurations**, or **devices**. If this parameter is left out, then all three aspects will be imported. | |
| 108 | +| `--state-file`, `-f` | The path to the exported state file. | |
| 109 | +| `--replace`, `-r` | If this parameter is included, then the import command will delete the current state of the destination hub. | |
| 110 | + |
| 111 | +## Migrate an IoT hub |
| 112 | + |
| 113 | +Use the [az iot hub state migrate](/cli/azure/iot/hub/state#az-iot-hub-state-migrate) command to migrate the state of one IoT hub to a new or existing IoT hub. |
| 114 | + |
| 115 | +This command wraps the export and import steps into a single command, and has no output files. If you are migrating a device registry with many devices (for example, a few hundred or a few thousand) you may find it easier and faster to run the export and import commands separately rather than running the migrate command. |
| 116 | + |
| 117 | +| Parameter | Details | |
| 118 | +| --------- | ------- | |
| 119 | +| `--aspects` | The state aspects to migrate. Specify one or more of the accepted values: **arm**, **configurations**, or **devices**. If this parameter is left out, then all three aspects will be migrated. | |
| 120 | +| `--replace`, `-r` | If this parameter is included, then the migrate command will delete the current state of the destination hub. | |
| 121 | +| `--destination-hub`, `--dh` | | |
| 122 | +| `--destination-hub-login`, `--dl` | | |
| 123 | +| `--destination-resource-group`, `--dg` | | |
| 124 | +| `--origin-hub`, `--oh` | | |
| 125 | +| `--origin-hub-login`, `--ol` | | |
| 126 | +| `--origin-resource-group`, `--og` | | |
| 127 | + |
| 128 | +## Troubleshoot a migration |
| 129 | + |
| 130 | +If you can't export or import devices or configurations, check that you have access to those properties. One way to verify this is by running the `az iot hub device-identity list` or `az iot hub configuration list` commands. |
| 131 | + |
| 132 | +## Next steps |
0 commit comments