Obtenga información sobre cómo implementar módulos y establecer rutas en IoT Edge

Se aplica a: IoT Edge 1.5

Cada dispositivo IoT Edge ejecuta al menos dos módulos: $edgeAgent y $edgeHub, que constituyen el entorno de ejecución de Azure IoT Edge. Un dispositivo IoT Edge puede ejecutar varios módulos para distintos procesos. Use un manifiesto de implementación para indicar al dispositivo qué módulos instalar y cómo configurarlos para que funcionen juntos.

El manifiesto de implementación es un documento JSON que describe lo siguiente:

• El módulo gemelo del agente de IoT Edge, que incluye tres componentes:
  • Imagen de contenedor para cada módulo que se ejecuta en el dispositivo
  • Las credenciales para usar registros de contenedores privados que contienen imágenes de módulos
  • Instrucciones sobre cómo se crea y administra cada módulo
• El módulo gemelo del hub de IoT Edge, que incluye cómo fluyen los mensajes entre módulos y a IoT Hub.
• Las propiedades deseadas de cualquier módulo gemelo adicional (opcional)

Todos los dispositivos IoT Edge necesitan un manifiesto de implementación. Un entorno de ejecución de IoT Edge recién instalado muestra un código de error hasta que se configura con un manifiesto válido.

En los tutoriales de Azure IoT Edge, creas un archivo de manifiesto de implementación mediante un asistente en el portal de Azure IoT Edge. También puede aplicar un manifiesto de implementación mediante programación mediante REST o el SDK del servicio IoT Hub. Para más información, consulte el artículo Descripción de las implementaciones de IoT Edge.

Creación de un manifiesto de implementación

Un manifiesto de implementación es una lista de módulos gemelos establecidos con sus propiedades deseadas. Indica a un dispositivo IoT Edge o grupo de dispositivos qué módulos instalar y cómo configurarlos. Los manifiestos de implementación incluyen las propiedades deseadas de cada módulo gemelo. Los dispositivos IoT Edge notifican las propiedades notificadas para cada módulo.

Cada manifiesto de implementación requiere dos módulos: $edgeAgent y $edgeHub. Estos módulos forman parte del entorno de ejecución de Azure IoT Edge que administra el dispositivo IoT Edge y los módulos que se ejecutan en él. Para más información acerca de estos módulos, consulte Información sobre el entorno de ejecución de Azure IoT Edge y su arquitectura.

Puede agregar hasta 50 módulos adicionales para ejecutarse en un dispositivo IoT Edge, además de los dos módulos en tiempo de ejecución.

Un manifiesto de implementación que solo tiene el entorno de ejecución de IoT Edge ($edgeAgent y $edgeHub) es válido.

Los manifiestos de implementación usan esta estructura:

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

Configuración de módulos

Defina cómo instala el entorno de ejecución de Azure IoT Edge los módulos en la implementación. El agente de IoT Edge es el componente del entorno de ejecución que administra la instalación, las actualizaciones y los informes de estado de un dispositivo IoT Edge. Por lo tanto, el módulo gemelo $edgeAgent tiene la información de configuración y administración de todos los módulos. Esta información incluye los parámetros de configuración para el propio agente de IoT Edge.

Las propiedades de $edgeAgent siguen esta estructura:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // let the IoT Edge agent use container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

La versión 1.1 del esquema del agente de IoT Edge se publicó con ioT Edge versión 1.0.10 y le permite establecer el orden de inicio del módulo. Use la versión de esquema 1.1 para cualquier implementación de IoT Edge que ejecute la versión 1.0.10 o posterior.

Configuración y administración de módulos

La lista de propiedades deseadas del agente de IoT Edge es donde se definen los módulos que se ejecutan en un dispositivo IoT Edge y cómo se configuran y administran.

Para ver una lista completa de propiedades deseadas que pueden o deben incluirse, consulte Propiedades del agente de IoT Edge y del centro de IoT Edge.

Por ejemplo:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Todos los módulos tienen una propiedad settings con el módulo image, una dirección para la imagen de contenedor en un registro de contenedor y cualquier valor createOptions para configurar la imagen en el inicio. Para más información, consulte Configuración de las opciones de creación de contenedores para módulos de IoT Edge.

El módulo edgeHub y los módulos personalizados también tienen tres propiedades que indican al agente de IoT Edge cómo administrarlos:

• Estado: indica si el módulo se ejecuta o se detiene cuando se implementa por primera vez. Necesario.

• RestartPolicy: cuándo y si el agente de IoT Edge reinicia el módulo si se detiene. Si el módulo se detiene sin errores, no se inicia automáticamente. Para obtener más información, consulte Docker Docs - Start containers automatically (Docker Docs: Inicio automático de contenedores). Necesario.

• StartupOrder: introducido en la versión 1.0.10 de IoT Edge. Orden que usa el agente de IoT Edge para iniciar los módulos cuando se implemente por primera vez. El orden usa enteros, donde un módulo con un valor de inicio de 0 se inicia primero y, a continuación, se siguen números más altos. El módulo edgeAgent no tiene un valor de inicio porque siempre es el primero que se inicia. Opcional.

  El agente de IoT Edge inicia los módulos en orden del valor de inicio, pero no espera a que cada módulo termine de comenzar antes de iniciar el siguiente.

  El orden de inicio ayuda si algunos módulos dependen de otros. Por ejemplo, es posible que desee que el módulo edgeHub se inicie primero para que esté listo para enrutar los mensajes cuando se inician los otros módulos. O bien, es posible que desee iniciar un módulo de almacenamiento antes de iniciar módulos que envíen datos a él. Pero diseñe siempre los módulos para controlar los errores de otros módulos. Los contenedores se pueden detener y reiniciar en cualquier momento y cualquier número de veces.

  Nota:

  El cambio de las propiedades de un módulo reinicia ese módulo. Por ejemplo, se produce un reinicio si cambia las propiedades de :

  • Imagen de módulo
  • Opciones de creación de Docker
  • variables de entorno
  • Directiva de reinicio
  • Directiva de extracción de imágenes
  • Versión
  • Orden de inicio

  Si no se cambian propiedades de módulo, no se desencadena un reinicio del módulo.

Declaración de rutas

El IoT Edge hub administra la comunicación entre módulos, IoT Hub y dispositivos descendentes. El módulo gemelo de $edgeHub tiene una propiedad deseada denominada rutas que define cómo se mueven los mensajes dentro de una implementación. Puede configurar varias rutas en la misma implementación.

Declare las rutas en las $edgeHub propiedades deseadas mediante esta sintaxis:

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

La versión 1 del esquema del centro de IoT Edge se publicó con la versión 1.0.10 de IoT Edge y le permite establecer la priorización de rutas y el período de vida. Use la versión de esquema 1.1 para cualquier implementación de IoT Edge que ejecute la versión 1.0.10 o posterior.

Cada ruta necesita un origen para los mensajes entrantes y un receptor para los mensajes salientes. La condición es opcional y permite filtrar mensajes.

Asigne prioridad a las rutas para procesar primero mensajes importantes. Esta característica ayuda cuando la conexión ascendente es débil o limitada y necesitas priorizar la información crítica por encima de los mensajes de telemetría estándar.

Fuente

El origen especifica de dónde proceden los mensajes. IoT Edge puede enrutar mensajes desde módulos o dispositivos de bajada.

Con los SDK de IoT, los módulos pueden establecer colas de salida específicas para sus mensajes mediante la clase ModuleClient. Las colas de salida no son necesarias, pero ayudan a administrar varias rutas. Los dispositivos descendentes usan la clase DeviceClient en los SDK de IoT para enviar mensajes a los dispositivos de puerta de enlace de IoT Edge, tal como envían mensajes al IoT Hub. Para más información, consulte Información y uso de los SDK de Azure IoT Hub.

La propiedad source puede usar cualquiera de estos valores:

Condición

La condición es opcional en una declaración de ruta. Para pasar todos los mensajes desde el receptor al origen, omita la cláusula WHERE. O bien, use el lenguaje de consulta de IoT Hub para filtrar mensajes o tipos de mensajes que cumplan la condición. Las rutas de IoT Edge no admiten mensajes de filtrado basados en etiquetas o propiedades de gemelos.

Los mensajes que se mueven entre módulos de IoT Edge usan el mismo formato que los mensajes entre los dispositivos y Azure IoT Hub. Todos los mensajes usan formato JSON y tienen parámetros systemProperties, appProperties y body .

Cree consultas en torno a cualquiera de los tres parámetros mediante esta sintaxis:

• Propiedades del sistema: $<propertyName> o {$<propertyName>}
• Propiedades de la aplicación: <propertyName>
• Propiedades del cuerpo: $body.<propertyName>

Para obtener ejemplos de cómo crear consultas para propiedades de mensaje, consulte Expresiones de consulta de rutas de mensajes de dispositivo a nube.

Por ejemplo, puede que quiera filtrar los mensajes que llegan a un dispositivo de puerta de enlace desde un dispositivo aguas abajo. Los mensajes enviados de los módulos incluyen una propiedad del sistema denominada connectionModuleId. Para enrutar mensajes de dispositivos descendentes directamente a IoT Hub y excluir mensajes de módulo, use esta ruta.

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

Receptor

El receptor define dónde se envían los mensajes. Solo los módulos e IoT Hub pueden recibir mensajes. No se pueden enrutar mensajes a otros dispositivos. La propiedad del receptor no admite caracteres comodín.

La propiedad del receptor puede usar cualquiera de estos valores:

IoT Edge proporciona garantías de por lo menos una vez. El centro de IoT Edge almacena los mensajes localmente si una ruta no puede entregar el mensaje a su receptor. Por ejemplo, si el centro de IoT Edge no puede conectarse a IoT Hub o el módulo de destino no está conectado.

El centro de IoT Edge almacena mensajes hasta el momento establecido en la propiedad storeAndForwardConfiguration.timeToLiveSecs de las propiedades deseadas del centro de IoT Edge.

Prioridad y período de vida

Declare rutas como una cadena que defina la ruta o como un objeto con una cadena de ruta, un entero de prioridad y un entero de período de vida.

Opción 1

"route1": "FROM <source> WHERE <condition> INTO <sink>",

Opción 2 (introducida en la versión 1.0.10 de IoT Edge con la versión 1.1 del esquema del centro de IoT Edge)

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

Los valores de prioridad oscilan entre 0 y 9, donde 0 es la prioridad más alta. Los puntos de conexión ponen en cola los mensajes. Todos los mensajes de prioridad 0 para un punto de conexión específico se procesan antes de cualquier mensaje de prioridad 1 para el mismo punto de conexión. Si varias rutas para el mismo punto de conexión tienen la misma prioridad, los mensajes se procesan en el orden en que llegan. Si no establece una prioridad, la ruta usa la prioridad más baja.

La propiedad timeToLiveSecs usa el valor de storeAndForwardConfiguration del centro de IoT Edge, a menos que lo establezca directamente. El valor puede ser cualquier entero positivo.

Para más información sobre cómo se administran las colas de prioridad, consulte Prioridad de ruta y período de vida.

Definición o actualización de las propiedades deseadas

El manifiesto de implementación establece las propiedades deseadas para cada módulo implementado en el dispositivo IoT Edge. Las propiedades deseadas del manifiesto de implementación sobrescriben a las que estén presentes en el módulo gemelo.

Si no establece las propiedades deseadas de un módulo gemelo en el manifiesto de implementación, IoT Hub no cambia el módulo gemelo. En su lugar, establezca las propiedades deseadas mediante programación.

Los mismos mecanismos que permiten cambiar dispositivos gemelos también permiten cambiar módulos gemelos. Para más información vea la guía para desarrolladores de módulos gemelos.

Ejemplo de manifiesto de implementación

En el ejemplo siguiente se muestra el aspecto que puede tener un documento de manifiesto de implementación válido.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

Pasos siguientes

• Para obtener una lista completa de las propiedades que puede incluir o debe incluir en $edgeAgent y $edgeHub, consulte Propiedades del agente de IoT Edge y del centro de IoT Edge.

• Ahora que sabe cómo funcionan los módulos de IoT Edge, obtenga información sobre los requisitos y las herramientas para desarrollar módulos de IoT Edge.