Creación y aprovisionamiento de un dispositivo IoT Edge en Linux mediante certificados X.509

  • Artículo

Se aplica a:IoT Edge 1.4 checkmark IoT Edge 1.4

Importante

IoT Edge 1.4 es la versión admitida. Si está usando una versión anterior, consulte Actualización de IoT Edge.

En este artículo se proporcionan instrucciones completas para registrar y aprovisionar un dispositivo IoT Edge en Linux, incluida la instalación de IoT Edge.

Todos los dispositivos que se conectan a IoT Hub tienen un identificador de dispositivo que se usa para realizar un seguimiento de las comunicaciones de la nube al dispositivo o del dispositivo a la nube. Configure un dispositivo con su información de conexión, que incluye el nombre de host del centro de IoT, el id. de dispositivo y la información que el dispositivo usa para autenticarse en IoT Hub.

Los pasos de este artículo le guían a través de un proceso denominado aprovisionamiento manual, donde conecta un único dispositivo a su centro de IoT. En el caso del aprovisionamiento manual, tiene dos opciones para autenticar dispositivos IoT Edge:

  • Claves simétricas: cuando se crea una identidad de dispositivo en IoT Hub, el servicio crea dos claves. Debe colocar una de las claves en el dispositivo para que este la presente a IoT Hub al autenticarse.

    Este método de autenticación es más rápido para comenzar, pero no es tan seguro.

  • X.509 auto firmado: se crean dos certificados de identidad X.509 y se colocan en el dispositivo. Cuando se crea una nueva identidad de dispositivo en IoT Hub, se proporcionan huellas digitales de ambos certificados. Cuando el dispositivo se autentica en IoT Hub, presenta un certificado, y IoT Hub comprueba que el certificado coincide con su huella digital.

    Este método de autenticación es más seguro y se recomienda para los escenarios de producción.

En este artículo se describe el uso de certificados X.509 como método de autenticación. Si quiere usar claves simétricas, consulte Creación y aprovisionamiento de un dispositivo IoT Edge en Linux mediante claves simétricas.

Nota:

Si tiene muchos dispositivos para configurar y no quiere aprovisionar manualmente cada uno, siga uno de los artículos a continuación para obtener información sobre cómo funciona IoT Edge con IoT Hub Device Provisioning Service:

Requisitos previos

En este artículo se explica cómo registrar un dispositivo IoT Edge e instalar IoT Edge en él. Estas tareas tienen requisitos previos y utilidades diferentes que se usan para realizarlas. Asegúrese de que cumple todos los requisitos previos antes de continuar.

Herramientas de administración de dispositivos

Puede usar Azure Portal, Visual Studio Code o la CLI de Azure para seguir los pasos para registrar el dispositivo. Cada utilidad tiene sus propios requisitos previos o puede que deban instalarse:

Un centro de IoT gratuito o estándar en la suscripción de Azure.

Requisitos del dispositivo

Dispositivo Linux X64, ARM32 o ARM64.

Microsoft publica paquetes de instalación para una variedad de sistemas operativos.

para la información más reciente sobre qué sistemas operativos se admiten actualmente en los escenarios de producción, consulte Sistemas compatibles con Azure IoT Edge.

Generación de los certificados de identidad del dispositivo

El aprovisionamiento manual con certificados X.509 requiere IoT Edge, versión 1.0.10 o posterior.

Al aprovisionar un dispositivo IoT Edge con certificados X.509, se usa lo que se denomina un certificado de identidad del dispositivo. Este certificado solo se usa para aprovisionar un dispositivo IoT Edge y autenticarlo en Azure IoT Hub. Es un certificado de hoja que no firma otros certificados. El certificado de identidad del dispositivo es independiente de los certificados de la entidad de certificación (CA) que el dispositivo IoT Edge presenta a los módulos o dispositivos de nivel inferior para la verificación.

En el caso de la autenticación mediante certificados X.509, la información de autenticación de cada dispositivo se proporciona en forma de huellas digitales tomadas de los certificados de identidad del dispositivo. Estas huellas digitales se proporcionan a IoT Hub en el momento de registrar el dispositivo para que el servicio pueda reconocer el dispositivo al conectarse.

Para obtener más información sobre cómo se usan los certificados de CA en los dispositivos IoT Edge, consulte Información sobre los certificados de Azure IoT Edge.

Necesita los siguientes archivos para el aprovisionamiento manual con X.509:

  • Dos certificados de identidad del dispositivo con sus certificados de clave privada coincidentes en los formatos .cer o .pem. Necesita dos certificados de identidad del dispositivo para la rotación de certificados. Como procedimiento recomendado, prepare dos certificados de identidad del dispositivo diferentes con fechas de expiración diferentes. Si un certificado expira, el otro sigue siendo válido y le da tiempo para rotar el certificado expirado.

    Se proporciona un conjunto de archivos de certificado y clave al entorno de ejecución de IoT Edge. Al crear los certificados de identidad del dispositivo, establezca el nombre común del certificado (CN) en el id. de dispositivo que quiere que tenga el dispositivo en el centro de IoT.

  • Huellas digitales tomadas de ambos certificados de identidad del dispositivo. IoT Hub requiere dos huellas digitales al registrar un dispositivo IoT Edge. Solo puede usar un certificado para el registro. Para usar un solo certificado, establezca la misma huella digital de certificado para las huellas digitales principal y secundaria al registrar el dispositivo.

    Los valores de huella digital son 40 caracteres hexadecimales para hashes de tipo SHA-1 o 64 caracteres hexadecimales para hashes de tipo SHA-256. Ambas huellas digitales se proporcionan a IoT Hub en el momento del registro del dispositivo.

    Una manera de recuperar la huella digital de un certificado es con el siguiente comando openssl:

    openssl x509 -in <certificate filename>.pem -text -fingerprint

    La huella digital se incluye en la salida de este comando. Por ejemplo:

    SHA1 Fingerprint=D2:68:D9:04:9F:1A:4D:6A:FD:84:77:68:7B:C6:33:C0:32:37:51:12

Si no tiene certificados disponibles, puede proceder a la Creación de certificados de demostración para probar las características de dispositivo IoT Edge. Siga las instrucciones de ese artículo para configurar scripts de creación de certificados, crear un certificado de CA raíz y luego crear dos certificados de identidad de dispositivo IoT Edge. Con fines de prueba, puede crear un único certificado de identidad de dispositivo y usar la misma huella digital para los valores de huella digital principal y secundario al registrar el dispositivo en IoT Hub.

Registro del dispositivo

Puede usar Azure Portal, Visual Studio Code o la CLI de Azure para registrar el dispositivo, según su preferencia.

En su centro de IoT en Azure Portal, los dispositivos IoT Edge se crean y administran por separado de los dispositivos IoT que no están habilitados para Edge.

  1. Inicie sesión en Azure Portal y vaya a IoT Hub.

  2. En el panel izquierdo, seleccione Dispositivos en el menú y, luego, elija Agregar dispositivo.

  3. En la página Crear un dispositivo, proporcione la información siguiente:

    • Cree un id. de dispositivo descriptivo. Anote este identificador de dispositivo, ya que lo usará más adelante.
    • Active la casilla Dispositivo IoT Edge.
    • Seleccione X.509 autofirmado como el tipo de autenticación.
    • Proporcione las huellas digitales de certificado de identidad principal y secundaria. Los valores de huella digital son 40 caracteres hexadecimales para hashes de tipo SHA-1 o 64 caracteres hexadecimales para hashes de tipo SHA-256. Azure Portal solo admite valores hexadecimales. Quite los separadores de columna y los espacios de los valores de huella digital antes de escribirlos en el portal. Por ejemplo, D2:68:D9:04:9F:1A:4D:6A:FD:84:77:68:7B:C6:33:C0:32:37:51:12 se escribe como D268D9049F1A4D6AFD8477687BC633C032375112.

    Sugerencia

    Si está probando y desea usar un certificado, puede usar el mismo certificado para las huellas digitales principal y secundaria.

  4. Seleccione Guardar.

Ahora que tiene un dispositivo registrado en IoT Hub, recupere la información que usa para completar la instalación y el aprovisionamiento del entorno de ejecución de Azure IoT Edge.

Visualización de dispositivos registrados y recuperación de la información de aprovisionamiento

Los dispositivos que usan la autenticación con certificados X.509 necesitan el nombre de su centro de IoT, su nombre de dispositivo y sus archivos de certificado para completar la instalación y el aprovisionamiento del entorno de ejecución de Azure IoT Edge.

Todos los dispositivos habilitados para Edge que se conectan al centro de IoT se enumeran en la página Dispositivos. Puede filtrar la lista por el tipo de dispositivo Dispositivo IoT Edge.

Instalación de IoT Edge

En esta sección, preparará su máquina virtual Linux o dispositivo físico para IoT Edge. A continuación, instalará IoT Edge.

Ejecute los comandos siguientes para agregar el repositorio de paquetes y luego agregue la clave de firma de paquetes de Microsoft a la lista de claves de confianza.

Importante

El 30 de junio de 2022 se retiró Raspberry Pi OS Stretch de la lista de soporte técnico del sistema operativo de nivel 1. Para evitar posibles vulnerabilidades de seguridad, actualice el sistema operativo del host a Bullseye.

La instalación se puede realizar con unos pocos comandos. Abra un terminal y ejecute los comandos siguientes:

  • 22.04:

    wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

  • 20.04:

    wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

Para obtener más información sobre las versiones del sistema operativo, consulte Plataformas compatibles con Azure IoT Edge.

Nota:

Los paquetes de software de Azure IoT Edge están sujetos a los términos de licencia que se encuentran cada paquete (usr/share/doc/{package-name} o el directorio LICENSE). Lea los términos de licencia antes de usar el paquete. La instalación y el uso de un paquete constituyen la aceptación de estos términos. Si no acepta los términos de licencia, no utilice ese paquete.

Instalación de un motor del contenedor

Azure IoT Edge utiliza un runtime de contenedor compatible con OCI. En los escenarios de producción, se recomienda utilizar el motor de Moby. El motor de Moby es el único motor de contenedor compatible oficialmente con IoT Edge. Las imágenes de contenedor de Docker CE/EE son totalmente compatibles con el entorno de ejecución de Moby.

Instale el motor de Moby.

sudo apt-get update; \
  sudo apt-get install moby-engine

De forma predeterminada, el motor del contenedor no establece límites de tamaño de registro de contenedor. Con el tiempo, esto puede hacer que el dispositivo se llene con registros y se quede sin espacio en disco. Sin embargo, puede configurar el registro para que se muestre localmente, aunque es opcional. Para más información sobre la configuración de registro, consulte Lista de comprobación de implementación de producción.

En los pasos siguientes se muestra cómo configurar el contenedor para que use el localcontrolador de registro como mecanismo de registro.

  1. Crear o editar el archivo de configuración del demonio de Docker existente

    sudo nano /etc/docker/daemon.json

  2. Establezca el controlador de registro predeterminado en el controlador de registro local, tal como se muestra en el ejemplo.

       {
      "log-driver": "local"
   }

  3. Reinicie el motor de contenedores para que se apliquen los cambios.

    sudo systemctl restart docker

Instalación del entorno de ejecución de IoT Edge

El servicio IoT Edge proporciona y mantiene los estándares de seguridad en el dispositivo IoT Edge. El servicio se inicia en cada arranque e inicia el resto del entorno de ejecución de IoT Edge para arrancar el dispositivo.

Nota:

A partir de la versión 1.2, el servicio de identidad de IoT controla el aprovisionamiento y la administración de identidades para IoT Edge y otros componentes de dispositivo que necesitan comunicarse con IoT Hub.

Los pasos de esta sección representan el proceso habitual para instalar la versión más reciente de IoT Edge en un dispositivo que tenga conexión a Internet. Si tiene que instalar una versión específica, como una versión preliminar, o tiene que realizar la instalación mientras está sin conexión, siga los pasos de Instalación sin conexión o de una versión específica, más adelante en este artículo.

Sugerencia

Si ya tiene un dispositivo IoT Edge que ejecuta una versión anterior y desea actualizar a la versión más reciente, siga los pasos descritos en Actualización del demonio de seguridad de IoT Edge y el entorno de ejecución. Las versiones más recientes son suficientemente diferentes de las versiones anteriores de IoT Edge para que sean necesarios pasos específicos para la actualización.

Instale la versión más reciente de IoT Edge y el paquete de servicio de identidad de IoT (si aún no está actualizado):

  • 22.04:

    sudo apt-get update; \
   sudo apt-get install aziot-edge

  • 20.04:

    sudo apt-get update; \
   sudo apt-get install aziot-edge defender-iot-micro-agent-edge

El paquete defender-iot-micro-agent-edge opcional incluye el micro agente de seguridad de Microsoft Defender para IoT que proporciona visibilidad del punto de conexión en la administración de la posición de seguridad, vulnerabilidades, detección de amenazas, administración de flotas y mucho más para ayudarle a proteger los dispositivos de IoT Edge. Se recomienda instalar el microagente con el agente de Edge para habilitar la supervisión de seguridad y la protección de los dispositivos de Edge. Para obtener más información sobre Microsoft Defender para IoT, consulte ¿Qué es Microsoft Defender para IoT para generadores de dispositivos?.

Aprovisionamiento del dispositivo con su identidad de nube

Ahora que el motor del contenedor y el entorno de ejecución de IoT Edge están instalados en el dispositivo, está listo para configurar el dispositivo con su información de autenticación e identidad en la nube.

  1. Cree el archivo de configuración para el dispositivo basándose en un archivo de plantilla que se proporciona como parte de la instalación de IoT Edge.

    sudo cp /etc/aziot/config.toml.edge.template /etc/aziot/config.toml

  2. Abra el archivo de configuración en el dispositivo IoT Edge.

    sudo nano /etc/aziot/config.toml

  3. Busque la sección Provisioning del archivo y quite las marcas de comentario de las líneas para el aprovisionamiento manual con el certificado de identidad X.509. Asegúrese de que las demás secciones de aprovisionamiento estén comentadas.

    # Manual provisioning with x.509 certificates
[provisioning]
source = "manual"
iothub_hostname = "REQUIRED_IOTHUB_HOSTNAME"
device_id = "REQUIRED_DEVICE_ID_PROVISIONED_IN_IOTHUB"

[provisioning.authentication]
method = "x509"

identity_cert = "REQUIRED_URI_OR_POINTER_TO_DEVICE_IDENTITY_CERTIFICATE"

identity_pk = "REQUIRED_URI_TO_DEVICE_IDENTITY_PRIVATE_KEY"

Actualice los siguientes campos:

  • iothub_hostname: nombre de host de IoT Hub al que se conectará el dispositivo. Por ejemplo, {IoT hub name}.azure-devices.net.
  • device_id: el id. que proporcionó al registrar el dispositivo.
  • identity_cert: URI para un certificado de identidad en el dispositivo, por ejemplo: file:///path/identity_certificate.pem. O bien, emita el certificado de forma dinámica mediante EST o una entidad de certificación local.
  • identity_pk: URI para el archivo de clave privada del certificado de identidad proporcionado, por ejemplo: file:///path/identity_key.pem. O bien, proporcione un identificador URI PKCS#11 y proporcione la información de configuración en

Sección PKCS#11 más adelante en el archivo de configuración.

Para más información sobre los certificados, consulte Administración de certificados de IoT Edge.

Guarde y cierre el archivo.

CTRL + X, Y, Enter

Después de escribir la información de aprovisionamiento en el archivo de configuración, aplique sus cambios:

sudo iotedge config apply

Implementación de módulos

Para implementar los módulos de IoT Edge, vaya al centro de IoT en Azure Portal y, a continuación, haga lo siguiente:

  1. Seleccione Dispositivos en el menú de IoT Hub.

  2. Seleccione el dispositivo para abrir su página.

  3. Seleccione la pestaña Establecer módulos.

  4. Puesto que queremos implementar los módulos predeterminados de IoT Edge (edgeAgent y edgeHub), no es necesario agregar módulos a este panel, por lo que seleccione Revisar y crear en la parte inferior.

  5. Verá la confirmación JSON de los módulos. Seleccione Crear para implementar los módulos.<

Para obtener más información, consulte Implementación de un módulo.

Comprobación de configuración correcta

Compruebe que el runtime se ha instalado y configurado correctamente en el dispositivo de IoT Edge.

Sugerencia

Necesita privilegios elevados para ejecutar comandos iotedge. Cuando cierre la sesión en su máquina y la inicie de nuevo por primera vez después de instalar el entorno de ejecución de IoT Edge, sus permisos se actualizarán automáticamente. Hasta entonces, use sudo delante de los comandos.

Compruebe que el servicio del sistema IoT Edge esté en ejecución.

sudo iotedge system status

Una respuesta de estado correcta es Ok.

Si necesita solucionar problemas del servicio, recupere los registros del servicio.

sudo iotedge system logs

Use la herramienta check para comprobar el estado de configuración y conexión del dispositivo.

sudo iotedge check

Puede esperar un intervalo de respuestas que pueden incluir Aceptar (verde), Advertencia (amarillo) o Error (rojo). Para solucionar errores comunes, consulte Soluciones a problemas comunes de Azure IoT Edge.

Screenshot of sample responses from the check command.

Sugerencia

Use siempre sudo para ejecutar la herramienta de comprobación, incluso después de que se actualicen los permisos. Para comprobar el estado de la configuración, la herramienta necesita privilegios elevados para acceder al archivo de configuración.

Nota:

En un dispositivo recién aprovisionado, es posible que vea un error relacionado con IoT Edge Hub:

× preparación para producción: el directorio de almacenamiento de Edge Hub se conserva en el sistema de archivos host: error

No se pudo comprobar el estado actual del contenedor de Edge Hub

Este error se espera en un dispositivo recién aprovisionado porque el módulo de IoT Edge Hub no se está ejecutando. Para resolver el error, en IoT Hub, establezca los módulos del dispositivo y cree una implementación. La creación de una implementación para el dispositivo inicia los módulos en el dispositivo, incluido el módulo de IoT Edge Hub.

Vea todos los módulos que se ejecutan en el dispositivo IoT Edge. Cuando el servicio se inicia por primera vez, solo verá la ejecución del módulo edgeAgent. El módulo edgeAgent se ejecuta de forma predeterminada y le ayuda a instalar e iniciar todos los módulos adicionales que implemente en el dispositivo.

sudo iotedge list

Al crear un nuevo dispositivo IoT Edge, se muestra el código de estado 417 -- The device's deployment configuration is not set en Azure Portal. Este estado es normal y significa que el dispositivo está listo para recibir una implementación de módulo.

Instalación sin conexión o de una versión específica (opcional)

Los pasos de esta sección corresponden a escenarios que no se tratan en los pasos de instalación estándar. Esto puede incluir:

  • Instalación de IoT Edge sin conexión
  • Instalación de una versión candidata para lanzamiento

Siga los pasos de esta sección si quiere instalar una versión específica del entorno de ejecución de Azure IoT Edge que no esté disponible mediante el administrador de paquetes. La lista de paquetes de Microsoft solo contiene un conjunto limitado de versiones recientes y sus subversiones, por lo que estos pasos son para cualquiera que quiera instalar una versión anterior o una versión candidata para lanzamiento.

Si usa snaps de Ubuntu, puede descargar un snap e instalarlo sin conexión. Para más información, consulte Descarga de snaps e instalación sin conexión.

Con los comandos curl, puede dirigirse a los archivos de componentes directamente desde el repositorio de GitHub de IoT Edge.

Nota:

Si el dispositivo ejecuta actualmente IoT Edge versión 1.1 o anterior, desinstale los paquetes iotedge y libiothsm-std antes de seguir los pasos de esta sección. Para más información, consulte Actualización de 1.0 o 1.1 a la versión más reciente.

  1. Vaya a Versiones de Azure IoT Edge y busque la versión de lanzamiento que desea tener como destino.

  2. Expanda la sección Recursos para esa versión.

  3. Cada versión debe tener archivos nuevos para IoT Edge y el servicio de identidad. Si va a instalar IoT Edge en un dispositivo sin conexión, descargue estos archivos con anterioridad. De lo contrario, use los comandos siguientes para actualizar esos componentes.

    1. Busque el archivo aziot-identity-service que coincida con la arquitectura del dispositivo IoT Edge. Haga clic con el botón derecho en el vínculo del archivo y copie la dirección del vínculo.

    2. Use el vínculo copiado en el comando siguiente para instalar esa versión del servicio de identidad:

      curl -L <identity service link> -o aziot-identity-service.deb && sudo apt-get install ./aziot-identity-service.deb

    1. Busque el archivo aziot-edge que coincida con la arquitectura del dispositivo IoT Edge. Haga clic con el botón derecho en el vínculo del archivo y copie la dirección del vínculo.

    2. Use el vínculo copiado en el comando siguiente para instalar esa versión de IoT Edge.

      curl -L <iotedge link> -o aziot-edge.deb && sudo apt-get install ./aziot-edge.deb

Desinstalación de IoT Edge

Si quiere quitar la instalación de IoT Edge de su dispositivo, use los siguientes comandos.

Quite el entorno de ejecución de Azure IoT Edge.

sudo apt-get autoremove --purge aziot-edge

Excluya la marca --purge si planea reinstalar IoT Edge y usar la misma información de configuración en el futuro. Las marcas --purge eliminan todos los archivos asociados a IoT Edge, incluidos los archivos de configuración.

Al quitar el entorno de ejecución de IoT Edge, los contenedores que se hayan creado en él se detendrán, pero seguirán existiendo en el dispositivo. Observe todos los contenedores para ver cuáles permanecen.

sudo docker ps -a

Elimine los contenedores del dispositivo, incluidos los dos contenedores del entorno en tiempo de ejecución.

sudo docker rm -f <container name>

Por último, quite el entorno en tiempo de ejecución del contenedor del dispositivo.

sudo apt-get autoremove --purge moby-engine