ogboot-api-documentation #2

Merged
lgromero merged 13 commits from ogboot-api-documentation into main 2024-05-09 13:21:28 +02:00
Collaborator

Objetivo del Pull Request

El presente documento tiene como objetivo guiar al revisor de la Pull Request para validar la entrega correspondiente a la documentación del API ogboot. La documentación abarca la situación inicial del sistema y los endpoints propuestos inicialmente para el servicio ogboot.

  1. Claridad y Coherencia: Verificar que la documentación esté redactada de manera clara y coherente, facilitando la comprensión de los usuarios finales y otros desarrolladores.

  2. Cumplimiento de Estándares: El API ogboot debe seguir las mejores prácticas y estándares de diseño de APIs RESTful, asegurando una estructura coherente, uso adecuado de métodos HTTP y convenciones de nomenclatura.

  3. Cobertura Completa: Asegurarse de que se incluyan todos los endpoints propuestos inicialmente, así como cualquier otro detalle relevante para el entendimiento y uso adecuado del API ogboot.

Descripción del componente Ogboot en licitación UMA

4.1. Situación actual

La aplicación OpenGnsys para gestionar los equipos clientes requiere de un entorno de
ejecución de “prearranque” (PXE).  Este sistema PXE permite que los equipos clientes
inicien un sistema operativo desde la red y puedan particionar su disco duro
remotamente y clonar un sistema operativo en una partición de ese equipo, de esta
manera se disminuye el tiempo en tener un equipo disponible para su explotación.
En la arquitectura actual de OpenGnsys, el entorno PXE lo identificamos como “PXE Boot
Server” y está compuesto por el servicio DHCP y el servicio TFTP (tfpa) y un sistema
operativo diskless “ogLive”.

OpenGnsys PXE Boot Server   

El “Manager” del PXE Boot Serverse encarga de definir el comportamiento de un equipo
cliente cuando se inicia por PXE y que será interpretado por el gestor de arranque
remoto definido en el DHCP.
El “Manager”, por tanto, se encarga de especificar cómo arrancará un equipo
determinado, si por un sistema operativo instalado en una partición concreta o por el
sistema operativo PXE “ogLive OS”, para realizar tareas propias de OpenGnsys.
La arquitectura actual de OG implican que el servicio TFTP y la interfaz web estén en la
misma máquina, ya que la web escribe directamente en el directorio de TFTP.  
El sistema operativo ogLiveOS tiene las limitaciones que la descarga del initrd y el kernel
se hace de manera unicast desde un único el servidor TFTP.  Estas limitaciones quedan
en evidencia cuando el número de equipos a gestionar es elevado, ya que en cada
arranque solicitan al servidor unos 80 MB (initrd y kernel) por UNICAST, ralentizando el
proceso normal de arranque de los equipos, pasando de 60 segundos a más de 5
minutos.  
Para evitar transferencias de red e independizar el tiempo de arranque del número que
equipos que se están iniciando, desde el grupo de desarrollo de OpenGnsys se activó el
mecanismo para almacenar el ogLive en la partición especial de los equiposidentificada
como CACHE. De esta manera se intenta evitar transferencias de red y garantizar un
arranque óptimo. Pero este mecanismo no funciona correctamente en todas las
universidades.
Las opciones de arranque del ogLive se ofrecen como parámetros al initrd del ogLive
desde el fichero del gestor de arranque remoto.  El usuario y contraseña del ogLive para
acceder a los recursos de los servidores no está cifrado dentro del initrd.

Endpoints Propuestos y Acciones Correspondientes

Estos endpoints son los propuestos inicialmente por las Universidades. Actualmente hemos añadido el /downloads a mayores ya que consideramos que el usuario en ogweb pueda recibir una lista de descargas de oglives disponibles desde ogboot.

End Point Acción Propuesta Luis Opción oglive
GET /ogboot/v1/config Devuelve configuración del servicio (1) /ogboot/config config
GET /ogboot/v1/status Devuelve datos del rendimiento: espacio en disco, ...
Gestión ogLive
GET /ogboot/v1/oglives Lista información de todos los ogLives instalados (2) /ogboot/clients/oglives show all
GET /ogboot/v1/oglives/{ID} Muestra información del ogLives solicitado (4) /ogboot/clients/oglives/show/{Index|Dir} show Index|Dir
POST /ogboot/v1/oglives/{ID} Baja e instala el ogLive indicado (11) /ogboot/images/download/{iso} (12) /ogboot/images/upload/{iso} download + install
DELETE /ogboot/v1/oglives/{ID} Desintala ogLive indicado y borra la iso (13) /ogboot/images/remove/{iso} uninstall Iso
GET /ogboot/v1/oglives/default Muestra ogLive por defecto get-default
POST /ogboot/v1/oglives/default Configura ogLive por defecto (3) /ogboot/clients/oglives/show-default set-default
GET /ogboot/v1/oglives/status Muestra chequeo de la consistencia del sistema check
PUT /ogboot/v1/oglives Regenera el archivo de información de los ogLives rebuild
Gestión configuración PXE
GET /ogboot/v1/pxes Listado de los nombres de los archivos PXE (5) /ogboot/clients/pxes
GET /ogboot/v1/pxes/{MAC} Muestra el archivo PXE perteneciente al equipo con MAC dada (6) /ogboot/clients/pxes/{mac}
POST /ogboot/v1/pxes/{MAC} Crea o regenera archivo de configuración PXE del equipo con la MAC dada (7) /ogboot/clients/pxes
PUT /ogboot/v1/pxes/{MAC} Crea o regenera archivo de configuración PXE del equipo con la MAC dada (7) /ogboot/clients/pxes
DELETE /ogboot/v1/pxes/{MAC} Borra el archivo de configuración PXE del equipo con la MAC dada
Gestión plantillas PXE
GET /ogboot/v1/pxe-templates Lista el nombre de todas las plantillas
GET /ogboot/v1/pxe-templates/{NOMBRE} Devuelve el texto de una plantilla
POST /ogboot/v1/pxe-templates/{NOMBRE} Crea o regenera el texto de una plantilla
PUT /ogboot/v1/pxe-templates/{NOMBRE} Crea o regenera el texto de una plantilla

Endpoints finales

End Point Acción
GET /ogboot/v1/config Devuelve la configuración actual del ogboot.
GET /ogboot/v1/status Devuelve la consistencia, errores de incompatibilidad y de configuración.
GET /ogboot/v1/clients/oglives Muestra información en formato JSON sobre todos los clientes ogLive instalados.
GET /ogboot/v1/clients/oglives/{Index} Muestra información en formato JSON sobre un cliente ogLive instalado específico.
GET /ogboot/v1/clients/oglives/default Muestra información en formato JSON sobre el cliente ogLive predeterminado.
POST /ogboot/v1/clients/oglives/default/{Index} Establece un nuevo cliente ogLive como predeterminado utilizando su índice.
POST /ogboot/v1/oglives Descarga y luego instala un nuevo cliente ogLive utilizando el nombre de la imagen como parámetro de entrada
DELETE /ogboot/v1/oglives/{Index} Desinstala un cliente ogLive específico y elimina su imagen asociada.
PUT /ogboot/v1/oglives Regenera el archivo de información de los clientes ogLive instalados.
GET /ogboot/v1/images/download Muestra un menú con opciones para descargar imágenes de ogLive disponibles.
GET /ogboot/v1/pxes Obtiene una lista de todos los archivos de arranque disponibles.
GET /ogboot/v1/clients/pxes/{mac} Obtiene un archivo de arranque específico utilizando la dirección MAC del cliente.
POST /ogboot/v1/pxes Crea un nuevo archivo de arranque utilizando los parámetros proporcionados.
DELETE /ogboot/v1/clients/pxes Elimina un archivo de arranque específico utilizando su identificador único.
PUT /ogboot/v1/pxes Actualiza el repositorio de archivos de arranque con los archivos modificados.
GET /ogboot/v1/pxe-templates Obtiene una lista de todas las plantillas de arranque disponibles.
GET /ogboot/v1/pxe-templates/{nombre} Obtiene el contenido de una plantilla de arranque específica utilizando su nombre.
POST /ogboot/v1/pxe-templates Crea una nueva plantilla de arranque utilizando los datos proporcionados.
PUT /ogboot/v1/pxe-templates/{nombre} Regenera el contenido de una plantilla de arranque específica utilizando su nombre.
DELETE /ogboot/v1/pxe-templates/{nombre} Elimina una plantilla de arranque específica utilizando su nombre.
## Objetivo del Pull Request El presente documento tiene como objetivo guiar al revisor de la Pull Request para validar la entrega correspondiente a la documentación del API ogboot. La documentación abarca la situación inicial del sistema y los endpoints propuestos inicialmente para el servicio ogboot. 1. Claridad y Coherencia: Verificar que la documentación esté redactada de manera clara y coherente, facilitando la comprensión de los usuarios finales y otros desarrolladores. 2. Cumplimiento de Estándares: El API ogboot debe seguir las mejores prácticas y estándares de diseño de APIs RESTful, asegurando una estructura coherente, uso adecuado de métodos HTTP y convenciones de nomenclatura. 3. Cobertura Completa: Asegurarse de que se incluyan todos los endpoints propuestos inicialmente, así como cualquier otro detalle relevante para el entendimiento y uso adecuado del API ogboot. ### Descripción del componente Ogboot en licitación UMA #### 4.1. Situación actual La aplicación OpenGnsys para gestionar los equipos clientes requiere de un entorno de ejecución de “prearranque” (PXE).  Este sistema PXE permite que los equipos clientes inicien un sistema operativo desde la red y puedan particionar su disco duro remotamente y clonar un sistema operativo en una partición de ese equipo, de esta manera se disminuye el tiempo en tener un equipo disponible para su explotación. En la arquitectura actual de OpenGnsys, el entorno PXE lo identificamos como “PXE Boot Server” y está compuesto por el servicio DHCP y el servicio TFTP (tfpa) y un sistema operativo diskless “ogLive”. #### OpenGnsys PXE Boot Server    El “Manager” del PXE Boot Serverse encarga de definir el comportamiento de un equipo cliente cuando se inicia por PXE y que será interpretado por el gestor de arranque remoto definido en el DHCP. El “Manager”, por tanto, se encarga de especificar cómo arrancará un equipo determinado, si por un sistema operativo instalado en una partición concreta o por el sistema operativo PXE “ogLive OS”, para realizar tareas propias de OpenGnsys. La arquitectura actual de OG implican que el servicio TFTP y la interfaz web estén en la misma máquina, ya que la web escribe directamente en el directorio de TFTP.   El sistema operativo ogLiveOS tiene las limitaciones que la descarga del initrd y el kernel se hace de manera unicast desde un único el servidor TFTP.  Estas limitaciones quedan en evidencia cuando el número de equipos a gestionar es elevado, ya que en cada arranque solicitan al servidor unos 80 MB (initrd y kernel) por UNICAST, ralentizando el proceso normal de arranque de los equipos, pasando de 60 segundos a más de 5 minutos.   Para evitar transferencias de red e independizar el tiempo de arranque del número que equipos que se están iniciando, desde el grupo de desarrollo de OpenGnsys se activó el mecanismo para almacenar el ogLive en la partición especial de los equiposidentificada como CACHE. De esta manera se intenta evitar transferencias de red y garantizar un arranque óptimo. Pero este mecanismo no funciona correctamente en todas las universidades. Las opciones de arranque del ogLive se ofrecen como parámetros al initrd del ogLive desde el fichero del gestor de arranque remoto.  El usuario y contraseña del ogLive para acceder a los recursos de los servidores no está cifrado dentro del initrd. ### Endpoints Propuestos y Acciones Correspondientes Estos endpoints son los propuestos inicialmente por las Universidades. Actualmente hemos añadido el /downloads a mayores ya que consideramos que el usuario en ogweb pueda recibir una lista de descargas de oglives disponibles desde ogboot. | End Point | Acción | Propuesta Luis | Opción oglive | |----------------------------|----------------------------------------------------|----------------|---------------| | GET /ogboot/v1/config | Devuelve configuración del servicio | (1) /ogboot/config | config | | GET /ogboot/v1/status | Devuelve datos del rendimiento: espacio en disco, ... | | | | **Gestión ogLive** | | | | | GET /ogboot/v1/oglives | Lista información de todos los ogLives instalados | (2) /ogboot/clients/oglives | show all | | GET /ogboot/v1/oglives/{ID} | Muestra información del ogLives solicitado | (4) /ogboot/clients/oglives/show/{Index\|Dir} | show Index\|Dir | | POST /ogboot/v1/oglives/{ID} | Baja e instala el ogLive indicado | (11) /ogboot/images/download/{iso} (12) /ogboot/images/upload/{iso} | download + install | | DELETE /ogboot/v1/oglives/{ID} | Desintala ogLive indicado y borra la iso | (13) /ogboot/images/remove/{iso} | uninstall Iso | | GET /ogboot/v1/oglives/default | Muestra ogLive por defecto | | get-default | | POST /ogboot/v1/oglives/default | Configura ogLive por defecto | (3) /ogboot/clients/oglives/show-default | set-default | | GET /ogboot/v1/oglives/status | Muestra chequeo de la consistencia del sistema | | check | | PUT /ogboot/v1/oglives | Regenera el archivo de información de los ogLives | | rebuild | | **Gestión configuración PXE** | | | | | GET /ogboot/v1/pxes | Listado de los nombres de los archivos PXE | (5) /ogboot/clients/pxes | | | GET /ogboot/v1/pxes/{MAC} | Muestra el archivo PXE perteneciente al equipo con MAC dada | (6) /ogboot/clients/pxes/{mac} | | | POST /ogboot/v1/pxes/{MAC} | Crea o regenera archivo de configuración PXE del equipo con la MAC dada | (7) /ogboot/clients/pxes | | | PUT /ogboot/v1/pxes/{MAC} | Crea o regenera archivo de configuración PXE del equipo con la MAC dada | (7) /ogboot/clients/pxes | | | DELETE /ogboot/v1/pxes/{MAC} | Borra el archivo de configuración PXE del equipo con la MAC dada | | | | **Gestión plantillas PXE** | | | | | GET /ogboot/v1/pxe-templates | Lista el nombre de todas las plantillas | | | | GET /ogboot/v1/pxe-templates/{NOMBRE} | Devuelve el texto de una plantilla | | | | POST /ogboot/v1/pxe-templates/{NOMBRE} | Crea o regenera el texto de una plantilla | | | | PUT /ogboot/v1/pxe-templates/{NOMBRE} | Crea o regenera el texto de una plantilla | | | ### Endpoints finales | End Point | Acción | |--------------------------------------------------|---------------------------------------------------------------------------------------------| | GET /ogboot/v1/config | Devuelve la configuración actual del ogboot. | | GET /ogboot/v1/status | Devuelve la consistencia, errores de incompatibilidad y de configuración. | | GET /ogboot/v1/clients/oglives | Muestra información en formato JSON sobre todos los clientes ogLive instalados. | | GET /ogboot/v1/clients/oglives/{Index} | Muestra información en formato JSON sobre un cliente ogLive instalado específico. | | GET /ogboot/v1/clients/oglives/default | Muestra información en formato JSON sobre el cliente ogLive predeterminado. | | POST /ogboot/v1/clients/oglives/default/{Index} | Establece un nuevo cliente ogLive como predeterminado utilizando su índice. | | POST /ogboot/v1/oglives | Descarga y luego instala un nuevo cliente ogLive utilizando el nombre de la imagen como parámetro de entrada | | DELETE /ogboot/v1/oglives/{Index} | Desinstala un cliente ogLive específico y elimina su imagen asociada. | | PUT /ogboot/v1/oglives | Regenera el archivo de información de los clientes ogLive instalados. | | GET /ogboot/v1/images/download | Muestra un menú con opciones para descargar imágenes de ogLive disponibles. | | GET /ogboot/v1/pxes | Obtiene una lista de todos los archivos de arranque disponibles. | | GET /ogboot/v1/clients/pxes/{mac} | Obtiene un archivo de arranque específico utilizando la dirección MAC del cliente. | | POST /ogboot/v1/pxes | Crea un nuevo archivo de arranque utilizando los parámetros proporcionados. | | DELETE /ogboot/v1/clients/pxes | Elimina un archivo de arranque específico utilizando su identificador único. | | PUT /ogboot/v1/pxes | Actualiza el repositorio de archivos de arranque con los archivos modificados. | | GET /ogboot/v1/pxe-templates | Obtiene una lista de todas las plantillas de arranque disponibles. | | GET /ogboot/v1/pxe-templates/{nombre} | Obtiene el contenido de una plantilla de arranque específica utilizando su nombre. | | POST /ogboot/v1/pxe-templates | Crea una nueva plantilla de arranque utilizando los datos proporcionados. | | PUT /ogboot/v1/pxe-templates/{nombre} | Regenera el contenido de una plantilla de arranque específica utilizando su nombre. | | DELETE /ogboot/v1/pxe-templates/{nombre} | Elimina una plantilla de arranque específica utilizando su nombre. |
lgromero added 7 commits 2024-03-27 12:52:00 +01:00
lgromero added 1 commit 2024-04-12 13:05:14 +02:00
lgromero requested review from vtroshchinskiy 2024-04-12 15:34:54 +02:00
vtroshchinskiy requested changes 2024-04-18 16:26:17 +02:00
@ -27,0 +50,4 @@
- **Contenido:** Configuración del ogboot en formato JSON.
```json
{
"config-file": "/opt/opengnsys/etc/ogliveinfo.json",

Esto quién lo usa y para que?

La API se puede acceder remotamente, así que que provecho saca el consumidor de rutas que posiblemente no puede acceder?

Esto quién lo usa y para que? La API se puede acceder remotamente, así que que provecho saca el consumidor de rutas que posiblemente no puede acceder?
@ -27,0 +55,4 @@
"download-dir": "/opt/opengnsys/lib",
"install-dir": "/opt/opengnsys/tftpboot",
"default-name": "ogLive",
"min-release": "r20190601"

Que es "min-release"? Hay un estándar de número de versiones?

Esto tiene pinta de algo que se compara para alguna comprobación, pero la "r" inicial lo complica innecesariamente.

Que es "min-release"? Hay un estándar de número de versiones? Esto tiene pinta de algo que se compara para alguna comprobación, pero la "r" inicial lo complica innecesariamente.
Poster
Collaborator

Especificado en el commit 10927d2195 . Entiendo que el estandar viene de la fecha de lanzamiento, la "r" es resultado directo que devuelve el oglivecli que el script encargado de lanzar estas consultas:

{ "param": "min-release", "description": "Mainimum compatibility release", "value": "r$MINREL" }

Se podría estudiar de cambiarlo pero sería tema de otra PR

Especificado en el commit 10927d2195242ec56fa5f49032da18ee6502f93a . Entiendo que el estandar viene de la fecha de lanzamiento, la "r" es resultado directo que devuelve el oglivecli que el script encargado de lanzar estas consultas: `{ "param": "min-release", "description": "Mainimum compatibility release", "value": "r$MINREL" }` Se podría estudiar de cambiarlo pero sería tema de otra PR
README.md Outdated
@ -27,0 +58,4 @@
"min-release": "r20190601"
}
```
- **Código 400 Bad Request:** La solicitud es incorrecta. La configuración del ogboot no se ha obtenido correctamente.

Como puede ser incorrecta una solicitud sin parámetros?

Como puede ser incorrecta una solicitud sin parámetros?
@ -35,0 +78,4 @@
**Respuestas:**
- **Código 200 OK:** La status de ogboot se obtuvo exitosamente.
- **Contenido:** .
Some installed ogLive aren't fully compatible: , , ogLive-3.19.0-i386-r4795

Esto no aparece bien en el resultado, hay algo mal con el formato del markdown.

Esto no aparece bien en el resultado, hay algo mal con el formato del markdown.
README.md Outdated
@ -35,0 +105,4 @@
[
{
"distribution": "focal",

"focal" mas que una distribución es una release de una distribución. Y si queremos Fedora?

"focal" mas que una distribución es una release de una distribución. Y si queremos Fedora?
Poster
Collaborator

Entiendo que oglive está diseñado principalmente para funcionar en sistemas basados en Debian y que no corre en sistemas de Red Hat.

Entiendo que oglive está diseñado principalmente para funcionar en sistemas basados en Debian y que no corre en sistemas de Red Hat.
README.md Outdated
@ -500,1 +225,3 @@
}
```bash
curl -X POST -H "Authorization: $API_KEY" -d "ISO=ogLive-focal-5.13.0-27-beta-amd64-r20210706.5b4bf5f.iso" http://example.com/ogboot/v1/oglive

ISO=ogLive... no es JSON. Puede haber algún problema de parsing aquí?

Hay algo aparte de ISO que se puede pasar? El texto de abajo habla de índices.

`ISO=ogLive...` no es JSON. Puede haber algún problema de parsing aquí? Hay algo aparte de `ISO` que se puede pasar? El texto de abajo habla de índices.
@ -516,0 +252,4 @@
**Respuestas:**
- **Código 200 OK:** El cliente ogLive se desinstaló y su imagen asociada se eliminó correctamente.
- **Código 404 Not Found:** No se encontró ningún cliente ogLive con el índice o nombre de archivo ISO proporcionado.

Puede haber algún otro error aparte de no encontrado? Permiso denegado?

Puede haber algún otro error aparte de no encontrado? Permiso denegado?
lgromero marked this conversation as resolved
@ -523,0 +308,4 @@
**Respuestas:**
- **Código 200 OK:** La lista de todos los archivos de arranque se obtuvo exitosamente.
- **Contenido:** Lista de archivos de arranque en formato JSON.

Falta el formato en la documentación. Simplemente un array, hay mas estructura?

Falta el formato en la documentación. Simplemente un array, hay mas estructura?
@ -523,0 +319,4 @@
**Método HTTP:** GET
**Parámetros de la URL:**
- `{mac}`: La dirección MAC del cliente cuyo archivo de arranque se desea obtener.

De donde obtenemos MACs en la API? La API de "Obtener Todos los Archivos de Arranque" devuelve archivos, MACs, ambas cosas?

De donde obtenemos MACs en la API? La API de "Obtener Todos los Archivos de Arranque" devuelve archivos, MACs, ambas cosas?
README.md Outdated
@ -523,0 +347,4 @@
**Ejemplo de Solicitud:**
```bash
curl -X POST -H "Authorization: $API_KEY" -d '{"name": "bootfile", "config": "some_configuration"}' http://example.com/ogboot/v1/pxes

Esta si usa JSON para parámetros, no es consistente con mas arriba.

Esta si usa JSON para parámetros, no es consistente con mas arriba.
README.md Outdated
@ -523,0 +385,4 @@
**Método HTTP:** PUT
**Cuerpo de la Solicitud:**
- Fichero en json con la configuración de arranque de la máquina

Formato?

Formato?
@ -523,0 +414,4 @@
**Respuestas:**
- **Código 200 OK:** La lista de todas las plantillas de arranque se obtuvo exitosamente.
- **Contenido:** Lista de plantillas de arranque en formato JSON.

Formato?

Formato?
README.md Outdated
@ -523,0 +422,4 @@
Obtiene el contenido de una plantilla de arranque específica utilizando su nombre.
**URL:** `/ogboot/v1/pxe-templates/{nombre}`

El nombre va en la URL, puede haber algún problema con /, espacios, etc?

El nombre va en la URL, puede haber algún problema con /, espacios, etc?
README.md Outdated
@ -523,0 +448,4 @@
**Método HTTP:** POST
**Cuerpo de la Solicitud:**
- Datos necesarios para la creación de la plantilla de arranque, como el nombre y el contenido.

En que formato?

En que formato?
lgromero added 1 commit 2024-04-19 13:01:29 +02:00
lgromero added 1 commit 2024-04-23 09:02:16 +02:00
lgromero added 1 commit 2024-04-23 09:10:17 +02:00
lgromero added 1 commit 2024-04-25 15:15:43 +02:00
lgromero added 1 commit 2024-04-26 11:17:44 +02:00
vtroshchinskiy approved these changes 2024-04-26 15:02:33 +02:00
lgromero merged commit 12ec6caaad into main 2024-05-09 13:21:28 +02:00
Sign in to join this conversation.
No reviewers
No Label
No Milestone
No project
No Assignees
2 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: opengnsys/ogboot#2
There is no content yet.