Configuración del módulo de proxy de API para el escenario de jerarquías de puertas de enlace

Se aplica a: IoT Edge 1.5

En este artículo se describen las opciones de configuración del módulo de proxy de API, lo que le permite personalizar el módulo para satisfacer los requisitos de jerarquía de la puerta de enlace.

El módulo de proxy de API simplifica la comunicación para IoT Edge dispositivos cuando varios servicios usan el protocolo HTTPS y se enlazan al puerto 443. Esta configuración es especialmente relevante en implementaciones jerárquicas de dispositivos IoT Edge en arquitecturas aisladas de red basadas en ISA-95, como las descritas en La red aísla los dispositivos descendentes, ya que los clientes en los dispositivos descendentes no pueden conectarse directamente a la nube.

Por ejemplo, permitir que los dispositivos IoT Edge situados aguas abajo extraigan imágenes de Docker requiere la implementación de un módulo del registro de Docker. Permitir que los dispositivos carguen blobs requiere la implementación de un módulo de Azure Blob Storage en el mismo dispositivo IoT Edge. Ambos servicios usan HTTPS para la comunicación. El módulo proxy de API habilita estas implementaciones en un dispositivo IoT Edge. En lugar de cada enlace de servicio al puerto 443, el módulo proxy de API se enlaza al puerto 443 en el dispositivo host y enruta las solicitudes al módulo de servicio correcto que se ejecuta en ese dispositivo en función de las reglas configurables por el usuario. Los servicios individuales siguen siendo responsables de controlar las solicitudes, incluida la autenticación y autorización de clientes.

Sin el proxy de API, cada módulo de servicio debe enlazarse a un puerto independiente en el dispositivo host, lo que requiere un cambio de configuración tedioso y propenso a errores en cada dispositivo secundario que se conecta al dispositivo primario IoT Edge.

Implementación del módulo de proxy

El módulo proxy de API está disponible en Microsoft Container Registry (MCR) y el URI de imagen es mcr.microsoft.com/azureiotedge-api-proxy:latest. Implemente el módulo mediante el portal Azure o Azure CLI.

Descripción del módulo de proxy

El módulo proxy de API usa un proxy inverso nginx para enrutar los datos a través de capas de red. El módulo tiene un proxy incrustado, por lo que la imagen del módulo debe admitir la configuración del proxy. Por ejemplo, si el proxy escucha en un puerto determinado, el módulo debe tener ese puerto abierto.

El proxy se inicia con un archivo de configuración predeterminado incrustado en el módulo. Pase una nueva configuración al módulo desde la nube mediante su módulo gemelo. También puede usar variables de entorno para activar o desactivar la configuración en el momento de la implementación.

En este artículo se describe primero el archivo de configuración predeterminado y cómo usar variables de entorno para habilitar su configuración. A continuación, se explica cómo personalizar el archivo de configuración.

Configuración predeterminada

El módulo proxy de API incluye una configuración predeterminada que admite escenarios comunes y le permite personalizarlo. Controle la configuración predeterminada a través de las variables de entorno del módulo.

Actualmente, entre las variables de entorno predeterminadas se incluyen:

Minimización de puertos abiertos

Para minimizar los puertos abiertos, establezca el módulo de proxy de API para retransmitir todo el tráfico HTTPS (puerto 443), incluido el tráfico para el módulo edgeHub. De forma predeterminada, el módulo de proxy de API redirecciona todo el tráfico de edgeHub en el puerto 443.

Siga estos pasos para configurar la implementación para minimizar los puertos abiertos:

1. Actualice la configuración del módulo edgeHub para que no se enlace al puerto 443. De lo contrario, obtendrá conflictos de enlace de puertos. De forma predeterminada, el módulo edgeHub se enlaza a los puertos 443, 5671 y 8883. Elimine el enlace del puerto 443 y deje los otros dos en su lugar:

   {
     "HostConfig": {
       "PortBindings": {
         "5671/tcp": [
           {
             "HostPort": "5671"
           }
         ],
         "8883/tcp": [
           {
             "HostPort": "8883"
           }
         ]
       }
     }
   }
   

2. Configure el módulo de proxy de API para enlazar el puerto 443.

   1. Establezca el valor de la variable de entorno NGINX_DEFAULT_PORT en 443.

   2. Actualice las opciones de creación del contenedor para enlazar al puerto 443.

      {
        "HostConfig": {
          "PortBindings": {
            "443/tcp": [
              {
                "HostPort": "443"
              }
            ]
          }
        }
      }
      

Si no necesita minimizar los puertos abiertos, deje que el módulo edgeHub use el puerto 443 y configure el módulo proxy de API para que escuche en otro puerto. Por ejemplo, configure la variable de entorno NGINX_DEFAULT_PORT en 8000 y cree un enlace de puerto para el puerto 8000.

Habilitación de la descarga de la imagen de contenedor

Un caso de uso común para el módulo proxy de API es permitir que los dispositivos IoT Edge en las capas inferiores extraigan imágenes de contenedor. En este escenario se usa el módulo del Registro de Docker para obtener imágenes de contenedor de la nube y almacenarlas en caché en la capa superior. El proxy de API retransmite todas las solicitudes HTTPS para descargar una imagen de contenedor de las capas inferiores al módulo del Registro en la capa superior.

En este escenario, los dispositivos de nivel inferior IoT Edge apuntan al nombre de dominio $upstream seguido del número de puerto del módulo proxy de API en lugar del registro de contenedor de una imagen. Por ejemplo: $upstream:8000/azureiotedge-api-proxy:1.1.

Este caso de uso se muestra en el tutorial Crear una jerarquía de dispositivos IoT Edge mediante puertas de enlace.

Configure los siguientes módulos en la capa superior:

• Un módulo del registro de Docker
  • Configure el módulo con un nombre sencillo de recordar, como registro y exponga un puerto en el módulo para recibir solicitudes.
  • Configure el módulo para que se asigne al registro de contenedor.
• Un módulo de proxy de API

  • Configure las siguientes variables de entorno:

    NOMBRE	Valor
    DOCKER_REQUEST_ROUTE_ADDRESS	Nombre del módulo del registro y puerto abierto. Por ejemplo: registry:5000.
    NGINX_DEFAULT_PORT	Puerto en el que escucha el proxy nginx para las solicitudes desde dispositivos de nivel inferior. Por ejemplo: 8000.

  • Configure las siguientes createOptions:

    {
       "HostConfig": {
          "PortBindings": {
             "8000/tcp": [
                {
                   "HostPort": "8000"
                }
             ]
          }
       }
    }
    

Configure el siguiente módulo en cualquier capa inferior para este escenario:

• Módulo de proxy de API. El módulo de proxy de API es necesario en todos los dispositivos de capa inferior, excepto en el dispositivo de capa más baja.

  • Configure las siguientes variables de entorno:

    NOMBRE	Valor
    NGINX_DEFAULT_PORT	Puerto en el que escucha el proxy nginx para las solicitudes desde dispositivos de nivel inferior. Por ejemplo: 8000.

  • Configure las siguientes createOptions:

    {
       "HostConfig": {
          "PortBindings": {
             "8000/tcp": [
                {
                   "HostPort": "8000"
                }
             ]
          }
       }
    }
    

Exposición del puerto de proxy

El puerto 8000 se expone de forma predeterminada desde la imagen de Docker. Si usa un puerto proxy nginx diferente, agregue la sección ExposedPorts para declarar el puerto en el manifiesto de implementación. Por ejemplo, si cambia el puerto de proxy nginx a 8001, agrega lo siguiente al manifiesto de implementación:

{
   "ExposedPorts": {
      "8001/tcp": {}
   },
   "HostConfig": {
      "PortBindings": {
            "8001/tcp": [
               {
                  "HostPort": "8001"
               }
            ]
      }
   }
}

Habilitación de la carga de blobs

Otro caso de uso para el módulo proxy de API permite a los dispositivos IoT Edge en capas inferiores cargar blobs. Este caso de uso le permite solucionar problemas de dispositivos de capas inferiores, como cargar registros de módulos o el paquete de soporte.

En este escenario se usa el módulo Azure Blob Storage en IoT Edge en la capa superior para controlar la creación y carga de blobs. En un escenario anidado, se admiten hasta cinco capas. El módulo Azure Blob Storage en IoT Edge es necesario para el dispositivo de capa superior, pero es opcional para los dispositivos de capa inferior. Para obtener una implementación de varias capas de ejemplo, consulte el ejemplo Azure IoT Edge for Industrial IoT.

Configure los siguientes módulos en la capa superior:

• Un módulo de Azure Blob Storage en el módulo de IoT Edge.
• Un módulo de proxy de API

  • Configure las siguientes variables de entorno:

    NOMBRE	Valor
    BLOB_UPLOAD_ROUTE_ADDRESS	Nombre del módulo de almacenamiento de blobs y puerto abierto. Por ejemplo: azureblobstorageoniotedge:11002.
    NGINX_DEFAULT_PORT	Puerto en el que escucha el proxy nginx para las solicitudes desde dispositivos de nivel inferior. Por ejemplo: 8000.

  • Configure las siguientes createOptions:

    {
       "HostConfig": {
          "PortBindings": {
             "8000/tcp": [
                {
                   "HostPort": "8000"
                }
             ]
          }
       }
    }
    

Configure el siguiente módulo en cualquier capa inferior para este escenario:

• Un módulo de proxy de API

  • Configure las siguientes variables de entorno:

    NOMBRE	Valor
    NGINX_DEFAULT_PORT	Puerto en el que escucha el proxy nginx para las solicitudes desde dispositivos de nivel inferior. Por ejemplo: 8000.

  • Configure las siguientes createOptions:

    {
       "HostConfig": {
          "PortBindings": {
             "8000/tcp": [
                {
                   "HostPort": "8000"
                }
             ]
          }
       }
    }
    

Siga estos pasos para cargar el paquete de soporte técnico o el archivo de registro en el módulo de Blob Storage en la capa superior:

1. Cree un contenedor de blobs mediante Azure Storage Explorer o las API REST. Para obtener más información, consulte la documentación Azure Storage Explorer.

2. Solicite la carga de un paquete de registros o soporte siguiendo los pasos en Obtener registros de implementaciones de IoT Edge, pero use el nombre de dominio $upstream y el puerto de proxy abierto en lugar de la dirección de módulo de almacenamiento blob. Por ejemplo:

   {
      "schemaVersion": "1.0",
      "sasUrl": "https://$upstream:8000/myBlobStorageName/myContainerName?SAS_key",
      "since": "2d",
      "until": "1d",
      "edgeRuntimeOnly": false
   }
   

Edición de la configuración de proxy

Un archivo de configuración predeterminado está incrustado en el módulo proxy de API, pero puede pasar una nueva configuración al módulo a través de la nube mediante el módulo gemelo.

Al escribir su propia configuración, puede seguir usando variables de entorno para ajustar la configuración de cada implementación. Use la sintaxis siguiente:

• Use ${MY_ENVIRONMENT_VARIABLE} para obtener el valor de una variable de entorno.

• Use instrucciones condicionales para activar o desactivar la configuración en función del valor de una variable de entorno:

  #if_tag ${MY_ENVIRONMENT_VARIABLE}
       statement to execute if environment variable evaluates to 1
  #endif_tag ${MY_ENVIRONMENT_VARIABLE}
  
  #if_tag !${MY_ENVIRONMENT_VARIABLE}
       statement to execute if environment variable evaluates to 0
  #endif_tag !${MY_ENVIRONMENT_VARIABLE}
  

Cuando el módulo de proxy de API analiza una configuración de proxy, primero reemplaza todas las variables de entorno enumeradas en PROXY_CONFIG_ENV_VAR_LIST por sus valores mediante la sustitución. A continuación, reemplaza todo entre un par de #if_tag y #endif_tag. A continuación, el módulo proporciona la configuración analizada al proxy inverso nginx.

Para actualizar la configuración del proxy dinámicamente, siga estos pasos:

1. Escriba el archivo de configuración. Use esta plantilla predeterminada como referencia: nginx_default_config.conf.

2. Copie el texto del archivo de configuración y conviértalo en base64.

3. Pegue el archivo de configuración codificado como valor de la propiedad proxy_config deseada en el módulo gemelo.

   

Pasos siguientes

Utilice el módulo proxy de API para conectar un dispositivo IoT Edge descendente a una puerta de enlace de Azure IoT Edge.