Reinicio o apagado de dispositivos con Azure IoT y OSConfig

Importante

La versión 1.0.3 (publicada el 28 de junio de 2022) incluye cambios importantes en los nombres de miembros que pueden afectar a los usuarios existentes. Para obtener más información, consulte: Los nombres de miembro pasan de PascalCase a camelCase en la versión 1.0.3.

Audiencia y ámbito

Este artículo está diseñado para admitir a los usuarios que aprovisionan o administran dispositivos con Azure IoT. Si eso no suena como usted, considere la posibilidad de echar un vistazo a la documentación de Audiences for OSConfig.

En este artículo se explica cómo reiniciar o apagar dispositivos mediante la característica CommandRunner de OSConfig. Este artículo se centra en ejemplos prácticos con una explicación mínima. Para obtener información técnica sobre la característica CommandRunner , el modelo de interacción, etc. consulte Interacción con la característica CommandRunner de OSConfig y Azure IoT.

Ejemplos de caso de uso

Requisitos previos para probar los ejemplos en sistemas activos

Si usa este artículo como referencia (por ejemplo, está aquí para copiar un nombre de propiedad), no hay requisitos previos.

Si desea probar los ejemplos en sistemas dinámicos (recomendado), haga lo siguiente:

1. Necesitará una cuenta de Azure con un IoT Hub

   En este artículo se supone que está familiarizado con IoT Hub y las herramientas relacionadas. Por ejemplo, se supone que está familiarizado con la creación de ioT Hubs y la conexión de dispositivos. Si prefiere una introducción paso a paso más prescriptiva para instalar y usar OSConfig desde cero, consulte Inicio rápido: Administración de un único dispositivo IoT virtual mediante la CLI de Azure en su lugar.

2. Necesitará al menos un dispositivo Linux con el agente OSConfig instalado y conectado a Azure IoT.

   Para obtener más información, vea Cómo y dónde instalar el agente de OSConfig para Linux.

3. Usará Azure Portal o la CLI de Azure para interactuar con los dispositivos a través de la IoT Hub

   Para conocer más pasos, elija su experiencia preferida:

Azure Portal

1. Asegúrese de que ha iniciado sesión en Azure Portal y puede acceder a la página Información general de la IoT Hub .

Bash/Cloud Shell

1. Inicie sesión en Azure Portal con la cuenta que desea usar.
2. Inicio de Azure Cloud Shell en modo bash
3. (opcional) Use el comando az account show para asegurarse de que ha iniciado sesión en el contexto que desea usar para los ejemplos.

Ejemplo A. Reiniciar uno o varios dispositivos

En los ejemplos de dispositivos únicos, puede agregar la directiva de reinicio directamente al gemelo OSConfig del dispositivo que desea reiniciar.

Para los ejemplos a escala, imaginemos que se trabaja con un proceso externo que agrega y quita needsReboot etiquetas a los dispositivos. Crearemos una configuración de IoT Hub que tiene como destino dinámicamente los dispositivos donde se establece la needsReboot etiqueta en el gemelo osconfig. Simularemos este proceso externo estableciendo explícitamente la etiqueta .

Azure Portal, con un dispositivo

1. En la página del portal de la IoT Hub, vaya al gemelo OSConfig para el dispositivo que desea administrar y agregue lo siguiente a la properties.desired sección, seguido de una coma para separarla del siguiente elemento de properties.desired. action=1 siguiente especifica el reinicio.

   "CommandRunner": {
      "__t": "c",
      "commandArguments": {
         "commandId": "reboot_single_device_cmd",
         "arguments": "",
         "timeout": 30,
         "singleLineTextResult": false,
         "action": 1
      }
   }
   

   

2. Opcional: Una vez que el dispositivo vuelva a estar en línea (esto tardará unos minutos), puede comprobar la properties.reported sección y comprobar el comandoStatus que mostrará la acción de reinicio completada correctamente, como se muestra a continuación.

   "CommandRunner": {
      "__t": "c",
      "commandStatus": {
         "commandId": "reboot_single_device_cmd",
         "resultCode": 0,
         "textResult": "",
         "currentState": 2
      }
   }
   

1.Opcional: también puede iniciar sesión en el dispositivo o la máquina virtual para validar después de reiniciar el dispositivo.

Azure Portal, a escala

1. En primer lugar, simularemos el proceso externo descrito anteriormente aplicando manualmente una etiqueta "needsReboot" a uno o varios dispositivos de su elección. Esto proporcionará criterios de selección de destino para el trabajo de configuración de IoT Hub (que se creará en un paso posterior). Para ello, vaya a la página de Azure IoT Hub del dispositivo en el portal, al módulo gemelo OSConfig y agregue lo siguiente antes de la properties sección del gemelo.

   {
      {"tags": {"needsReboot": "true"}}
   }
   

2. En la página del portal de la Azure IoT Hub, elija Administración de dispositivos -->Configuraciones -->Agregar configuración del módulo.

3. Especifique un nombre y establezca la configuración de gemelos con la configuración deseada del administrador de paquetes. Establezca Module Twin Property (Propiedad de módulo gemelo)properties.desired.CommandRunner en y establezca module Twin Property Content (Contenido de propiedad del módulo gemelo) en lo siguiente:

   {
        "__t": "c",
        "commandArguments": {
            "commandId": "reboot_devices_by_tag",
            "arguments": "",
            "timeout": 30,
            "singleLineTextResult": false,
            "action": 1
        }
    }
   

4. Para los módulos de destino, especifique los criterios para los que los dispositivos están en el ámbito. En este ejemplo, estableceremos como destino todos los dispositivos habilitados para OSConfig que tengan la etiqueta especificada needsReboot, especificando una condición de destino de . FROM devices.modules where moduleId='osconfig' AND tags.needsReboot = 'true'

   

5. Opcional: Para observar qué dispositivos gemelos se han actualizado (en la nube), consulte la métrica Applied (también conocida como appliedCount).

   

6. Opcional: Puede observar los dispositivos que se reiniciaron correctamente mediante IoT Hub Consultas. Vaya a Administración de dispositivos -->Queries y ejecute la siguiente consulta.

   SELECT deviceId from devices.modules where moduleId='osconfig' 
   AND tags.needsReboot = 'true' 
   AND properties.reported.CommandRunner.CommandStatus.CommandId = 'reboot_devices_by_tag' 
   AND properties.reported.CommandRunner.CommandStatus.ResultCode = 0
   

   Tenga en cuenta que habrá algún retraso (~5-10 minutos) para que el comandoStatus se actualice, ya que esto requiere que el dispositivo complete el ciclo de reinicio y vuelva a estar en línea.

7. Opcional: Para fines de desarrollo y depuración, puede comprobar si connectionState para el módulo OSConfig (o cualquier otro módulo) aparece como Conectado. Para ello, vaya a Administración de dispositivos -->Queries y ejecute la consulta SELECT deviceId, connectionState FROM devices.modules where moduleId = 'osconfig'. Para obtener más información, consulta: DeviceHeartbeat.

8. Opcional: Para supervisar los eventos de conexión y desconexión del dispositivo en producción, consulte: MonitorConnectandDisconnect.

Bash/Cloud Shell, con un dispositivo

1. Use el siguiente comando de ejemplo para reiniciar un único dispositivo mediante la actualización del módulo gemelo OSConfig, reemplazando <el identificador> de dispositivo o <el nombre> del centro para que coincida con el entorno.

   az iot hub module-twin update -m osconfig --desired \
   '{
   "CommandRunner": {
        "__t": "c",
        "commandArguments": {
            "commandId": "reboot_single_device_cmd",
            "arguments": "",
            "timeout": 30,
            "singleLineTextResult": false,
            "action": 1
         }
      }
   }' -d <device id> --hub-name <hub name>
   

   

2. Opcional: Para comprobar que los dispositivos se han reiniciado correctamente mediante consultas de IoT Hub, vaya a Administración de dispositivos -->Queries y ejecute la consulta siguiente. Tenga en cuenta que habrá algún retraso (~5-10 minutos) para que el comando notificadoStatus se actualice, ya que esto requiere que el dispositivo complete el ciclo de reinicio y vuelva a estar en línea.

   SELECT deviceId from devices.modules where moduleId='osconfig' 
   AND properties.reported.CommandRunner.CommandStatus.CommandId = 'reboot_single_device_cmd' 
   AND properties.reported.CommandRunner.CommandStatus.ResultCode = 0
   

3. Opcional: También puede iniciar sesión en el dispositivo o la máquina virtual para validar después de reiniciar el dispositivo.

Bash/Cloud Shell, a escala

1. En primer lugar, simularemos el proceso externo descrito anteriormente aplicando manualmente una etiqueta "needsReboot" a uno o varios dispositivos de su elección. Esto proporcionará criterios de selección de destino para el trabajo de configuración de IoT Hub (que se creará en un paso posterior).

az iot hub module-twin update -m osconfig --tags '{"needsReboot": "true"}' -n <hub name> -d <device id> 

1. Use el siguiente comando de ejemplo para crear una configuración de IoT Hub. Esta configuración incluye criterios de destino, la configuración deseada. Asegúrese de reemplazar <el nombre> del centro por el nombre del IoT Hub.

   az iot hub configuration create -c "reboot_devices_by_tag" --content \
   '{"moduleContent":
     {"properties.desired.CommandRunner":
      {"commandArguments":
      {"commandId": "reboot_devices_by_tag",
        "arguments": "",      
        "timeout": 30,
        "singleLineTextResult": false,
        "action": 1            
      }}}}' \
   --target-condition "from devices.modules where moduleId='osconfig' and tags.needsReboot = 'true'" --priority 10 \
   --hub-name <hub name>
   

   

2. Opcional: Observe la métrica Aplicada

   Para ver qué dispositivos tienen aplicada la directiva de reinicio mediante esta configuración, ejecute el siguiente comando. La creación de la configuración puede tardar hasta 5 minutos en aplicarse a los gemelos de destino.

     az iot hub configuration show-metric --metric-id appliedCount -c "reboot_devices_by_tag" \
     -n <hub name> --metric-type system
   

3. Opcional: Para fines de desarrollo y depuración, puede comprobar si connectionState para el módulo OSConfig (o cualquier otro módulo) aparece como Conectado. Para ello, vaya a Administración de dispositivos -->Queries y ejecute la consulta SELECT deviceId, connectionState FROM devices.modules where moduleId = 'osconfig'. Para obtener más información, consulta: DeviceHeartbeat.

4. Opcional: Para supervisar los eventos de conexión y desconexión del dispositivo en producción, consulte esta documentación, MonitorConnectandDisconnect.

Ejemplo B. Apagado en lugar de reinicio

El apagado remoto (en lugar de reiniciar) los dispositivos perimetrales o IoT es una operación menos común, ya que el dispositivo no está disponible posteriormente (lo que impide que se inicie la copia de seguridad). Incluso así, hay casos reales que llaman al apagado remoto. Imagine que un dispositivo problemático que envía datos dañados es demasiado consumido por bytes de transmisión satélite preciosos, se cree que está en peligro o que está haciendo más daño que bien. En tales casos, puede ser conveniente apagar el dispositivo hasta que se pueda reemplazar o reparar.

Para realizar el apagado de los dispositivos a través de OSConfig, puede usar los mismos flujos de trabajo en la nube que el ejemplo A, pero con "action": 2 (apagado) en lugar "action": 1 de (reinicio) en commandArguments. Tenga en cuenta que cada solicitud de CommandRunner necesita un nuevo valor commandId. Por ejemplo, si ya ha realizado un reinicio en el ejemplo A y ahora desea cambiar al apagado, deberá modificar commandArguments no solo con "action": 2 , sino también con un valor no usado previamente para commandId, como "commandId": "my_shutdown_cmd". Para más información sobre el modelo de interacción de CommandRunner, consulte: Interacción con la característica CommandRunner de OSConfig y Azure IoT.

Pasos siguientes

Para obtener información general sobre los escenarios y funcionalidades de OSConfig, consulte:

• ¿Qué es OSconfig para IoT?

Para obtener ejemplos prácticos específicos, consulte:

• Creación de un entorno de laboratorio de OSConfig (con Azure IoT) en 5 minutos
• Inicio rápido: Consulta de ejemplos para empezar a trabajar con OSConfig y Azure IoT
• ¿Qué puedo aprovisionar y administrar?