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

Se aplica a: IoT Edge 1.5

Use el Azure CLI para crear una implementación automática de Azure IoT Edge y administrar implementaciones para muchos dispositivos a la vez. Las implementaciones automáticas para IoT Edge forman parte de la característica device management 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, configurará 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

• Un IoT hub en la suscripción de Azure.

• Uno o varios dispositivos IoT Edge.

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

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

• Extensión IoT para Azure CLI.

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 obtener más información, consulte Learn cómo implementar módulos y establecer rutas en IoT Edge.

Para implementar módulos mediante el Azure CLI, 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
        }
      }
    }
  }
}

Implementación superpuesta

Las implementaciones superpuestas son un tipo de implementación automática que se puede apilar entre sí. Para obtener más información sobre los despliegues en capas, consulte Entender las implementaciones automáticas de IoT Edge para dispositivos individuales o a escala.

Puede crear y administrar implementaciones en capas con el Azure CLI como cualquier implementación automática, con solo algunas diferencias. Después de crear una implementación superpuesta, el Azure CLI funciona para implementaciones superpuestas igual que para cualquier implementación. Para crear una implementación superpuesta, agregue la marca 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 en capas también necesitan una implementación automática estándar en un dispositivo para proporcionar los componentes necesarios de cada dispositivo IoT Edge, como los módulos en tiempo 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
        }
      }
    }
  }
}

En el ejemplo anterior se muestra la configuración 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
}

Para crear una implementación superpuesta:

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

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 tags 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 obtener más información sobre dispositivos gemelos y etiquetas, consulte Comprender y usar dispositivos gemelos en IoT Hub.

Crear 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 marca para crear una implementación superpuesta.

El 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 .
• --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: .
• --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: . 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 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: .

Para supervisar una implementación con el Azure CLI, consulte Monitor IoT Edge implementaciones.

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 hub debe estar en la suscripción actual. Para cambiar a otra suscripción, ejecute .
• --set: cambiar una propiedad de la implementación. Puede cambiar las siguientes propiedades:
  • (por ejemplo, )
  • 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.

Eliminar 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 comando usa los parámetros siguientes:

• --deployment-id. Nombre de la implementación que está en IoT Hub.
• --hub-name. Nombre del IoT Hub en el 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 .

Pasos siguientes

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