Modelo de despliegue de APIs

Diagrama de Despliegue

Namespace

Existirá un namespace propio para el API Manager, que hace de puerta de entrada hacia los microservicios y servicios de interoperabilidad tanto para peticiones externas como para internas entre distintos proyectos.

Dentro de él se desplegarán las APIs, que son las interfaces que facilitan estas comunicaciones con el backend, tanto de microservicios como de servicios de interoperabilidad. 

Es necesario en este punto, aclarar que no todos los servicios desarrollados serán desplegados en el API Manager para su consumo y gobierno. Los proyectos de microservicios siempre publicarán sus APIs mientras que no todos los servicios de interoperabilidad lo harán. Esto es así porque estos servicios no tienen por qué ser servicios de uso general o que necesiten ser gobernados y analizados por un API Manager; si no que son servicios que permiten la comunicación entre un microservicio concreto y otro componente que requiere de algún tipo de integración específica o pertenece a un sistema de información corporativo.

Servicios

Un Servicio es un recurso de la plataforma que proporciona un punto de acceso estable a una aplicación ejecutándose en un conjunto de pods como un servicio de red. Los Servicios permiten acceder a los pods, que son entidades efímeras y pueden ser destruidos y creados nuevamente, a través de una dirección IP estable y un nombre de DNS. Esto es crucial para asegurar la estabilidad y la accesibilidad de las aplicaciones en un entorno de contenedores.

El uso de los servicios es especialmente útil en la arquitectura de APIs para poder configurar los endpoints de las APIs. Al ser los pods entidades efímeras, las APIs no pueden apuntar a estos de forma directa porque tendrían que ser modificadas en cada reinicio de pods y escalado de los mismo. Por lo tanto, los endpoints deben apuntar al servicio configurado que, además de proporcionar una IP y DNS fijos, tiene la capacidad de balancear la carga entre todos los pods desplegados y, junto con las políticas establecidas de escalado, es capaz descubrir todos los pods que se vayan creando (y los que se eliminen) y así ajustar su política de balanceo. 

Despliegue vs Publicación

Previo a la presentación propiamente dicho de las distintas posibilidades de desplegar una API, es necesario explicar la diferencia entre desplegar una API y publicarla. Vamos a usar el siguiente diagrama de estados de la plataforma API Publisher que ayudará a esta explicación.

• Develop: es el estado inicial, que se establece al crear una API a partir de su especificación. En este estado, la API solo es visible en el API Publisher y no se pueden realizar pruebas, solo ver y modificar la configuración.
• Deploy: este estado es transitable desde develop cuando se configuran tanto los business plan, que son los planes que indican los máximos de peticiones permitidas por minuto, y los endpoints. En este estado, la API se envía al Gateway, que es el encargado de manejar las solicitudes entrantes; por lo que puede recibir tráfico pero solo desde el API Publisher; no es accesible para los usuarios finales. Una vez desplegada, se activa también el estado Test ya que se permite hacer pruebas desde el API Publisher.
• Publish: tras ser desplegada, puede transitar a publicada. En este estado, ya es visible desde el API Portal para que los desarrolladores puedan explorarla, suscribirse y comenzar a usarla en sus aplicaciones. La publicación marca el punto en el que la API está lista para ser consumida públicamente.

Como resumen, las diferencias claves entre desplegar y publicar, son las siguientes:

• Desplegar es más técnico y se refiere a la preparación interna de la API en el sistema, asegurando que esté lista para funcionar y recibir solicitudes en el gateway.

• Publicar es más sobre la exposición de la API a los usuarios finales, permitiendo que desarrolladores externos puedan descubrirla, suscribirse y empezar a consumirla.

   

Despliegue de APIs

Ahora que está explicada la diferencia de conceptos, se van a explicar los distintos métodos para realizar el despliegue de las APIs, que puede realizarse de forma manual y de forma automática.

Desde la Oficina de Arquitectura recomendamos siempre el despliegue de forma automática. No obstante, se van a explicar ambas opciones.

Despliegue manual 

El despliegue de forma manual de APIs, se puede realizar de dos formas, según cuál sea el backend de la API.

Distinguiremos el caso más particular como APIs cuyo backend es un servicio desplegado en la plataforma de interoperabilidad, y el caso general, despliegue de cualquier API.

APIs cuyo backend es un servicio de interoperabilidad desplegado

Este método de despliegue se aplica a aquellas APIs que hacen referencia a un servicio de interoperabilidad ya desplegado en la plataforma de interoperabilidad. Estos servicios no tienen por qué estar completamente implementados, es decir, no tienen por qué haber seguido el enfoque Code-First pero sí que al menos han tenido que configurar las interfaces de entrada a los servicios.

El motivo de esta especialización a la hora de desplegar su API es que existe una interconexión entre la plataforma de interoperabilidad y el API Publisher y que, de forma automática, estas API aparecen en el API Publisher como “Catálogo de Servicios” y ya tienen una serie de configuraciones implícitas en relación con el despliegue de la API.

El despliegue manual de este este tipo de APIs se realiza desde el portal del API Publisher y es necesario disponer de los permisos necesarios para acceder al API Publisher y para crear APIs.Se deberán de seguir los siguientes pasos

1. Acceso al Catálogo de Servicios           
   
   Al acceder al API Publisher, habrá que navegar al menú “Catálogo de servicios”, donde se encuentran todos los servicios que han sido desplegados en la plataforma de interoperabilidad y, de los que se puede crear una API.             
               
    
2. Creación de la API           
   
   Para desplegarlo como API, primero hay que crear la API pulsando el botón (+) o accediendo al servicio y dándole a Crear API. Se pedirá introducir el nombre, el contexto y la versión.            
              
    
3. Configuración de la API           
   
   Tras crearla, se podrán realizar las configuraciones necesarias de la API en cuanto a políticas, scopes, seguridad, etc para poder desplegarla. No obstante, en este caso, el endpoint ya estará configurado con la url al servicio desplegado y se asignará un Business Plan (puede ser modificado); por lo tanto, la API está lista para ser desplegada.            
              
    
4. Selección de los Gateway de despliegue            
   
   Para ello, tanto desde la vista general de la API (pulsando en el estado Deploy) o desde el menú Deployments, se indicará el/los Gateway/s donde se desplegará la API.            
              
    
5. Información del despliegue           
   
   Una vez realizada la selección y desplegada la API, saldrá una ventana resumen del despliegue realizado, indicando qué revisión de la API hay desplegada (inicialmente la 1) y en qué Gateways.           
             
    

APIs cuyo backend NO es un servicio de interoperabilidad desplegado

Este método de despliegue se aplica a aquellas API que no hacen referencia a un servicio de interoperabilidad ya desplegado en la plataforma de interoperabilidad. 

Pueden ser tanto APIs de microservicios como APIs de servicios de interoperabilidad no desarrollados aún; es decir, APIs que siguen un enfoque API-First donde en primer lugar se generará el contrato y el despliegue de la API para que las personas que quieran consumirla puedan explorarla, revisar su documentación, testearla e implementarla.

1. Acceso al Catálogo de Servicios           
   
   Al acceder al API Publisher, habrá que navegar al menú “Catálogo de servicios”, donde se encuentran todos los servicios que han sido desplegados en la plataforma de interoperabilidad y, de los que se puede crear una API.             
               
    
2. Importación de Definición de API           
   
   El portal permite crear APIs a través de la importación desde un fichero de especificación, tanto OpenAPI como AsyncAPI; y también realizando su configuración desde cero, indicando los recursos, parámetros, endpoints, etc. Desde la Oficina de Arquitectura y como se indica en las normas, siempre deberá de crearse a partir de la especificación.      
       
    
3. Validación de la Definición de API           
   
   Una vez añadido el fichero con el contrato de la API, se indicará el resultado de validación del contrato (errores, avisos, información y consejos).      
       
    
4. Creación de la Definición de API           
   
   Al continuar, pedirá nombre, contexto y versión de la API. Opcionalmente se puede añadir el endpoint, que, si se ha creado algún mock online, se puede indicar.      
       
    
5. Configuración de la API           
   
   Una vez creada, ya se pueden realizar todas las demás configuraciones de forma manual, al igual que en el caso anterior. Sin embargo, a diferencia del anterior, será necesario configurar los endpoints y los business plan. Desde la visión de Overview (descripción general), tenemos la opción de ver lo que falta para poder desplegar la API; en este caso, las dos cosas que acabamos de indicar.       
       
    
6. Configuración del EndPoint           
   
   Pulsamos en primer lugar sobre Endpoint para realizar la configuración y existen varios tipos de endpoints para añadir (solo se puede seleccionar uno). Lo normal, en caso de API-First será implementar un mock o añadir un endpoint http/rest a un mock realizado con alguna herramienta online.      
       
    
7. Configuración del Business Plan           
   
   Tras realizar la configuración de los endpoint, volvemos a la visión Overview y pulsamos sobre Business Plan e indicamos los planes permitidos para la API.      
       
    
8. Despliegue de la API           
   
   Tras esto, la API está lista para ser desplegada.      
       
    
9. Selección de los Gateway de despliegue           
   
   Para ello, tanto desde la vista general de la API (pulsando en el estado Deploy) o desde el menú Deployments, se indicará el/los Gateway/s donde se desplegará la API.      
       
    
10. Información del despliegue           
    
    Una vez realizada la selección y desplegada la API, saldrá una ventana resumen del despliegue realizado, indicando qué revisión de la API hay desplegada (inicialmente la 1) y en qué Gateways.      
        
     

Despliegue automático

En cuanto al despliegue automático de APIs, la plataforma no hace diferenciación, ya sean de catálogo de servicios o APIs completamente nuevas, siempre se crean de la misma forma.

El despliegue automático de APIs requiere en primer lugar de la creación y configuración de una serie de ficheros que permitirán la creación, configuración y despliegue de la API:

• Especificación de la API.
• Configuración del fichero de parametrización de la API.
• Configuración del fichero de despliegue.

Esto permitirá la creación, configuración y despliegue de una API como si lo hubiéramos hecho de forma manual en la plataforma.

Para llevar a cabo estas configuraciones, se creará un repositorio en Gitlab para proyecto API donde se cree la especificación de la API y se configure el fichero de parametrización. Para saber cómo realizar esto, existirá una guía de desarrollo de la API que irá guiando paso a paso.

Además de esos ficheros, y también explicado en la guía referenciada anteriormente, será necesario crear una colección de postman con los casos de prueba necesarios para validar que la API se ha desplegado de forma correcta.

Por último, el fichero de despliegue será creado de forma interna en el pipeline de despliegue a partir de parámetros introducidos en la misma (gateways donde desplegar).

Todos estos ficheros serán usados para que la pipeline genere un artefacto que será cargado en artifactory y será utilizado para desplegar la API en el API Publisher.

Proceso de Despliegue de APIs

A continuación, se listan los requerimientos que deben de tener los pipelines que despliegan APIs:

• Disparador de evento: Debe existir algún tipo de disparador que inicie el proceso. Este disparador puede ser manual, como pulsar un botón en la plataforma de openshift o automático, como que se dispare el proceso de despliegue al realizar un push en una rama concreta del repositorio de código.
• Los pipelines tienen que obtener la especificación y el fichero de parametrización del servidor de gitlab.
• Los pipelines tienen que validar el formato correcto de los contratos de las APIs mediante Sonarqube.
• Los pipelines tienen que utilizar la herramienta de comandos apictl para crear el artefacto de la API. Este artefacto no es más que un fichero zip con la estructura necesaria para poder ser desplegado posteriormente en el API Publisher.
• Los pipelines tienen que almacenar el artefacto generado en Artifactory.
• Los pipelines tienen que utilizar la herramienta de comandos apictl para importar el artefacto al API Publisher.
• Los pipelines tienen que ejecutar los casos de pruebas de postman proporcionados para verificar el correcto despliegue de la API.

Y en el siguiente diagrama de secuencias, se puede a alto nivel el proceso desde que se inicia la pipeline hasta que se despliega la API y se pasan las pruebas.

Seguridad

Será necesario que el acceso a las APIs esté segurizado.

El API Manager de WSO2 permite varias formas de añadir seguridad a las APIs.

Por un lado, a nivel de capa transporte, además de usar HTTPS, se puede configurar Mutual SSL. Para ello, es necesario cargar los certificados públicos de los clientes que van a consumir la API. Estos tendrán que configurar su certificado privado en el momento de realizar la petición.

Independientemente del uso de Mutual SSL, a nivel de aplicación también hay varias formas de segurizar las APIs:

• OAuth2: utiliza tokens emitidos por un sevidor de autorización (Red Hat build of Keycloak). Tiene distintos flujos de autorización, siendo el de ‘credenciales de cliente’ el más común. Los tokens generados no pueden ser modificados. Pueden tener ‘scopes’ para limitar el ámbito de uso. Tienen tiempo de expiración de validez pero se pueden renovar.

• Autenticación básica: se envían las credenciales (usuario y contraseña) codificadas en Base64 en la cabecera de la petición. 

• Api Key: se envía la clave secreta en la cabecera de la petición. Esta clave identifica unívocamente al cliente. Permite rotar las claves para mantener seguridad.

A continuación, se muestra una pequeña tabla con algunas ventajas y desventajas de las tres opciones y posibles casos de uso.

El flujo para que un cliente pueda consumir una APIs se podría dividir en dos partes: creación / obtención de credenciales y consumo de la API. (En otro documento se desarrollará una guía más completa para clientes).

Flujo de creación / obtención de credenciales:

1. Creación del cliente en el servidor de autorización, ya sea a través del API Portal o mediante algún tipo de gestión de usuarios.
2. Configuración del cliente (posibles roles, ámbitos, …)
3. Obtención de credenciales en función de la tipología configurada 
   1. Generación de id y secreto para OAuth2
   2. Generación de clave para Api Key
   3. Usuario y contraseña para autenticación básica

Flujo de consumo de la API:

1. En el caso de API segurizada con OAuth2, el cliente tendrá que hacer una petición a una URL con su id y secreto para que se le genere su token JWT que utilizará en las peticiones.
2. El cliente realiza una petición a la URL de la API con la autenticación necesaria en la cabecera correspondiente (de forma genérica):
   1. OAuth2: “Authorization: Bearer <token_obtenido>”
   2. Basic: “Authorization: Basic <Base64(usuario:contraseña)>
   3. Api Key: “apikey: <clave secreta>”
3. El API Manager valida que el cliente que realiza la petición tiene privilegios para consumir la API a través de la autorización enviada.
   1. Envía la respuesta obtenida del backend
   2. Envía error si no está autorizado

Como se ha ido comentando, estos clientes tienen que ser gestionados en un servidor de autorización; en nuestro caso será Red Hat build of Keycloak que, internamente, se integrará con otros servicios de autenticación ya existentes en la JdA (SSO Web, ProxyCl@ve, etc).

Observabilidad

En cuanto a la observabilidad, hay que indicar que las APIs como tal no tienen una configuración específica que realizar puesto que

• Por el lado del backend, ya sea un microservicio como sea un servicio de interoperabilidad, son ellos los encargados de realizar y configurar todo lo referente a logs y observabilidad.
• Por el lado del despliegue y la publicación de la API, la plataforma estará configurada para integrarse con distintas herramientas de observabilidad que permitan tener un control de todo lo que ocurre y facilitar la detección temprana de errores y su recuperación.

Open Telemtry Collector

En el namespace del API Manager, se desplegará una instancia del componente de código abierto Open Telemetry Collector. 

Su principal funcionalidad es recopilar y procesar la información de observabilidad recolectada por cada uno de los componentes desplegados en el namespace. 

La información recogida se mandará a los componentes de la Plataforma de Observabilidad para su gestión y visualización.

El principal beneficio de Open Telemetry Collector es que permite aislar a los distintos servicios y resto de componentes de la Plataforma de Observabilidad. Una API no necesita saber a dónde van a dirigirse las métricas, trazas y logs generados; Open Telemetry Collector centraliza la recolección y manda la información a los diferentes destinos que tiene configurado. 

Estos destinos pueden ser las herramientas de observabilidad (Prometheus, Jaeger…) definidas en la Plataforma de Observabilidad centralizada o específicas para un namespace concreto. 

En el diagrama de despliegue se indican los detalles de este componente, además, se proporcionará un documento de despliegue específico para este componente que facilite su instalación en cada namespace.

Para verlo de manera más gráfica, a continuación se muestra un diagrama con los componentes que formarán parte de la observabilidad

• Collector (OpenTelemetry Collector): transforma los datos recibidos mediante protocolo OTLP para poder enviarlos a Logstash, normalmente en JSON. 
• Logstash: procesa los datos recibidos, los filtra, enriquece, transforma o modifica según las necesidades y los envía a Elasticsearch.
• Elasticsearch: es un motor de búsqueda y analítica. Es el núcleo del stack, donde se almacenan los datos procesados por logstash. 
• Kibana: es una herramienta diseñada para la visualización y explotación de datos indexados en Elasticsearch.

Pipeline de Despliegue

<<A completar por el equipo de devops cuando se defina el pipeline>>

Parametrización del Pipeline

<<Parametrización necesaria para ejecutar el pipeline>>

Referencias

• Artifactory 
• Gitlab 
• Jenkins 
• Sonarqube 
• RedHat Openshift
• WSO2 Autenticación
• Red Hat build of Keycloak/
• OpenTelemetry 
• Stack ELK