ogboot-api-documentation #2
No reviewers
Labels
No Label
No Milestone
No project
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: opengnsys/ogboot#2
Loading…
Reference in New Issue
There is no content yet.
Delete Branch "ogboot-api-documentation"
Deleting a branch is permanent. Although the deleted branch may exist for a short time before cleaning up, in most cases it CANNOT be undone. Continue?
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.
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.
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.
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.
Endpoints finales
@ -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?
@ -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.
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
@ -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?
@ -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.
@ -35,0 +105,4 @@
[
{
"distribution": "focal",
"focal" mas que una distribución es una release de una distribución. Y si queremos Fedora?
Entiendo que oglive está diseñado principalmente para funcionar en sistemas basados en Debian y que no corre en sistemas de Red Hat.
@ -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.@ -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?
@ -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?
@ -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?
@ -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.
@ -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?
@ -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?
@ -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?
@ -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?