wiki:Version2/Desarrollo/Communications

Introducción

Las comunicaciones entre clientes y servidor se realizan mediante tareas (jobs). Dichas tareas permiten ejecutar comandos del sistema o comandos de opengnsys en los clientes y recibir información acerca de esa ejecución en el servidor.

Características principales

El sistema de tareas se caracteriza principalmente por:

  • Toda comunicación se establece mediante peticiones GET/POST mediante HTTPS.
  • El socket de comunicación está autenticado siempre entre ambas partes mediante un certificado SSL.
  • Existen tests unitarios de todo el sistema de comunicaciones.

Elementos comunicantes

Existen tres elementos que se comunican entre sí, estos son:

  • La consola web, que es un servicio web que se ejecuta en el servidor y que a instancias del usuario es la que crea una nueva tarea, que se guarda en la BD de la consola y solicita al cliente (o clientes) la ejecución de dicha tarea.
  • El job executer, que es un servicio web que se ejecuta en el cliente donde deben ejecutarse las tareas. Se encarga de recibir las peticiones, ejecutar los comandos asociados a dichas peticiones, y mantener al servidor Opengnsys informado del estado de la tarea.
  • El job receiver, que es un servicio web que se ejecuta en el servidor Opengnsys y es el encargado de recibir las actualizaciones de los clientes, guardarlas en la BD del servidor para que la consola web tenga noticia de las mismas, y procesar las actualizaciones, puesto que cada tarea puede tener asociada una función a tal efecto.

La consola web y el job receiver son sendos servidores web que se ejecutan en el servidor Opengnsys y comparten la misma BD. La razón por la cual fue necesaria la creación de un segundo servicio web (job receiver) es porque mientras que la consola web no autentica mediante SSL al cliente HTTP, el job receiver necesita hacerlo.

Vida de una tarea

La vida de una tarea simple suele ser la siguiente:

  1. Un usuario desde la consola web de administración de Opengnsys solicita la realización de una tarea, por ejemplo restaurar una imagen de disco en un ordenador cliente opengnsys.
  2. La consola web crea un objeto de tipo Job que será guardado en la BD, y realiza una petición HTTPS al job receiver del cliente.
  3. El servicio web job receiver del cliente recibe la petición HTTP, la procesa, y lanza en un hilo el comando a ejecutar.
  4. El job receiver mantiene informado del estado de la tarea al servidor opengnsys mediante mensajes de actualización que se envían mediante una petición HTTP al servicio job receiver del servidor. Básicamente hay dos tipos de actualizaciones:
    1. Actualizaciones de estado, que indican un tipo de estado que puede ser "INPROGRESS", "FINISHED" o "ERROR", y una cadena de mensaje que será procesada por el servidor. INPROGRESS se envía automáticamente cada cierto tiempo en tareas lentas para que el servidor sepa que la tarea sigue en proceso.
    2. Actualizaciones de progreso. Se envían cuando el comando que se ejecuta es de tipo ogr y la salida de información del comando ha lanzado un mensaje de progreso. Este tipo de mensajes de progreso indican dos cosas: el porcentaje de completitud de la tarea, y un mensaje informativo.

Mensajería

Los puertos, certificados SSL utilizados y direcciones ip del job receiver son configurables en los ficheros de configuración config.py de cada servicio web. Por defecto, el servicio web job executer se ejecuta en el puerto 1100, y el job receiver en el 1101.

Los mensajes que se intercambian en este protocolo son los siguientes:

Job Execution Request

Es el mensaje que envía la consola web al servicio job executer de un cliente cuando desde la consola web se solicita la realización de una tarea. La petición debe ir a la url /jobrequest/(?P<id>[0-9]+) del servicio job executer. El id se utilizará para luego poder referenciar este trabajo, y el contenido de los mensajes tiene formato JSON, con los siguientes campos:

{
   'type': '(command|ogr)',
   'command': '<command name>',
   'args' : ['arg1', 'arg2', 'arg3', ...],
   'sequential': (True|False)
   'files': ['data in file 1', 'data in file2', ...]
}

Sólo los dos primeros campos (type y command) son requeridos, el resto son opcionales:

  • El campo type es requerido e indica el tipo de comando y tiene dos posibles valores:
    • command, para ejecutar comandos del sistema.
    • ogr, para ejecutar comandos de ogr.
  • El campo command es requerido e indica qué comando ejecutar.
    • Ejemplos de comandos del sistema (cuando type es command):
      • ls
      • cat
      • /usr/bin/python
    • Ejemplos de comandos ogr:
      • Boot.sh
      • GetIpAddress.sh
  • El campo args es opcional y indica los argumentos que se le pasarán al comando a ejecutar, y es una lista de cadenas. Por ejemplo si queremos ejecutar cat /dev/null, el valor de args sería ['/dev/null'].
  • El campo sequential es opcional e indica si el comando se debe ejecutar inmediatamente (False), o debe encolarse de tal manera que se ejecute en la cola de comandos importantes que se deben ejecutar uno detrás de otro (True). Por defecto los comandos se ejecutan inmediatamente sin ser encolados.
  • El campo files es opcional y contiene una lista de cadenas que contienen datos que deben meterse en un fichero temporal y pueden ser referenciados mediante la lista de argumentos args. Así, el primer fichero puede ser referenciado en args utilizando un argumento con valor '$0', el segundo fichero con '$1', y así sucesivamente.

Job Update

Un mensaje de tipo Job Update es enviado desde el servicio job executer de un cliente al servicio job receiver de un servidor opengnsys. El objetivo de este mensaje es mandar información actualizada referente a la ejecución de un comando desde el cliente al servidor.

La petición debe ir a la url /updatejob/normal/(?P<id>\d+)/(?P<status>[A-Z]+). El id es único y se refiere al id del trabajo (Job) que fue recibido por el cliente en un mensaje del tipo anterior (Job Execution Request), y status es el estado del trabajo.

El contenido del mensaje se tratará como texto plano y se guardará tal cual en la base de datos del servidor, para que posteriormente sea procesador por la función de callback de dicho Job, si tuviera.

Es una práctica común que dicho mensaje, que proviene de un comando ejecutado en el cliente (ya sea un comando nativo o de OGR) esté codificado en JSON, y que la función de callback lo procese como tal a partir del texto del mensaje en la BD, pero no es necesario. De hecho, lo normal es que sólo algunos comandos de OGR estén codificados en JSON, puesto que los comandos nativos de Linux no suelen devolver su salida en formato JSON.

La cadena status puede ser:

  • FINISHED, que significa que el trabajo ha terminado correctamente.
  • ERROR, si la ejecución del comando dio algún tipo de error.
  • INPROGRESS, cuando se trata de un trabajo lento para indicar al servidor que sigue en ejecución.

Job Progress Update

Un mensaje de tipo Job Progress Update es enviado desde el servicio job executer de un cliente al servicio job receiver de un servidor opengnsys. El objetivo de este mensaje es mandar información actualizada referente al progreso de la ejecución de un comando desde el cliente al servidor.

La petición debe ir a la url /updatejob/progress/(?P<id>\d+)/(?P<progress>\d+). El id es único y se refiere al id del trabajo (Job) que fue recibido por el cliente en un mensaje del tipo anterior (Job Execution Request), y progress indica el porcentaje de finalización (un número de 0 a 100) del trabajo.

El contenido del mensaje se tratará como texto plano, suele ser un corto texto de una línea y se guardará tal cual en la base de datos del servidor, para que posteriormente sea procesador por la función de callback de dicho Job, si tuviera.

Last modified 7 years ago Last modified on Jul 14, 2017, 1:07:08 PM