Configuración de un dispositivo de IoT Edge para que se comunique a través de un servidor proxy

Artículo
04/11/2024

Se aplica a: 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.

Los dispositivos de IoT Edge envían solicitudes HTTPS para comunicarse con IoT Hub. Si ha conectado el dispositivo a una red que usa un servidor proxy, debe configurar el entorno de ejecución de IoT Edge para comunicarse a través del servidor. Los servidores proxy también pueden afectar a los módulos individuales de IoT Edge si realizan solicitudes HTTP o HTTPS que no se han enrutado a través del centro de IoT Edge.

Este artículo le guiará por los cuatro pasos que se describen a continuación para configurar y administrar un dispositivo de IoT Edge situado detrás de un servidor proxy:

Instale el entorno de ejecución de Azure IoT Edge en el dispositivo.

Los scripts de instalación de IoT Edge extraen paquetes y archivos de Internet, por lo que es necesario que la comunicación con el dispositivo pueda atravesar el servidor proxy para realizar esas solicitudes. En el caso de los dispositivos Windows, el script de instalación también dispone de una opción de instalación sin conexión.

Este paso es un proceso que solamente tiene que realizarse una vez para configurar el dispositivo de IoT Edge al establecer la configuración inicial. También necesita estas mismas conexiones al actualizar el entorno de ejecución de IoT Edge.
Configuración de IoT Edge y el tiempo de ejecución de contenedor en el dispositivo

IoT Edge es responsable de las comunicaciones con IoT Hub. El tiempo de ejecución de contenedor es responsable de la administración de contenedores, por lo que se comunica con los registros del contenedor. Ambos componentes deben hacer las solicitudes web a través del servidor proxy.

Este paso es un proceso que solamente tiene que realizarse una vez para configurar el dispositivo de IoT Edge al establecer la configuración inicial.
Configuración de las propiedades del agente de IoT Edge en el archivo de configuración del dispositivo

El demonio de IoT Edge inicia el módulo edgeAgent inicialmente. Después, el módulo edgeAgent recupera el manifiesto de implementación de IoT Hub e inicia todos los demás módulos. Configure las variables de entorno del módulo edgeAgent manualmente en el propio dispositivo para que el agente de IoT Edge pueda realizar la conexión inicial a IoT Hub. Una vez establecida la conexión inicial, puede configurar el módulo de edgeAgent de forma remota.

Este paso es un proceso que solamente tiene que realizarse una vez para configurar el dispositivo de IoT Edge al establecer la configuración inicial.
En el futuro, siempre que implemente un módulo, defina las variables de entorno de todos los módulos que se comuniquen a través del proxy.

Una vez configurado y conectado un dispositivo IoT Edge a IoT Hub a través del servidor proxy, debe mantener la conexión en todas las implementaciones futuras de módulos.

Este paso es un proceso continuo que se realiza de forma remota para que, con cada nueva actualización del módulo o la implementación, el dispositivo conserve su capacidad para comunicarse a través del servidor proxy.

Dirección URL de proxy

Para poder comenzar los pasos que se describen en este artículo, debe conocer la dirección URL del proxy.

Las direcciones URL de proxy tienen el formato siguiente: protocolo://host_proxy:puerto_proxy.

El protocolo es HTTP o HTTPS. El demonio de Docker puede usar cualquier protocolo según la configuración del registro de contenedor, pero los contenedores en runtime y demonio de IoT Edge deben utilizar siempre HTTPS para conectarse al proxy.
El host_proxy es una dirección para el servidor proxy. Si el servidor proxy requiere autenticación, puede proporcionar sus credenciales como parte del host proxy utilizando el siguiente formato: usuario:contraseña@host_proxy.
El puerto_proxy es el puerto de red en el que el proxy responde al tráfico de red.

Instalación de IoT Edge a través de un proxy

Tanto si el dispositivo de IoT Edge se ejecuta en Windows como si se ejecuta en Linux, debe obtener acceso a los paquetes de instalación a través del servidor proxy. En función del sistema operativo, siga el procedimiento que corresponda para instalar el entorno de ejecución de IoT Edge a través de un servidor proxy.

Dispositivos Linux

Si va a instalar el entorno de ejecución de Azure IoT Edge en un dispositivo Linux, configure el administrador de paquetes para que pase por el servidor proxy para acceder al paquete de instalación. Por ejemplo, configure apt-get para usar un http-proxy. Una vez configurado el administrador de paquetes, siga las instrucciones de Instalación del entorno de ejecución de Azure IoT Edge como de costumbre.

Dispositivos de Windows con IoT Edge para Linux en Windows.

Si va a instalar el entorno de ejecución de IoT Edge mediante IoT Edge para Linux en Windows, IoT Edge se instala de forma predeterminada en la máquina virtual de Linux. No es necesario instalar ni actualizar ningún otro paso.

Dispositivos de Windows con contenedores de Windows

Si va a instalar el entorno de ejecución de Azure IoT Edge en un dispositivo Windows, debe pasar por el servidor proxy dos veces. La primera conexión descarga el archivo del script de instalación. La segunda conexión se produce durante la instalación para descargar los componentes necesarios. Puede especificar la información del proxy en la configuración de Windows o incluirla directamente en los comandos de PowerShell.

Los siguientes pasos son un ejemplo de una instalación de Windows con el argumento -proxy:

El comando Invoke-WebRequest necesita información del proxy para poder acceder al script de instalación. A continuación, el comando Deploy-IoTEdge necesita la información del proxy para poder descargar los archivos de instalación.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
```
El comando Initialize-IoTEdge no tiene que atravesar el proxy, por lo que el segundo paso solo necesita la información del proxy para Invoke-WebRequest.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
```

Si tiene credenciales complicadas para el servidor proxy que no puede incluir en la dirección URL, use el -ProxyCredential parámetro dentro de -InvokeWebRequestParameters. Por ejemplo,

$proxyCredential = (Get-Credential).GetNetworkCredential()
. {Invoke-WebRequest -proxy <proxy URL> -ProxyCredential $proxyCredential -useb aka.ms/iotedge-win} | Invoke-Expression; `
Deploy-IoTEdge -InvokeWebRequestParameters @{ '-Proxy' = '<proxy URL>'; '-ProxyCredential' = $proxyCredential }

Para obtener más información acerca de los parámetros de proxy, consulte Invoke-WebRequest.

Configuración de IoT Edge y Moby

IoT Edge utiliza dos demonios que se ejecutan en el dispositivo de IoT Edge. El demonio de Docker realiza solicitudes web para extraer imágenes de contenedor desde los registros de contenedor. El demonio de IoT Edge realiza solicitudes web para comunicarse con IoT Hub.

Debe configurar los demonios de Moby y IoT Edge para usar el servidor proxy para la funcionalidad de dispositivo en curso. Este paso tiene lugar en el dispositivo de IoT Edge durante la instalación inicial del dispositivo.

Demonio Moby

Como Moby se basa en Docker, consulte la documentación de Docker para configurar el demonio Moby con variables de entorno. La mayoría de los registros de contenedor (incluidos los de DockerHub y Azure Container) admiten solicitudes HTTPS, por lo que el parámetro que se debe establecer es HTTPS_PROXY. Si va a extraer imágenes de un registro que no admite la seguridad de la capa de transporte (TLS), debe establecer el parámetro HTTP_PROXY.

Elija el artículo que corresponda al sistema operativo del dispositivo de IoT Edge:

Configure Docker daemon on Linux (Configuración del demonio de Docker en Linux). El demonio Moby en Linux mantiene el nombre Docker.
Configure Docker daemon on Windows (Configuración del demonio de Docker en Windows). El demonio Moby en Windows se llama iotedge-moby. Los nombres son diferentes porque, en los dispositivos Windows, Docker Desktop y Moby se pueden ejecutar a la vez.

Demonio de IoT Edge

El demonio de IoT Edge es similar al demonio de Moby. Utilice los pasos siguientes para establecer una variable de entorno para el servicio según su sistema operativo.

El demonio de IoT Edge siempre utiliza HTTPS para enviar solicitudes a IoT Hub.

Linux

Abra un editor en el terminal para configurar el demonio de IoT Edge.

sudo systemctl edit aziot-edged

Escriba el texto siguiente, y reemplace la <dirección URL del proxy> por la dirección del servidor proxy y el puerto. A continuación, guarde y salga.

[Service]
Environment="https_proxy=<proxy URL>"

A partir de la versión 1.2, IoT Edge usa el servicio de identidad de IoT para controlar el aprovisionamiento de dispositivos con IoT Hub o IoT Hub Device Provisioning Service. Abra un editor en el terminal para configurar el demonio del servicio de identidad de IoT.

sudo systemctl edit aziot-identityd

Escriba el texto siguiente, y reemplace la <dirección URL del proxy> por la dirección del servidor proxy y el puerto. A continuación, guarde y salga.

[Service]
Environment="https_proxy=<proxy URL>"

Actualice el administrador de servicios para que incluya las nuevas configuraciones.

sudo systemctl daemon-reload

Reinicie los servicios del sistema de IoT Edge para que los cambios en ambos demonios surtan efecto.

sudo iotedge system restart

Compruebe que las variables de entorno y la nueva configuración están presentes.

systemctl show --property=Environment aziot-edged
systemctl show --property=Environment aziot-identityd

Windows con IoT Edge para Linux en Windows.

Inicie sesión en ioT Edge para Linux en la máquina virtual Windows:

Connect-EflowVm

Siga los mismos pasos que la sección Linux de este artículo para configurar el demonio de IoT Edge.

Windows con contenedores de Windows

Abra una ventana de PowerShell como administrador y ejecute el comando siguiente para editar el registro con la nueva variable de entorno. Reemplace la <dirección URL del proxy> por la dirección del servidor proxy y el puerto.

reg add HKLM\SYSTEM\CurrentControlSet\Services\iotedge /v Environment /t REG_MULTI_SZ /d https_proxy=<proxy URL>

Reinicie IoT Edge para que los cambios surtan efecto.

Restart-Service iotedge

Configuración del agente de IoT Edge

El agente de IoT Edge es el primer módulo que se inicia en cualquier dispositivo de IoT Edge. Este módulo se inicia por primera vez en función de la información del archivo de configuración de IoT Edge. Después, el agente de IoT Edge se conecta a IoT Hub para recuperar manifiestos de implementación. El manifiesto declara qué otros módulos debe implementar el dispositivo.

Este paso se realiza una sola vez en el dispositivo de IoT Edge durante la instalación inicial del dispositivo.

Abra el archivo de configuración en el dispositivo IoT Edge: /etc/aziot/config.toml. Necesita privilegios administrativos para acceder al archivo de configuración. En los sistemas Linux, utilice el comando sudo antes de abrir el archivo en el editor de texto que prefiera.
En el archivo de configuración, busque la sección [agent], que contiene toda la información de configuración para el módulo edgeAgent que se va a usar en el inicio. Asegúrese de que la [agent] sección no tenga comentarios. Si falta la [agent] sección, agréguela a .config.toml La definición del agente de IoT Edge incluye una subsección [agent.env] en la que puede agregar variables de entorno.

Agregue el parámetro https_proxy a la sección de variables de entorno y establezca la dirección URL del proxy como su valor.

[agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.4"

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

El runtime de IoT Edge usa AMQP de forma predeterminada para comunicarse con IoT Hub. Algunos servidores proxy bloquean los puertos AMQP. Si es así, también debe configurar edgeAgent para que use AMQP sobre WebSocket. Quite la marca de comentario del parámetro UpstreamProtocol.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.4"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```

Agregue el parámetro https_proxy a la sección de variables de entorno y establezca la dirección URL del proxy como su valor.

[agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.4"

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

El runtime de IoT Edge usa AMQP de forma predeterminada para comunicarse con IoT Hub. Algunos servidores proxy bloquean los puertos AMQP. Si es así, también debe configurar edgeAgent para que use AMQP sobre WebSocket. Quite la marca de comentario del parámetro UpstreamProtocol.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.4"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
Guarde los cambios y cierre el editor. Aplique los cambios más recientes.
```
sudo iotedge config apply
```
Compruebe que la configuración del proxy se propaga mediante docker inspect edgeAgent en la sección Env. Si no es así, debe volver a crear el contenedor.
```
sudo docker rm -f edgeAgent
```
El entorno de ejecución de Azure IoT Edge debe volver a crear edgeAgent en un minuto. Una vez que el edgeAgent contenedor vuelva a ejecutarse, use el docker inspect edgeAgent comando para comprobar que la configuración del proxy coincide con el archivo de configuración.

Configuración de manifiestos de implementación

Una vez configurado el dispositivo IoT Edge para que funcione con el servidor proxy, declare la variable de entorno HTTPS_PROXY en los manifiestos de implementación futuros. Puede editar los manifiestos de implementación utilizando el asistente de Azure Portal o editando el archivo JSON de un manifiesto de implementación.

Configure siempre los dos módulos en tiempo de ejecución (edgeAgent y edgeHub) para que se comuniquen a través del servidor proxy con el fin de que puedan mantener una conexión con IoT Hub. Si quita la información de proxy del módulo edgeAgent, la única forma de restablecer la conexión es editando el archivo de configuración en el dispositivo, tal como se describe en la sección anterior.

Además de los módulos edgeAgent y edgeHub, es posible que otros módulos necesiten la configuración del proxy. Los módulos que necesitan acceder a recursos de Azure además de IoT Hub, como el almacenamiento de blobs, deben tener la variable HTTPS_PROXY especificada en el archivo de manifiesto de implementación.

El siguiente procedimiento es aplicable a lo largo de la vida del dispositivo IoT Edge.

Azure portal

Cuando usa el asistente de Establecimiento de módulos para crear implementaciones para dispositivos de IoT Edge, todos los módulos tienen una sección Variables de entorno donde puede configurar las conexiones con el servidor proxy.

Para configurar el agente de IoT Edge y los módulos del centro de IoT Edge, seleccione Configuración del entorno de ejecución en el primer paso del asistente.

Screenshot of how to configure advanced Edge Runtime settings.

Agregue la variable de entorno https_proxy al agente de IoT Edge y a las definiciones de módulo del centro de IoT Edge. Si incluyó la variable de entorno UpstreamProtocol en el archivo de configuración del dispositivo IoT Edge, agréguela también a la definición del módulo del agente de IoT Edge.

Screenshot of how to set the https_proxy environment variable.

Todos los demás módulos que agregue a un manifiesto de implementación seguirán el mismo patrón. Seleccione Aplicar para guardar los cambios.

Archivos JSON del manifiesto de implementación

Si va a crear implementaciones para dispositivos IoT Edge mediante las plantillas de Visual Studio Code o mediante la creación manual de archivos JSON, puede agregar las variables de entorno directamente a cada definición del módulo. Si no los agréguelos en Azure Portal, agréguelos aquí al archivo de manifiesto JSON. Reemplace <proxy URL> por su propio valor.

Use el siguiente formato JSON:

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    }
}

Con las variables de entorno incluidas, la definición del módulo debería ser similar al siguiente ejemplo de edgeHub:

"edgeHub": {
    "type": "docker",
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
        "createOptions": "{}"
    },
    "env": {
        "https_proxy": {
            "value": "http://proxy.example.com:3128"
        }
    },
    "status": "running",
    "restartPolicy": "always"
}

Si incluyó la variable de entorno UpstreamProtocol en el archivo confige.yaml del dispositivo de IoT Edge, agréguela también a la definición del módulo del agente de IoT Edge.

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    },
    "UpstreamProtocol": {
        "value": "AmqpWs"
    }
}

Trabajo con proxies de inspección de tráfico

Algunos servidores proxy, como Zscaler, pueden inspeccionar el tráfico cifrado con TLS. Durante la inspección del tráfico TLS, el certificado devuelto por el proxy no es el certificado del servidor de destino, sino el certificado firmado por el propio certificado raíz del proxy. De forma predeterminada, los módulos de IoT Edge (incluidos edgeAgent y edgeHub) no confían en el certificado de este proxy y se produce un error en el protocolo de enlace TLS.

Para resolver el protocolo de enlace con errores, configure tanto el sistema operativo como los módulos de IoT Edge para confiar en el certificado raíz del proxy con los pasos siguientes.

Configure el certificado proxy en el almacén de certificados raíz de confianza del sistema operativo host. Para obtener más información sobre cómo instalar un certificado raíz, consulte Instalación de una entidad de certificación raíz en el almacén de certificados de sistema operativo.
Configure el dispositivo IoT Edge para comunicarse a través de un servidor proxy haciendo referencia al certificado en la agrupación de confianza. Para obtener más información sobre cómo configurar la agrupación de confianza, consulte Administración de una entidad de certificación raíz de confianza (agrupación de confianza).

Para configurar la compatibilidad del proxy de inspección de tráfico con contenedores no administrados por IoT Edge, póngase en contacto con el proveedor del proxy en cuestión.

Nombres de dominio completos (FQDN) de destinos con los que se comunica IoT Edge

Si el firewall del proxy requiere que agregue todos los FQDN a la lista de permitidos para la conectividad a Internet, revise la lista de Permitir conexiones desde dispositivos IoT Edge para determinar qué FQDN agregar.

Pasos siguientes

Más información sobre los roles del entorno de ejecución de Azure IoT Edge.

Solución de errores de instalación y configuración con Problemas habituales y soluciones para Azure IoT Edge