Implementación y supervisión de módulos de IoT Edge a gran escala mediante la CLI de Azure

Se aplica a: IoT Edge 1.5

Importante

IoT Edge 1.5 LTS es la versión compatible. IoT Edge 1.4 LTS finaliza su ciclo de vida el 12 de noviembre de 2024. Si está usando una versión anterior, consulte Actualización de IoT Edge.

Use la CLI de Azure para crear una implementación automática de Azure IoT Edge y administrar implementaciones para muchos dispositivos a la vez. Las implementaciones automáticas de IoT Edge forman parte de la característica de Administración de dispositivos de Azure IoT Hub. Las implementaciones permiten implementar varios módulos en varios dispositivos, realizar un seguimiento del estado y el estado de los módulos y realizar cambios cuando sea necesario.

En este artículo, configuró la CLI de Azure y la extensión de IoT. A continuación, implementará módulos en un conjunto de dispositivos IoT Edge y supervisará el progreso mediante comandos de la CLI.

Requisitos previos

• Una instancia de IoT Hub en la suscripción de Azure.

• Uno o más dispositivos IoT Edge.

  Si no tiene un dispositivo IoT Edge configurado, puede crear uno en una máquina virtual de Azure. Siga los pasos de alguno de estos artículos de inicio rápido: Crear un dispositivo virtual Linux o Crear un dispositivo virtual Windows.

• La CLI de Azure en su entorno. La versión de la CLI de Azure debe ser 2.0.70 o posterior. Use az --version para comprobarlo. Esta versión admite comandos az extension e introduce la plataforma de comandos de Knack.

• La extensión de IoT para la CLI de Azure.

Configuración de un manifiesto de implementación

Un manifiesto de implementación es un documento JSON que describe qué módulos implementar, cómo fluyen los datos entre los módulos y las propiedades deseadas de los módulos gemelos. Para más información, consulte Aprenda a implementar módulos y establecer rutas en IoT Edge.

Para implementar módulos con la CLI de Azure, guarde el manifiesto de implementación localmente como un archivo .txt. Usará la ruta de acceso al archivo de la siguiente sección cuando ejecute el comando para aplicar la configuración al dispositivo.

Este es un manifiesto de implementación básico con un módulo como ejemplo.

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota:

Este manifiesto de implementación de ejemplo usa la versión de esquema 1.1 para el centro y el agente de IoT Edge. La versión 1.1 del esquema se publica junto con la versión 1.0.10 de IoT Edge. Permite usar características como el orden de inicio del módulo y la priorización de rutas.

Implementación superpuesta

Las implementaciones superpuestas son un tipo de implementación automática que se puede apilar entre sí. Para más información sobre las implementaciones superpuestas, consulte el artículo Descripción de las implementaciones automáticas de IoT Edge en un único dispositivo o a escala.

Puede crear y administrar implementaciones en capas con la CLI de Azure, como cualquier implementación automática, con solo algunas diferencias. Después de crear una implementación superpuesta, la CLI de Azure funciona para implementaciones superpuestas igual que para cualquier implementación. Para crear una implementación superpuesta, agregue la marca --layered al comando CREATE.

La segunda diferencia es la forma de construir el manifiesto de implementación. Las implementaciones automáticas estándar deben incluir los módulos en tiempo de ejecución del sistema y los módulos de usuario. Las implementaciones superpuestas solo pueden incluir módulos de usuario. Las implementaciones superpuestas también necesitan que haya una implementación automática estándar en un dispositivo para proporcionar los componentes necesarios de cada dispositivo IoT Edge, como los módulos del entorno de ejecución del sistema.

Este es un manifiesto de implementación en capas básico con un módulo como ejemplo.

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota:

Este manifiesto de implementación superpuesta tiene un formato ligeramente diferente al de un manifiesto de implementación estándar. Las propiedades deseadas de los módulos en tiempo de ejecución se contraen y usan la notación de puntos. Este formato es necesario para que Azure Portal reconozca una implementación en capas. Por ejemplo:

• properties.desired.modules.<module_name>
• properties.desired.routes.<route_name>

En el ejemplo anterior se muestra la configuración properties.desired de implementación superpuesta de un módulo. Si esta implementación superpuesta tiene como destino un dispositivo en el que ya se aplica el mismo módulo, sobrescribe las propiedades deseadas existentes. Para actualizar las propiedades deseadas en lugar de sobrescribirlas, defina una nueva subsección. Por ejemplo:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

También puede expresar lo mismo con la sintaxis siguiente:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

Nota:

Actualmente, todas las implementaciones superpuestas deben incluir un edgeAgent objeto para que sea válido. Incluso si una implementación en capas solo actualiza las propiedades del módulo, incluya un objeto vacío. Por ejemplo: "$edgeAgent":{}. Una implementación superpuesta con un objeto edgeAgent vacío se muestra como destino en el módulo gemelo edgeAgent, y no se aplicará.

Para crear una implementación superpuesta:

• Agregue la marca --layered al comando create de la CLI de Azure.
• No incluya módulos del sistema.
• Use la notación de puntos completa en $edgeAgent y $edgeHub.

Para obtener más información sobre la configuración de los módulos gemelos en implementaciones superpuestas, consulte Implementación superpuesta.

Identificación de dispositivos mediante etiquetas

Antes de crear una implementación, debe especificar qué dispositivos desea afectar. Azure IoT Edge identifica los dispositivos mediante etiquetas en el dispositivo gemelo.

Cada dispositivo puede tener varias etiquetas que puede definir de cualquier manera que tenga sentido para su solución. Por ejemplo, si administra un campus de edificios inteligentes, puede agregar las siguientes etiquetas a un dispositivo:

"tags":{
  "location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

Para más información sobre dispositivos gemelos y etiquetas, consulte Información y uso de dispositivos gemelos en IoT Hub.

Creación de una implementación

Implemente módulos en dispositivos de destino mediante la creación de una implementación que tenga el manifiesto de implementación y otros parámetros.

Ejecute el comando az iot edge deployment create para crear una implementación:

az iot edge deployment create --deployment-id <deployment-id> --hub-name <hub-name> --content <file-path> --labels "<labels>" --target-condition "<target-query>" --priority <priority>

Agregue la --layered marca para crear una implementación superpuesta.

El az iot edge deployment create comando usa los parámetros siguientes:

• --layered: marca opcional que identifica la implementación como una implementación superpuesta.
• --deployment-id: nombre de la implementación creada en el centro de IoT. Use un nombre único con hasta 128 letras minúsculas. Evite espacios y estos caracteres no válidos: & ^ [ ] { } \ | " < > /. Este parámetro es obligatorio.
• --content: ruta de acceso al archivo JSON del manifiesto de implementación. Este parámetro es obligatorio.
• --hub-name: nombre del centro de IoT donde se crea la implementación. El centro debe estar en la suscripción actual. Cambie su suscripción actual ejecutando az account set -s <subscription-name>.
• --labels: pares nombre-valor que describen y ayudan a realizar un seguimiento de las implementaciones. Las etiquetas usan formato JSON para nombres y valores. Por ejemplo: {"HostPlatform":"Linux", "Version":"3.0.1"}.
• --target-condition: condición que determina qué dispositivos están destinados a esta implementación. La condición se basa en las etiquetas del dispositivo gemelo o en las propiedades notificadas del dispositivo gemelo y debe coincidir con el formato de expresión. Por ejemplo: tags.environment='test' and properties.reported.devicemodel='4000x'. Si no especifica la condición de destino, la implementación no se aplica a ningún dispositivo.
• --priority: entero positivo. Si dos o más implementaciones tienen como destino el mismo dispositivo, se aplica la implementación con la prioridad más alta.
• --metrics: métricas que consultan las edgeHub propiedades notificadas para realizar un seguimiento del estado de una implementación. Las métricas usan entrada de JSON o una ruta de archivo. Por ejemplo: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

Para supervisar una implementación con la CLI de Azure, consulte Supervisión de implementaciones de IoT Edge.

Nota:

Al crear una nueva implementación de IoT Edge, IoT Hub puede tardar hasta 5 minutos en procesar la nueva configuración y enviar las nuevas propiedades deseadas a los dispositivos de destino.

Modificación de una implementación

Al cambiar una implementación, los cambios se replican inmediatamente en todos los dispositivos de destino.

Si actualiza la condición de destino, se producen los cambios siguientes:

• Si un dispositivo no cumple la condición de destino anterior, pero cumple la nueva condición de destino, y esta implementación es la prioridad más alta para ese dispositivo, esta implementación se aplica al dispositivo.
• Si un dispositivo que ejecuta actualmente esta implementación ya no cumple la condición de destino, desinstala esta implementación y toma la siguiente implementación de prioridad más alta .
• Si un dispositivo que ejecuta esta implementación ya no cumple la condición de destino y no cumple la condición de destino de ninguna otra implementación, no se produce ningún cambio en el dispositivo. El dispositivo sigue ejecutando sus módulos actuales en su estado actual, pero ya no se administra como parte de esta implementación. Una vez que el dispositivo cumple la condición de destino de otra implementación, desinstala esta implementación y toma la nueva.

No puede actualizar el contenido de una implementación, lo cual incluye los módulos y las rutas definidos en el manifiesto de implementación. Para actualizar el contenido de una implementación, cree una implementación que tenga como destino los mismos dispositivos con una prioridad más alta. Puede modificar determinadas propiedades de un módulo existente, incluidas la condición de destino, las etiquetas, las métricas y la prioridad.

Utilice el comando az iot edge deployment update para actualizar una implementación:

az iot edge deployment update --deployment-id <deployment-id> --hub-name <hub-name> --set <property1.property2='value'>

El comando de actualización de implementación usa los parámetros siguientes:

• --deployment-id: el nombre de la implementación en el centro de IoT.
• --hub-name: nombre del centro de IoT donde existe la implementación. El centro debe estar en la suscripción actual. Para cambiar a otra suscripción, ejecute az account set -s <subscription-name>.
• --set: cambiar una propiedad de la implementación. Puede cambiar las siguientes propiedades:
  • targetCondition (por ejemplo, targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add: Agregue una nueva propiedad a la implementación, incluidas las condiciones de destino o las etiquetas.
• --remove: elimine una propiedad existente, incluidas las condiciones objetivo o las etiquetas.

Eliminación de una implementación

Al eliminar una implementación, los dispositivos usan su siguiente implementación de prioridad más alta. Si los dispositivos no cumplen la condición de destino de otra implementación, los módulos no se quitan al eliminar la implementación.

Ejecute el comando az iot edge deployment delete para eliminar una implementación:

az iot edge deployment delete --deployment-id <deployment-id> --hub-name <hub-name>

El deployment delete comando usa los parámetros siguientes:

• --deployment-id. Nombre de la implementación que está en IoT Hub.
• --hub-name. Nombre de la instancia de IoT Hub en la que está la implementación. El centro debe estar en la suscripción actual. Cambie a la suscripción que quiera usar mediante el comando az account set -s [subscription name].

Pasos siguientes

Obtenga más información sobre la implementación de módulos en dispositivos IoT Edge.