El objetivo de esta guía es introducir a cualquier desarrollador tanto en la pila tecnológica que se usa para el desarrollo de aplicaciones en Mi Campus, como en los procedimientos de configuración, despliegue y gestión de la calidad.

0. ¿Qué es Mi Campus?

Mi campus es una aplicación frontend implementada en VueJS comunicada con una nube de servicios web desarrollados con Spring Boot que la nutren. Para poder desarrollar y gestionar de manera ágil todo este ecosistema, cada aplicación está alojada en un contenedor Docker que incluye, tanto a ella misma, como un sistema operativo, librerías y configuración necesaria para su ejecución. A su vez también tiene asociada una configuración hardware establecida indicando los requisitos de CPU y RAM que puede llegar a consumir.  Llamaremos Llamaremos POD a una instancia en ejecución de una aplicación concreta.

1. Infraestructura bajo Mi campus

Como hemos visto anteriormente, Mi Campus está constituido por un conjunto de PODs que ejecutan aplicaciones independientes que interactúan entre sí. No obstante es necesario disponer de un sistema que orqueste los diferentes PODs y su configuración, para ello disponemos de Kubernetes (también llamado k8s) que es una plataforma para la gestión y control de contenedores. Gracias a esta herramienta podremos tener una orquestación real de cada POD para que, en caso de necesidad, se creen réplicas ( nuevos PODs réplica ) para soportar una carga mayor y se den de baja cuando no sean necesarios de manera automática y desatendida.

Al mismo tiempo gracias al enfoque IaC (Infraestructure as Code) a partir de un fichero de texto (o conjunto de los mismos), llamado manifiesto, podemos especificar cómo desplegar cada POD, con cuánta memoria mínima o máxima, cuándo escalar el POD en base a límites de recursos, etc. Es decir, todo el trabajo que hay que hacer de manera manual en una infraestructura tradicional los gestionará Kubernetes en base a lo que le indiquemos en los manifiestos. Adicionalmente, todo cluster Kubernetes tiene un punto de entrada, el cual se denomina Ingress, en el cual se pueden establecer reglas de tráfico entre el exterior y los diferentes PODs

2. Desarrollo de servicios

Toda la funcionalidad de Mi Campus se encuentra en la nube de servicios que nutren el frontend. Dichos servicios están desarrollados con el framework FundewebJS basado en SpringBoot y la manera de comunicarse con el frontend es exponiendo una API de servicios, que para Mi Campus será una API de servicios REST. Una API REST se puede resumir como un conjunto de URLs a las que nuestra aplicación es capaz de responder, por tanto, el protocolo de comunicación entre frontend y banckend (nuestros servicios) será mediante HTTP. Es importante conocer bien tanto la pila tecnológica utilizada, como todos los requisitos derivados de una comunicación HTTP.

1. Para trabajar y configurar un proyecto nuevo deberemos leer la guía de FundewebJS
2. Para conocer cómo desarrollar servicios REST correctos, deberemos revisar la Normativa de servicios REST
3. Para saber cómo documentar un servicio REST deberemos seguir las indicaciones de Documentar APIs con OPENAPI  
4. Para desarrollar test en nuestros servicios deberemos leer la guía FundewebJS - Test

3. Arquitectura de proyectos

Los desarrollos de servicios de Mi Campus deben ser totalmente desacoplados para que permitan, si fuera necesario, cambiar el código fuente de un proyecto a otro para reorganizar la arquitectura de los PODs según la demanda de los usuarios. Para ello se ha optado por un enfoque basado en arquitecturas hexagonales (o de cebolla) que dividen el código en tres capas bien definidas de menor a mayor concreción con el dominio del servicio, siendo la capa mas externa la que comunica con cualquier sistema fuera de la aplicación  (base de datos, otros endpoints REST, etc).

Image AddedDiagrama de flujo de dependencias

Para poder definir esta arquitectura nos apoyaremos en el enfoque de diseño de proyectos Domain Driven Design, donde estableceremos dominios que guiarán desde el diseño del core de nuestra aplicación hasta las rutas donde deberán estar los endpoint REST.

A la hora de empezar un nuevo desarrollo, deberemos identificar su dominio y decidir si la funcionalidad a realizar debería incorporarse a un proyecto ya existente, porque ya modela dicho dominio, o bien a uno nuevo porque no estaba contemplado con anterioridad. Igualmente deberemos analizar las rutas de los endpoints que expongamos para que reflejen el dominio modelado más allá del nombre que se le pueda dar al proyecto.

Junto con este modelado, la comunicación interna entre los diferentes elementos del proyecto se hace en base a eventos bajo el principio CQRS (Command Query Responsibility Segregation) que separa las operaciones de lectura de datos de las operaciones de escritura de datos. De esta manera queda totalmente desacoplada cualquier interacción dentro de la aplicación y nos permitirá, en un futuro, poder emitir esos eventos también fuera de la aplicación para que otros servicios "reaccionen" a determinadas acciones. No obstante, actualmente dichos eventos son sólo internos a la aplicación.

Image AddedModelos de escritura y lectura

A nivel técnico, todos los proyectos se crean a partir de una semilla que contiene las librerías necesarias para trabajar, a su vez también se desarrollan librerías internas que pueden incluirse en el proyecto en cualquier momento, tanto en su creación o con posterioridad. Dicha semilla evolucionará junto con la pila tecnológica.

Image Added

4. Seguridad

Un backend de servicios en Mi Campus, usualmente, expone una API REST con una URL determinada al mundo. Es decir, aunque no haya un frontend que invoque nuestros endpoints REST, dicha API ya es accesible vía HTTP por cualquier persona o equipo informático autónomo. Por tanto, desde el momento en el que mi API REST esté desplegada en el entorno de producción es susceptible de ser atacada por cualquiera, por muy extraña o parametrizada que puedan ser las URL de los endpoints REST que se exponen.

Por tanto es crucial que desde el primer momento tengamos presente la seguridad, que va más allá de simplemente validar al usuario/servicio que se conecta ya que un usuario válido del sistema también puede iniciar un ataque, bien de manera intencionada, bien porque en su PC hay código dañino que le ha robado la sesión y/o el token de usuario.

5. Documentación

Todas las APIs del backend deben estar documentadas para que cualquier equipo pueda consultarlas de manera independiente. Dichas APIs se encuentran recogidas en el Catálogo de APIs de ATICA donde cualquiera podrá consultar los métodos que disponen y los resultados. 

Para poder documentar las APIs utilizaremos la iniciativa OpenAPI que establece un lenguaje común para describir los diferentes elementos necesarios para realizar la documentación. Dentro de un proyecto FundewebJS estarán cargadas las librerías necesarias para poder generar esta documentación directamente desde Java, a su vez la guía Documentar APIs con OPENAPI indica cómo podemos configurarlo y utilizarlo.

6. Calidad

La revisión de la calidad de los desarrollos es un paso imprescindible en el desarrollo de los mismos y así se indica en MEDEA P9. Gestión de la calidad del software no obstante, en Mi Campus, al estar dividido entre APIs de servicios distribuidas y un frontend único hay ciertas peculiaridades que debemos tener en cuenta:

• Pruebas de código fuente: Se realizarán tal y como se indica en MEDEA
• Pruebas de accesibilidad web: Sólo se tienen que realizar cuando se realicen cambios en el frontend del proyecto. Deberán ajustarse a los plazos que indica en OAW y se recogen dentro de la metodología.
  • ¿Si hago un pequeño cambio en el frontend de algún servicio tengo que hacer el análisis de la pantalla y actualizar la declaración de accesibilidad?
    • Si el cambio es pequeño y no incorpora elementos nuevos no es necesario porque ya estarán contemplados en la declaración existente. En caso contrario se deberá analizar y, si incorpora nuevos incumplimientos, modificar la declaración de accesibilidad existente.
  • ¿Si hago un cambio sustancial o introduzco un servicio nuevo tengo que hacer el análisis de la pantalla y actualizar la declaración de accesibilidad?
    • En este caso sí que es obligatorio hacer el análisis de la pantalla para detectar nuevos incumplimientos posibles. La declaración de accesibilidad sólo se deberá actualizar si se detectan incumplimientos nuevos.
  • ¿Cuándo debo hacer el informe de accesibilidad que se presenta al Observatorio de Accesibilidad Web?
    • Este informe se hace una vez cada 3 años, salvo que MNCS pida que se haga expresamente, independientemente que durante ese periodo se hayan puesto en marcha nuevos servicios o no.
    • Cuando venzan los 3 años se deberá hacer el informe basándose en todos los análisis de las pantallas ya realizados y ampliando con los servicios nuevos que todavía no tengan el análisis hecho.
• Pruebas de seguridad: Se realizarán tal y como se indica en MEDEA
• Pruebas funcionales: En el caso de mi campus todas las pruebas funcionales de las APIs se deben hacer con Cucumber. De esta manera tenemos, a la vez, test funcionales en el código y pruebas funcionales actualizadas en todo momento. Esto supone un gran beneficio ya que, gracias a cómo se describen los test con Cucumber podemos alinearlos directamente con los requisitos dados por el responsable de la API y utilizar el propio lenguaje usado para describirlos, lo cual facilita el asentamiento del dominio y un punto común entre responsable del producto y API desarrollada.
• Pruebas de carga: Se realizarán tal y como se indica en MEDEA. Se deberán realizar en local para asegurar que la aplicación tiene un buen rendimiento antes de lanzarlos en los servidores con el departamento de sistemas. Desde MNCS se recomienda usar JMeter y VisualVM (en local) para lanzar el test y medir la memoria RAM utilizada. No obstante se puede utilizar cualquier herramienta que permita obtener, al menos, los siguientes resultados:
  • Por cada petición diferente que haga nuestro test
    • Tiempo medio de respuesta
    • Porcentaje de error
    • Bytes transmitidos
    • Número de peticiones realizadas
  • A nivel global:
    • Memoria RAM máxima
    • Memoria RAM mínima
    • Evolución de la memoria RAM durante la ejecución del test
• Pruebas de usabilidad: Se realizarán tal y como se indica en MEDEA
• Pruebas de aceptación: Se realizarán tal y como se indica en MEDEA. En este caso también pueden servir de apoyo los test Cucumber realizados en las pruebas funcionales ya que deberían cubrir todos los requisitos del proyecto.

7. Rendimiento

Es importante resaltar que las APIs alojadas en Mi Campus deben tener un coste bajo tanto en memoria, como en tiempos de respuesta. En el caso de que tengamos problemas con alguna API hay que analizar detenidamente el coste en recursos ya que la arquitectura, al ser ligera, no debería presentar problemas en este punto.

Dependiendo del servicio y sus circunstancias , también podemos establecer los criterios de escalado en la infraestructura, hay servicios más o menos pesados, con más o menos concurrencia. La ventaja de tener un gestor de PODs (Kubernetes) es que el escalado se hará de manera automática según los criterios que establezcamos, por lo que garantizamos que la gestión de los recursos se hace de la manera más óptima posible.

No obstante hay que estar atentos a la monitorización de nuestros PODs para ver si están funcionando correctamente o tienen caídas con determinada frecuencia. Este último aspecto, asumiendo que el servicio está lo más optimizado posible, nos puede indicar si los recursos que tengamos asignados son suficientes o no. En este caso, justificando la necesidad con un estudio del código de la aplicación más su casuística, podremos solicitar más recursos, no obstante nos tendremos que asegurar que no se puede mejorar el rendimiento antes de intentar aumentar el consumo de nuestros PODs.

8. Logs y monitorización

Toda la monitorización que podemos hacer sobre los servicios de Mi Campus se encuentra en Lagar, que es una herramienta que nos va a permitir tanto tener acceso a los logs de las aplicaciones como al rendimiento de los diferentes PODs.

• Sistema de log: La aplicación Kibana nos dará acceso a los diferentes logs de nuestras APIs. El departamento de MNCS se encargará de agrupar y mostrar en Kibana los logs de nuestros servicios de manera que los tengamos fácilmente accesible. Adicionalmente, a partir de esos logs, podremos crear visualizaciones concretas si así lo deseamos.
• Rendimiento de servicios:  La aplicación Grafana recoge todos los datos estadísticos que emiten los diferentes POD's desplegados en Kubernetes y los muestra de manera gráfica. En esta aplicación podemos ver el rendimiento de nuestros servicios tanto a nivel de CPU, RAM, ancho de banda etc. También podemos ver cuándo nuestro servicio ha escalado o no. 

9. Procedimiento de alta de proyectos

El procedimiento de alta de proyectos FundewebJS se realiza en diferentes fases según el estado en el que se encuentre. Este procedimiento es así para asegurar que, cuando se despliega un POD, el código que contiene es válido y funcional, evitando que Kubernetes lance alarmas si el código no funciona correctamente.

Las fases de alta de un proyecto y los jiras que hay que crear 1.2 Alta de proyecto FundeWebJS, no obstante, las fases resumidas son:

• Solicitud de alta de proyecto: Se realiza en APIUM y sólo se creará el repositorio en gitlab pero NO el sistema de despliegue.
• Solicitud de creación de despliegue en desarrollo/test: Se realiza con Jira a MNCS. Requiere tener código válido y funcional en el repositorio. Se creará la configuración de despliegue tanto en desarrollo como en test.
• Solicitud de alta en producción: Se realiza con Jira a MNCS. Se creará la configuración de despliegue de producción.