From 03d56a93babbaf3c485ced155e3ac6bbc64e15df Mon Sep 17 00:00:00 2001 From: lgromero Date: Fri, 7 Jun 2024 15:31:42 +0200 Subject: [PATCH] refs #437 Adds new documentation with endpoints and flux of works of ogboot with ogcore --- docs/ogboot-ogcore-communication-design.md | 686 +++++++++++++++++++++ 1 file changed, 686 insertions(+) create mode 100644 docs/ogboot-ogcore-communication-design.md diff --git a/docs/ogboot-ogcore-communication-design.md b/docs/ogboot-ogcore-communication-design.md new file mode 100644 index 0000000..bcb6654 --- /dev/null +++ b/docs/ogboot-ogcore-communication-design.md @@ -0,0 +1,686 @@ +## Diseño de la Lógica y Comunicación entre los Endpoints del Componente `ogboot` y el Servidor `ogCore` + +### Introducción + +El componente `ogboot` se encarga de la gestión y configuración de archivos de arranque (iPXE) y plantillas en un entorno de despliegue de imágenes. El servidor `ogCore` es el núcleo que interactúa con `ogboot` para realizar operaciones de administración y configuración. Este documento describe la lógica y la comunicación entre los endpoints del componente `ogboot` y el servidor `ogCore`. + +### Endpoints del Componente `ogboot` + + +#### Endpoints del Recurso `oglive` + +1. **Ver todos los ogLives instalados (OGCORE)** + - **URL**: `/ogboot/v1/oglives/all` + - **Método HTTP**: GET + - **Descripción**: Obtiene información sobre todos los ogLives instalados. + - **Respuesta**: + ```json + [ + "ogLive-5.0.0-r20190605", + "ogLive-5.11.0-r20210413", + "ogLive-5.13.0-27-r20210706" + ] + ``` + + +2. **Obtener Información de un ogLive (OGCORE)** + - **URL**: `/ogboot/v1/oglives/{name}` + - **Método HTTP**: GET + - **Descripción**: Obtiene información sobre un cliente ogLive instalado utilizando su nombre. + - **Parámetros**: + - `name` (string): Nombre del ogLive. + - **Respuesta**: + ```json + { + "distribution": "focal", + "kernel": "5.13.0-27", + "architecture": "amd64", + "revision": "r20210706.5b4bf5f", + "directory": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f", + "iso": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso" + } + ``` + - **Respuestas**: + - **200 OK**: Información del ogLive obtenida exitosamente. + - **404 Not Found**: ogLive no encontrado. + +3. **Obtener Información del ogLive Predeterminado (OGCORE)** + - **URL**: `/ogboot/v1/oglives/default` + - **Método HTTP**: GET + - **Descripción**: Obtiene información sobre el cliente ogLive predeterminado. + - **Ejemplo de Solicitud**: + ```bash + curl -X GET -H "Authorization: $API_KEY" http://example.com/ogboot/v1/oglives/default + ``` + - **Respuesta**: + ```json + { + "distribution": "focal", + "kernel": "5.13.0-27", + "architecture": "amd64", + "revision": "r20210706.5b4bf5f", + "directory": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f", + "iso": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso" + } + ``` + + - **Respuestas**: + - **200 OK**: Información del ogLive predeterminado obtenida exitosamente. + - **500 Internal Server Error**: Error al obtener la información del ogLive predeterminado. + + +4. **Establecer ogLive Predeterminado** + - **URL**: `/ogboot/v1/oglives/default/{name}` + - **Método HTTP**: POST + - **Descripción**: Establece un cliente ogLive como predeterminado utilizando su nombre. + - **Parámetros**: + - `name` (string): Nombre del ogLive a establecer como predeterminado. + - **Respuestas**: + - **200 OK**: ogLive establecido como predeterminado exitosamente. + - **404 Not Found**: ogLive no encontrado. + - **500 Internal Server Error**: Error al establecer el ogLive como predeterminado. + + + +5. **Ver la lista de ogLives disponibles para descargar** + - **URL**: `/ogboot/v1/oglives/isos` + - **Método HTTP**: GET + - **Respuesta**: + ```json + [ + { + "id": "1", + "filename": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso", + "installed": false, + "compatible": true + }, + { + "id": "2", + "filename": "ogLive-focal-5.11.0-22-generic-amd64-r20210413.992ebb9.iso", + "installed": false, + "compatible": true + }, + { + "id": "3", + "filename": "ogLive-focal-5.8.0-50-generic-amd64-r20210413.992ebb9.iso", + "installed": false, + "compatible": true + }, + { + "id": "4", + "filename": "ogLive-bionic-5.4.0-40-generic-amd64-r20200629.85eceaf.iso", + "installed": false, + "compatible": true + }, + + ] + + ``` + - **500 Internal Server Error**: Error en la conexión. + + +6. **Crear un ogLive** + - **URL**: `/ogboot/v1/oglives` + - **Método HTTP**: POST + - **Descripción**: Crea un nuevo ogLive utilizando el nombre del ISO proporcionado. + - **Cuerpo de la Solicitud**: + ```json + { + "isoName": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso" + } + ``` + - **Ejemplo de Solicitud**: + ```bash + curl -X POST -H "Authorization: $API_KEY" -d '{"isoName": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso"}' http://example.com/ogboot/v1/oglives + ``` + - **Respuestas**: + - **200 OK**: ogLive creado exitosamente. + - **400 Bad Request**: Error en los datos proporcionados. + - **500 Internal Server Error**: Error al crear el ogLive. + +7. **Eliminar un ogLive** + - **URL**: `/ogboot/v1/oglives/{name}` + - **Método HTTP**: DELETE + - **Descripción**: Elimina un ogLive específico utilizando su nombre. + - **Parámetros**: + - `name` (string): Nombre del ogLive. + - **Respuestas**: + - **200 OK**: ogLive eliminado exitosamente. + - **404 Not Found**: ogLive no encontrado. + - **500 Internal Server Error**: Error al eliminar el ogLive. + + + +#### Endpoints del Recurso `pxe` y `pxe-template` + +1. **Obtener Todos los Archivos de Arranque** + - **URL**: `/ogboot/v1/pxes` + - **Método HTTP**: GET + - **Descripción**: Obtiene una lista de todos los archivos de arranque disponibles. + - **Respuesta**: Lista de archivos de arranque en formato JSON. + +2. **Obtener Configuración de Arranque** + - **URL**: `/ogboot/v1/pxes/{mac}` + - **Método HTTP**: GET + - **Descripción**: Obtiene el contenido del archivo de configuración de arranque específico para un cliente utilizando su dirección MAC. + - **Respuesta**: Archivo de arranque en formato adecuado. + ```json + { + "template_name": "pxe", + "mac": "00:50:56:22:11:12", + "lang": "es_ES.UTF-8", + "ip": "192.168.2.11", + "server_ip": "192.168.2.1", + "router": "192.168.2.1", + "netmask": "255.255.255.0", + "computer_name": "pc11", + "netiface": "eth0", + "group": "Aula_virtual", + "ogrepo": "192.168.2.1", + "oglive": "192.168.2.1", + "oglog": "192.168.2.1", + "ogshare": "192.168.2.1", + "oglivedir": "ogLive", + "ogprof": "false", + "hardprofile": "", + "ogntp": "", + "ogdns": "", + "ogproxy": "", + "ogunit": "", + "resolution": "788" + } + + ``` +3. **Crear Archivo de Arranque** + - **URL**: `/ogboot/v1/pxes` + - **Método HTTP**: POST + - **Descripción**: Crea un nuevo archivo de arranque utilizando los parámetros proporcionados. + - **Cuerpo de la Solicitud**: + ```json + { + "template_name": "pxe", + "mac": "00:50:56:22:11:12", + "lang": "es_ES.UTF-8", + "ip": "192.168.2.11", + "server_ip": "192.168.2.1", + "router": "192.168.2.1", + "netmask": "255.255.255.0", + "computer_name": "pc11", + "netiface": "eth0", + "group": "Aula_virtual", + "ogrepo": "192.168.2.1", + "oglive": "192.168.2.1", + "oglog": "192.168.2.1", + "ogshare": "192.168.2.1", + "oglivedir": "ogLive", + "ogprof": "false", + "hardprofile": "", + "ogntp": "", + "ogdns": "", + "ogproxy": "", + "ogunit": "", + "resolution": "788" + } + + ``` + - **Respuesta**: Mensaje de éxito o error. + +4. **Eliminar Archivo de Arranque** + - **URL**: `/ogboot/v1/pxes/{name}` + - **Método HTTP**: DELETE + - **Descripción**: Elimina un archivo de arranque específico utilizando su dirección MAC. + - **Respuesta**: Mensaje de éxito o error. + +5. **Obtener Todas las Plantillas de Arranque** + - **URL**: `/ogboot/v1/pxe-templates` + - **Método HTTP**: GET + - **Descripción**: Obtiene una lista de todas las plantillas de arranque disponibles. + - **Respuesta**: Lista de plantillas en formato JSON. + ```json + { + "templates": [ + "pxe", + "pxe2", + "pxe_default" + ] + } + ``` +6. **Obtener Contenido de una Plantilla** + - **URL**: `/ogboot/v1/pxe-templates/{name}` + - **Método HTTP**: GET + - **Descripción**: Obtiene el contenido de una plantilla de arranque específica utilizando su nombre. + - **Respuesta**: Contenido de la plantilla en formato adecuado. + +7. **Crear Plantilla de Arranque** + - **URL**: `/ogboot/v1/pxe-templates` + - **Método HTTP**: POST + - **Descripción**: Crea una nueva plantilla de arranque utilizando los datos proporcionados. + - **Cuerpo de la Solicitud**: + ```json + { + "name_template": "pxe", + "content_template": "contenido_de_la_plantilla" + } + ``` + - **Respuesta**: Mensaje de éxito o error. + +8. **Eliminar Plantilla de Arranque** + - **URL**: `/ogboot/v1/pxe-templates/{name}` + - **Método HTTP**: DELETE + - **Descripción**: Elimina una plantilla de arranque específica utilizando su nombre. + - **Respuesta**: Mensaje de éxito o error. + + + + +## Flujos de Trabajo + +Para los nuevos flujos de trabajo, asumimos que habrá al menos una nueva tabla en ogCore para almacenar la información de los ogLives y su estado. Esta tabla permitirá a ogCore gestionar y sincronizar la información con ogBoot. + + +### Propuesta de definición de la tabla `ogLive` + + +| Atributo | Tipo de Dato | Descripción | +|----------------|----------------|-----------------------------------------------------------------| +| `id` | `SERIAL` | Identificador único del registro, clave primaria. | +| `distribution` | `VARCHAR(50)` | Nombre de la distribución del ogLive (por ejemplo, "focal"). | +| `kernel` | `VARCHAR(100)` | Versión del kernel del ogLive. | +| `architecture` | `VARCHAR(10)` | Arquitectura del ogLive (por ejemplo, "amd64"). | +| `revision` | `VARCHAR(50)` | Revisión del ogLive (por ejemplo, "r20210706"). | +| `directory` | `VARCHAR(100)` | Nombre del directorio del ogLive en el sistema de archivos. | +| `iso` | `VARCHAR(255)` | Nombre del archivo ISO del ogLive. | +| `is_default` | `BOOLEAN` | Indica si el ogLive es el predeterminado (`true` o `false`). | + +### Ejemplo de Registro + +| `id` | `distribution` | `kernel` | `architecture` | `revision` | `directory` | `iso` | `is_default` | +|------|----------------|---------------------|----------------|-------------|--------------------------|-------------------------------------------------------|--------------| +| 1 | focal | 5.13.0-27-beta | amd64 | r20210706 | ogLive-5.13.0-r20210706 | ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso | true | + + + + +### Flujo de Trabajo: `oglive` + + +### Propuesta de Flujo de Trabajo para `ogLive` + +#### 1. Consultar los `ogLives` Instalados + +- **Descripción**: Obtener la lista de `ogLives` que están actualmente instalados en el sistema. +- **Realización**: Puede realizarse directamente desde **`ogCore`** mediante una consulta a la base de datos `oglives`. + +```sql +SELECT * FROM oglives; +``` + +#### 2. Consultar los `ogLives` disponibles para descargar + +- **Descripción**: Obtener una lista de `ogLives` disponibles para descargar desde el servidor. +- **Realización**: Necesita comunicación con **`ogBoot`**. Nota: Este proceso requiere de una consulta a Trac que se podría llevar a cabo desde el ogCore. + +**Endpoint**: +- **`ogBoot`**: `/ogboot/v1/isos` +- **Método**: `GET` + +#### 3. Instalar un `ogLive` + +- **Descripción**: Instalar un `ogLive` seleccionado en el sistema. +- **Realización**: Requiere comunicación con **`ogBoot`** + +**Endpoint**: +- **`ogBoot`**: `/ogboot/v1/oglives` +- **Método**: `POST` +- **Cuerpo de la Solicitud**: + ```json + { + "isoname": "ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso" + } + ``` + +#### 4. Revisar un `ogLive` Instalado + +- **Descripción**: Obtener detalles sobre un `ogLive` específico que está instalado. +- **Realización**: Puede realizarse desde **`ogCore`** mediante una consulta a la base de datos `oglives`. + +**Consulta SQL**: +```sql +SELECT * FROM oglives WHERE directory = 'ogLive-5.13.0-r20210706'; +``` + +#### 5. Ver el `ogLive` por Defecto + +- **Descripción**: Obtener el `ogLive` que está configurado como predeterminado. +- **Realización**: Puede realizarse desde **`ogCore`** mediante una consulta a la base de datos `oglives`. + +**Consulta SQL**: +```sql +SELECT * FROM oglives WHERE is_default = true; +``` + +#### 6. Asignar `ogLive` por Defecto + +- **Descripción**: Configurar un `ogLive` instalado como el predeterminado. +- **Realización**: Requiere comunicación con **`ogBoot`** para modificar el oglive por defecto en el tftpboot del **`ogBoot`** + + +**Endpoint**: +- **`ogBoot`**: `/ogboot/v1/oglives/default` +- **Método**: `POST` +- **Cuerpo de la Solicitud**: + ```json + { + "name": "ogLive-5.13.0-r20210706" + } + ``` + +#### 7. Desinstalar un `ogLive` + +- **Descripción**: Eliminar un `ogLive` instalado del sistema. +- **Realización**: Requiere comunicación con **`ogBoot`** + +**Endpoint**: +- **`ogBoot`**: `/ogboot/v1/oglives/uninstall` +- **Método**: `DELETE` +- **Cuerpo de la Solicitud**: + ```json + { + "name": "ogLive-5.13.0-r20210706" + } + ``` + + +#### 8. Revisar estado de ogboot + +- **Descripción**: Comparar el estado actual de `ogboot` con la base de datos de `ogCore`, generando un informe de discrepancias. +- **Realización**: Requiere comunicación con **`ogBoot`** para obtener el estado actual de los `ogLives` instalados, el `ogLive` por defecto, y las plantillas de arranque (`pxes`). Luego, `ogCore` compara estos datos con su base de datos y devuelve un informe de discrepancias. + +**Endpoint**: +- **`ogBoot`**: `/ogboot/v1/status` +- **Método**: `GET` +- **Resultado de la Solicitud**: + ```json + { + "installed_oglives": [ + { + "name": "ogLive-5.13.0-r20210706", + "kernel": "5.13.0-27-beta", + "revision": "r20210706", + "default": true + }, + { + "name": "ogLive-5.11.0-r20210413", + "kernel": "5.11.0-22-generic", + "revision": "r20210413", + "default": false + } + ], + "installed_pxe_templates": [ + "default.ipxe", + "template1.ipxe" + ] + } + ``` + +**Informe de Discrepancias** (Ejemplo): +```json +{ + "discrepancies": { + "oglives": [ + { + "expected": { + "name": "ogLive-5.13.0-r20210706", + "default": true + }, + "actual": { + "name": "ogLive-5.11.0-r20210413", + "default": true + } + } + ], + "pxe_templates": [ + { + "expected": "default.ipxe", + "actual": "template1.ipxe" + } + ] + } +} +``` + + +#### 9. Sincronizar Datos de `ogboot` con `ogCore` + +- **Descripción**: `ogCore` sincroniza su base de datos con el estado actual de `ogboot`. Este proceso solo actualiza las discrepancias detectadas. +- **Realización**: Requiere comunicación con **`ogBoot`** para obtener el estado actual. Luego, `ogCore` actualiza su base de datos con cualquier cambio detectado en los `ogLives` instalados, el `ogLive` por defecto, y las plantillas de arranque (`pxes`). + +**Endpoint**: +- **`ogBoot`**: `/ogboot/v1/sync` +- **Método**: `GET` +- **Resultado de la Solicitud**: + ```json + { + "installed_oglives": [ + { + "name": "ogLive-5.13.0-r20210706", + "kernel": "5.13.0-27-beta", + "revision": "r20210706", + "default": true + }, + { + "name": "ogLive-5.11.0-r20210413", + "kernel": "5.11.0-22-generic", + "revision": "r20210413", + "default": false + } + ], + "installed_pxe_templates": [ + "default.ipxe", + "template1.ipxe" + ] + } + ``` + + + + +### Flujo de Trabajo: `pxe y pxe-template` + +#### NOTA + +En la implementación actual de OpenGnsys, se realiza una consulta SQL a la tabla `ordenadores`, haciendo joins con tablas como `aulas`, `centros`, `entidades`, etc. (consultar fichero `opengnsys/server/bin/setclientmode`) para obtener todos los parámetros necesarios para la creación de archivos PXE. Es necesario estudiar si existe la necesidad de crear una tabla `pxe` para almacenar estos parámetros. En caso de decidirse la creación de dicha tabla, podría tener los siguientes atributos: + +- `template_name` (nombre de la plantilla) +- `mac` (dirección MAC) +- `lang` (idioma) +- `ip` (dirección IP) +- `server_ip` (dirección IP del servidor) +- `router` (router) +- `netmask` (máscara de red) +- `computer_name` (nombre del equipo) +- `netiface` (interfaz de red) +- `group` (grupo) +- `ogrepo` (IP del repositorio) +- `oglive` (IP del servidor en vivo) +- `oglog` (IP del servidor de logs) +- `ogshare` (IP del servidor compartido) +- `oglivedir` (directorio en vivo) +- `ogprof` (es profesor) +- `hardprofile` (perfil de hardware) +- `ogntp` (servidor NTP) +- `ogdns` (servidor DNS) +- `ogproxy` (servidor proxy) +- `ogunit` (directorio de unidad) +- `resolution` (resolución de pantalla) + +--- + +#### NOTA 2 + +¿Tiene sentido hacer una tabla para las plantillas pxe-templates? Solo tendrian dos atributos: template-name y content. ¿No sería mejor que quedasen guardadas en el ogboot y se usen cuando se vaya a crear un fichero de arranque? + + +Para estos flujos asumiremos que NO se han creado tablas a mayores de pxe ni de pxe-templates. Este es el flujo original que se produce actualmente en ogboot. + + + +1. **Obtener Todos los Archivos de Arranque** + - **URL**: `/ogboot/v1/pxes` + - **Método HTTP**: GET + - **Cuerpo de la Solicitud**: + ```json + { + { + "boot_files": [ + "01-00:50:56:20:69:11", + "01-00:50:56:20:69:12" + ] + } + } + ``` + + +2. **Obtener Configuración de Arranque por MAC** + - **URL**: `/ogboot/v1/pxes/{mac}` + - **Método HTTP**: GET + - **Cuerpo de la Solicitud**: + - **Respuesta**: + ```json + { + "template_name": "pxe", + "mac": "00:50:56:22:11:12", + "lang": "es_ES.UTF-8", + "ip": "192.168.2.11", + "server_ip": "192.168.2.1", + "router": "192.168.2.1", + "netmask": "255.255.255.0", + "computer_name": "pc11", + "netiface": "eth0", + "group": "Aula_virtual", + "ogrepo": "192.168.2.1", + "oglive": "192.168.2.1", + "oglog": "192.168.2.1", + "ogshare": "192.168.2.1", + "oglivedir": "ogLive", + "ogprof": "false", + "hardprofile": "", + "ogntp": "", + "ogdns": "", + "ogproxy": "", + "ogunit": "", + "resolution": "788" + } + + ``` + +3. **Obtener Todas las Plantillas de Arranque** + - **URL**: `/ogboot/v1/pxe-templates` + - **Método HTTP**: GET + - **Respuesta**: + ```json + { + "templates": [ + "pxe", + "pxe_default" + ] + } + ``` +4. **Crear Plantilla de Arranque** + - **URL**: `/ogboot/v1/pxes-templates` + - **Método HTTP**: POST + - **Cuerpo de la Solicitud**: + ```json + { + "name_template": "pxe2", + "content_template": "#!ipxe\\nset timeout 0\\nset timeout-style hidden\\n\\nset ISODIR ogLive\\nset default 0\\nset kernelargs INFOHOST\\nkernel tftp://SERVERIP/ogLive/ogvmlinuz ${kernelargs}\\ninitrd tftp://SERVERIP/ogLive/oginitrd.img\\nboot" + } + ``` + - **Respuesta**: + ```json + { + "message": "Plantilla creada exitosamente.", + "template": "#!ipxe\\nset timeout 0\\nset timeout-style hidden\\n\\nset ISODIR ogLive\\nset default 0\\nset kernelargs INFOHOST\\nkernel tftp://SERVERIP/ogLive/ogvmlinuz ${kernelargs}\\ninitrd tftp://SERVERIP/ogLive/oginitrd.img\\nboot" + } + ``` + +5. **Obtener Todas las Plantillas de Arranque** + - **URL**: `/ogboot/v1/pxe-templates` + - **Método HTTP**: GET + - **Respuesta**: + ```json + { + "templates": [ + "pxe", + "pxe2" + "pxe_default" + ] + } + ``` +6. **Crear archivo de Arranque** + - **URL**: `/ogboot/v1/pxes` + - **Método HTTP**: POST + - **Respuesta**: + ```json + { + "template_name": "pxe2", + "mac": "00:50:56:22:11:13", + "lang": "es_ES.UTF-8", + "ip": "192.168.2.11", + "server_ip": "192.168.2.1", + "router": "192.168.2.1", + "netmask": "255.255.255.0", + "computer_name": "pc13", + "netiface": "eth0", + "group": "Aula_virtual", + "ogrepo": "192.168.2.1", + "oglive": "192.168.2.1", + "oglog": "192.168.2.1", + "ogshare": "192.168.2.1", + "oglivedir": "ogLive", + "ogprof": "false", + "hardprofile": "", + "ogntp": "", + "ogdns": "", + "ogproxy": "", + "ogunit": "", + "resolution": "788" + } + ``` +7. **Obtener Todos los Archivos de Arranque** + - **URL**: `/ogboot/v1/pxes` + - **Método HTTP**: GET + - **Cuerpo de la Solicitud**: + ```json + { + { + "boot_files": [ + "01-00:50:56:20:69:11", + "01-00:50:56:20:69:12", + "01-00:50:56:20:69:13" + ] + } + } + ``` + +8. **Borrado de un fichero de arranque** + - **URL**: `/ogboot/v1/pxes/{mac}` + - **Método HTTP**: DELETE + - **Respuesta**: + ```json + { + "message": "El archivo de arranque se eliminó correctamente" + } + ``` + +9. **Borrado de una plantilla** + - **URL**: `/ogboot/v1/pxe-templates/{name}` + - **Método HTTP**: DELETE + - **Respuesta**: + ```json + { + "message": "Plantilla eliminada correctamente." + } + ``` + +