Cómo migrar automáticamente un centro de IoT mediante la CLI de Azure

  • Artículo

Use la CLI de Azure para migrar un centro de IoT a una nueva región, un nuevo nivel o una nueva configuración.

Los pasos de este artículo son útiles si desea hacer lo siguiente:

  • Actualizar el nivel gratis de un centro de IoT a un nivel básico o estándar.
  • Mover un centro de IoT a una nueva región.
  • Exportar la información de estado del centro de IoT para tenerlo como copia de seguridad.
  • Aumentar el número de particiones para un centro de IoT.
  • Configurar un centro para un entorno de desarrollo, en lugar de un entorno producción.

Comparación de los pasos de migración automática y manual

El resultado de este artículo es similar a Cómo migrar un centro de Azure IoT mediante plantillas de Azure Resource Manager, pero con un proceso diferente. Antes de comenzar, decida qué proceso es adecuado para su escenario.

  • Proceso de la CLI de Azure (este artículo):

    • Migra el registro de dispositivos, la información de enrutamiento y punto de conexión, y otros detalles de configuración, como las implementaciones de IoT Edge o las configuraciones automáticas de administración de dispositivos.
    • Es más fácil para migrar pequeños números de dispositivos (por ejemplo, hasta 10 000).
    • No requiere una cuenta de Azure Storage.
    • Recopila cadenas de conexión para el enrutamiento y los puntos de conexión de carga de archivos y los incluye en la salida de la plantilla de ARM.

  • El proceso manual:

    • Migra el registro de dispositivos y la información de enrutamiento y punto de conexión. Tiene que volver a crear manualmente otros detalles de configuración en el nuevo centro de IoT.
    • Es más rápido para migrar un gran número de dispositivos (por ejemplo, más de 100 000).
    • Usa una cuenta de Azure Storage para transferir el registro de dispositivos.
    • Limpia las cadenas de conexión para el enrutamiento y los puntos de conexión de carga de archivos de la salida de la plantilla de ARM, y debe volver a agregarlos manualmente.

Requisitos previos

  • Azure CLI

    Las características descritas en este artículo requieren la versión 0.20.0 o posterior de la extensión azure-iot. Para comprobar la versión de la extensión, ejecute az --version. Para actualizar la extensión, ejecute az extension update --name azure-iot.

    Si todavía tiene instalada la extensión azure-cli-iot-ext heredada, quite esa extensión antes de agregar la extensión azure-iot.

Estado del centro de IoT

Cuando hablamos de migrar el estado de un centro de IoT, nos referimos a una combinación de tres aspectos:

  • Recursos de Azure Resource Manager (ARM). Este aspecto incluye todo lo que se puede definir en una plantilla de recursos y es la misma información que obtendría si exporta la plantilla de recursos desde el centro de IoT en Azure Portal. La información capturada como parte del aspecto de Azure Resource Manager incluye:

    • Tiempo de retención del centro de eventos integrado
    • Certificados
    • Propiedades de la nube al dispositivo
    • Deshabilitación de SAS del dispositivo
    • Deshabilitación de la autenticación local
    • Habilitación de las notificaciones de carga de archivos
    • Punto de conexión de almacenamiento de carga de archivos
    • Identities
      • Identidades asignadas por el usuario
      • Identidades asignadas por el sistema (habilitadas o deshabilitadas)
    • Conjuntos de reglas de red
    • Enrutamiento
      • Puntos de conexión personalizados
      • Ruta de reserva
      • Rutas
    • Etiquetas

  • Configuraciones. Este aspecto es para los aspectos de un centro de IoT que no se representan en una plantilla de ARM. En concreto, este aspecto abarca las configuraciones de administración automática de dispositivos y las implementaciones de IoT Edge.

  • Dispositivos. Este aspecto representa la información del registro de dispositivos, que incluye lo siguiente:

    • Identidades de dispositivo y gemelos
    • Identidades de módulo y gemelos

Es posible que cualquier propiedad o configuración de IoT Hub que no aparezca aquí no se exporte ni importe correctamente.

Exportación del estado de un centro de IoT

Use el comando az iot hub state export para exportar el estado de un centro de IoT a un archivo JSON.

Si desea ejecutar los pasos de exportación e importación en un comando, consulte la sección más adelante en este artículo sobre cómo Migrar un centro de IoT.

Al exportar el estado de un centro de IoT, puede elegir qué aspectos se van a exportar.

Parámetro Detalles
--aspects Aspectos del estado que se van a exportar. Especifique uno o varios de los valores aceptados: arm, configuraciones o dispositivos. Si se deja fuera este parámetro, se exportan los tres aspectos.
--state-file -f Ruta de acceso al archivo donde se escribe la información de estado.
--replace -r Si se incluye este parámetro, el comando de exportación sobrescribe el contenido del archivo de estado.
--hub-name -n
or
--login -l		 Nombre del centro de IoT de origen (-n) o la cadena de conexión del centro de IoT de origen (-l). Si se proporcionan ambos, la cadena de conexión tiene prioridad.
--resource-group -g Nombre del grupo de recursos del centro de IoT de origen.

En el ejemplo siguiente se exportan todos los aspectos del estado de un centro de IoT a un archivo denominado myHub-state:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

En el ejemplo siguiente solo se exportan los dispositivos y los aspectos de Azure Resource Manager del estado de un centro de IoT, y se sobrescribe el contenido del archivo existente:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

Exportación de puntos de conexión

Si decide exportar el aspecto de Azure Resource Manager de un centro de IoT, el comando de exportación recupera las cadenas de conexión de los puntos de conexión que tengan autenticación basada en claves y las incluye en la plantilla de ARM de salida.

El comando de exportación también comprueba todos los puntos de conexión para comprobar que el recurso al que se conecta sigue existiendo. Si no es así, ese punto de conexión y las rutas que usan ese punto de conexión no se exportan.

Importación del estado de un centro de IoT

Use el comando az iot hub state import para importar la información de estado de un archivo exportado a un centro de IoT nuevo o existente.

Si desea ejecutar los pasos de exportación e importación en un comando, consulte la sección más adelante en este artículo sobre cómo Migrar un centro de IoT.

Parámetro Detalles
--aspects Aspectos de estado que se van a importar. Especifique uno o varios de los valores aceptados: arm, configuraciones o dispositivos. Si se deja fuera este parámetro, se importan los tres aspectos.
--state-file -f Ruta de acceso al archivo de estado exportado.
--replace -r Si se incluye este parámetro, el comando de importación elimina el estado actual del centro de destino.
--hub-name -n
or
--login -l		 Nombre del centro de IoT de destino (-n) o la cadena de conexión del centro de IoT de destino (-l). Si se proporcionan ambos, la cadena de conexión tiene prioridad.
--resource-group -g Nombre del grupo de recursos del centro de IoT de destino.

En el ejemplo siguiente se importan todos los aspectos a un nuevo centro de IoT, que se crea si aún no existe:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

En el ejemplo siguiente solo se importan los aspectos de dispositivos y configuraciones a un nuevo centro de IoT, que ya debe existir, y se sobrescriben los dispositivos y las configuraciones existentes:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

Creación de un centro de IoT nuevo con importación de estado

Puede usar el comando az iot hub state import para crear un centro de IoT nuevo o escribir en un centro de IoT existente.

Si desea crear una nueva instancia de IoT Hub, debe incluir el aspecto arm en el comando de importación. Si arm no se incluye en el comando y el centro de destino no existe, se produce un error en el comando de importación.

Si el centro de destino no existe, el parámetro --resource-group también es necesario para el comando de importación.

Actualización de un centro de IoT existente con importación de estado

Si el centro de IoT de destino ya existe, el aspecto arm no es necesario para el comando az iot hub state import. Si incluye el aspecto arm, se sobrescribirán todas las propiedades del recurso, excepto las siguientes propiedades que no se pueden cambiar después de la creación del centro:

  • Location
  • SKU
  • Recuento de particiones de Event Hubs integrado
  • Residencia de datos
  • Características

Si se especifica --resource-group en el comando de importación y es diferente del grupo de recursos actual del centro de IoT, se produce un error en el comando porque este intenta crear un nuevo centro con el mismo nombre que el que ya existe.

Si incluye la marca --replace en el comando de importación, los siguientes aspectos del centro de IoT se quitan del centro de destino antes de cargar el estado del centro:

  • ARM: se eliminan los certificados cargados en el centro de destino. Si hay un certificado, se necesita una etiqueta electrónica para actualizarse.
  • Dispositivos: se eliminan todos los dispositivos y módulos, perimetrales y no perimetrales.
  • Configuraciones: se eliminan todas las configuraciones de ADM y las implementaciones de IoT Edge.

Migrar un centro de IoT

Use el comando az iot hub state migrate para migrar el estado de un centro de IoT a un centro de IoT nuevo o existente.

Este comando ajusta los pasos de exportación e importación en un solo comando, pero no tiene archivos de salida. Todas las instrucciones y limitaciones descritas en Exportación del estado de un centro de IoT e Importación del estado de un centro de IoT también se aplican al comando state migrate.

Si va a migrar un registro de dispositivos con muchos dispositivos (por ejemplo, unos cientos o varios miles), es posible que le resulte más fácil y rápido ejecutar los comandos de exportación e importación por separado en lugar de ejecutar el comando de migración.

Parámetro Detalles
--aspects Aspectos de estado que se van a migrar. Especifique uno o varios de los valores aceptados: arm, configuraciones o dispositivos. Si se deja fuera este parámetro, se migran los tres aspectos.
--replace -r Si se incluye este parámetro, el comando de migración elimina el estado actual del centro de destino.
--destination-hub --dh
or
--destination-hub-login --dl		 Nombre del centro de IoT de destino (--dh) o la cadena de conexión del centro de IoT de destino (--dl). Si se proporcionan ambos, la cadena de conexión tiene prioridad.
--destination-resource-group --dg Nombre del grupo de recursos del centro de IoT de destino. El grupo de recursos de destino es necesario si el centro de destino no existe.
--origin-hub --oh
or
--origin-hub-login --ol		 Nombre del centro de IoT de origen (--oh) o la cadena de conexión del centro de IoT de origen (--ol). Si se proporcionan ambos, la cadena de conexión tiene prioridad. Use la cadena de conexión para evitar tener que iniciar sesión en la sesión de la CLI de Azure.
--origin-resource-group --og Nombre del grupo de recursos del centro de IoT de origen.

En el ejemplo siguiente se migran todos los aspectos del centro de origen al centro de destino, que se crea si no existe:

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

Solución de problemas de una migración

Si no puede exportar o importar dispositivos o configuraciones, compruebe que tenga acceso a esas propiedades. Una manera de comprobar el acceso es mediante la ejecución de los comandos az iot hub device-identity list o az iot hub configuration list.

Si se produce un error en el comando az iot hub state migrate, intente ejecutar los comandos de exportación e importación por separado. Los dos comandos dan como resultado la misma funcionalidad que el comando de migración solo, pero al ejecutarlos por separado, puede revisar los archivos de estado creados a partir del comando de exportación.

Pasos siguientes

Para obtener más información sobre cómo realizar operaciones masivas en el registro de identidades en un centro de IoT, consulte Importación y exportación de identidades de dispositivo de IoT Hub.