Uno de los objetivos de la organización es darle a los servicios el enfoque de APIs, de tal manera que puedan ser usados por varios canales dentro y fuera de la organización. También que la misma organización pueda ejecutar acciones de monitoreo de uso y rendimiento, monetización, seguridad, y algunas otras relacionadas con el proceso de API Management.
La arquitectura utilizada para la implementación es una mezcla de varias nubes de Oracle:
- Oracle API Platform Cloud Service
- Oracle Integration Cloud Service
- Oracle Infrastructure Cloud
- Oracle Developer Cloud Service
Voy a enfocar esta entrada del blog a la automatización de los artefactos creados en Oracle API Platform Cloud Service debido a que la arquitectura contempla un plan de recuperación ante desastres, comúnmente llamado DRP.
Oracle API Platform Cloud Service
Esta es la plataforma de API Management que ofrece Oracle. Proporciona funcionalidades típicas de una plataforma de este estilo. A continuación, se listan algunas de sus capacidades:
- Configuración de proveedores de OAuth 2.0
- Administración de usuarios y grupos
- Administración de roles
- Gateways lógicos y físicos
- Gestión de APIs
- Gestión de planes
- Gestión de cuentas de servicio
- Analíticos
- Portales de desarrolladores
- Administración de aplicaciones
Una de las desventajas de este servicio de Oracle es que no cuenta con opciones para realizar la migración de las APIs y Gateways desplegados, hacia una instancia nueva o distinta. Por ejemplo, en el caso de un desastre, tendríamos que encender la instancia contemplada en el DRP. Sin embargo, no existen capacidades para migrar los artefactos de una instancia a otra de manera natural.
Para mayor detalle del servicio de API Management de Oracle, pueden consultar la documentación en la siguiente liga:
REST API
Afortunadamente, el servicio (como casi todos los servicios de nube) cuenta con APIs de tipo REST que nos ayudarán a automatizar el proceso. Esto evitará la necesidad de construir y sincronizar todo de nuevo en la instancia del DRP.
El alcance de las APIs provistas por Oracle incluyen la interacción con distintos elementos de la plataforma. Algunos de ellos son los siguientes:
- APIs
- Aplicaciones
- Deployments
- Gateways
- Planes
- Políticas
- Cuentas de servicio
- Suscripciones
La seguridad implementada para el uso de las APIs es OAuth 2.0. Esto quiere decir que previo al uso de las APIs, es necesario obtener un token de acceso a través de Oracle Identity Cloud Service. Una vez que el usuario es autenticado y autorizado, se utiliza el token para invocar cualquiera de las APIs.
La documentación completa de la funcionalidad de las APIs, su alcance y ejemplos de uso se encuentra en la siguiente liga:
Developer Cloud Service
Para este proyecto inclumos el uso de Developer Cloud Service como un entorno en el que vamos a ejecutar la automatización del despliegue de las APIs generadas. Developer Cloud Service es la plataforma de desarrollo de Oracle en la nube (PaaS). Cuenta con capacidades para desarrollo, colaboración, construcción y despliegue de aplicaciones en Oracle Cloud.
La documentación completa de Oracle Developer Cloud Service la pueden encontrar aquí:
Proceso de Automatización
Los pasos que seguimos para la automatización del despliegue en Oracle Developer Cloud Service fueron los que se detallan a continuación.
Descriptor
Lo primero que utilizamos es un descriptor de las APIs. Este básicamente es un archivo de tipo JSON que nos indica información importante de las APIs que queremos promover de una instancia a otra.
Básicamente, la información que debe incluir el descriptor es la siguiente:
- Nombre de la API
- Endpoint del servicio del backend
A continuación, se muestra un ejemplo simple del descriptor:
{
"apis": [
{
"name": "Orders API",
"targetURL": "https://oracleintegrationcloudinstance/ic/ws/integration/v1/flows/soap/"
},
{
"name": "Customers API",
"targetURL": "https://oracleintegrationcloudinstance/ic/ws/integration/v1/flows/soap/"
}
]
}
Dentro del arreglo de APIs, vamos a colocar todas las APIs que necesitamos mover de una instancia (fuente) a otra (destino).
Una vez creado el descriptor, se debe subir al repositorio de Git para conectar el job que realizará el despliegue automático. Así, cada vez que se decida mover APIs de una instancia a otra, se deberá modificar el descriptor y hacer commit de los cambios al repositorio.
Es hora de crear el job.
Parámetrización del job
Para hacer dinámico el job que automatiza el despliegue, es necesario colocar algunos parámetros que podamos cambiar a la hora de ejecutarlo. De esta forma, si las instancias cambian, la ejecución del job será dinámica y se adaptará a nuestras necesidades. Los parámetros que colocamos son los siguientes:
- Descriptor: nombre del archivo descriptor que se subirá al repositorio. El contenido deberá tener la información de las APIs que se necesitan mover de un ambiente a otro.
- GetTokenURL. URL de la API que utilizaremos para obtener el token de acceso. Normalmente esta es la URL de Oracle Identity Cloud Service.
- ClientCredsSource. Client ID y client secret de la aplicación origen que utilizaremos para consumir las APIs.
- ClientCredsTarget. Client ID y client secret de la aplicación destino que utilizaremos para consumir las APIs.
- UsernameSource. Usuario para obtener el token de acceso en la instancia origen.
- PasswordSource. Password para obtener el token de acceso en la instancia origen.
- ScopeSource. Scope para obtener el token de acceso en la instancia origen.
- URLEnvSource. URL de la API de la instancia origen de Oracle API Platform.
- UsernameTarget. Usuario para obtener el token de acceso en la instancia destino.
- PasswordTarget. Password para obtener el token de acceso en la instancia destino.
- ScopeTarget. Scope para obtener el token de acceso en la instancia destino.
- URLEnvTarget. URL de la API de la instancia destinode Oracle API Platform.
- GatewayID. Identificador del Gateway donde vamos a desplegar las APIs.
Los parámetros anteriores nos ayudan a ejecutar el job con valores dinámicos. Así, si la instancia fuente o destino cambia, lo único que es necesario es cambiar los valores de esos parámetros.
Scripting
La estrategia para realizar la automatización fue ejecutar un bash script. La mayoría de las APIs de Oracle están ejemplificadas con el uso de cURL. Por esta razón decidimos escribir un bash script y ahí encapsular las llamadas a las APIs con el uso de cURL.
Sin embargo, es posible codificar la automatización en cualquier otro lenguaje. Aquí lo importante es que sepamos cómo consumir REST APIs con ese lenguaje. Incluso es posible crear un plugin de Maven o Gradle para este propósito.
Validaciones
Antes de ejecutar la automatización, debemos hacer algunas validaciones. En mi caso las validaciones que hice al contenido del descriptor fueron las siguientes:
- El archivo JSON tiene una estructura válida y cumple con la definición de la estructura del descriptor.
- El archivo incluye la información de al menos una API a desplegar.
Procedimiento de despliegue
Los pasos para realizar el despliegue, después de librar todas las validaciones del archivo, son los siguientes:
- Obtener un token de acceso del ambiente origen: POST /oauth2/v1/token
- Obtener las APIs del ambiente origen: GET /apiplatform/management/v1/apis
- Validar que todas las APIs del descriptor, se encuentran desplegadas y activas en el ambiente origen. Esto es necesario, pues del ambiente origen se va a tomar toda la definición de cada API. Si no están desplegadas o activas, no podemos tomar la definición de ese ambiente: GET /apiplatform/management/v1/apis/{id}/deployments
- Obtener un token de acceso del ambiente destino: POST /oauth2/v1/token
- Obtener las APIs del ambiente destino: GET /apiplatform/management/v1/apis
- Si la API origen existe en el destino: actualizar la definición con el detalle del origen y con el endpoint del descriptor (targetURL): PUT /apiplatform/management/v1/apis/{id}
- Si la API origen no existe en el destino: crear la API en el ambiente destino con el detalle del origen y con el endpoint del descriptor (targetURL): POST /apiplatform/management/v1/apis
- Desplegar la API en el ambiente destino: POST /apiplatform/management/v1/apis/{id}/deployments
Posibles errores
En caso de que exista un error en alguno de los pasos anteriores, el proceso se detiene y se reporta la causa del error. Algunas causas de error pueden ser las siguientes:
- Información de credenciales incorrecta: usuarios, passwords, client credentials
- Las APIs listadas en el descriptor no se encuentran desplegadas y/o activas en el entorno origen
- Hay alguna dependencia en el entorno origen que no está configurada en el entorno destino. Por ejemplo los service account.
Conclusiones
Crear un mecanismo de automatización de despliegue de las APIs desplegadas en Oracle API Platform Cloud Service es una buena idea, pues a menudo se pueden presentar escenarios donde es necesario mover los artefactos de una instancia a otra. Esto puede suceder por distintas razones: se actualizan los servicios de nube, en un escenario de DRP, en caso de tener distintas instancias para distintos ambientes (Dev, Staging, Prod).
La reacción oportuna a alguno de estos escenarios, se verá beneficiada por la automatizacion y evitará el esfuerzo de crear nuevamente cada uno de los artefactos (APIs, Gateways, Planes, entre otros).
El uso de Developer Cloud Service es una buena alternativa para concentrar estas estrategias, pues es una plataforma que podemos utilizar de manera transparente para integrar con distintas nubes de Oracle, ya sea a través del uso de las APIs o a través de la propia CLI de Oracle. Aquí mismo podemos documentar y dar seguimiento al proceso y tareas de automatización. Personalmente he utilizado esta nube para automatización de despliegues de:
- Microservicios (Helidon, Quarkus) hacia Oracle Kubernetes Cluster.
- Oracle SOA Suite (Service Bus y SOA Composites) hacia entornos OnPremise y Cloud.
- APIs en Oracle API Platform Cloud Service
- Integraciones en Oracle Integration Cloud Service
- Funciones en Oracle Functions (FaaS)
