Google API Gateway

Propósito y Alcance

Este proyecto proporciona una plantilla para configurar y desplegar una API utilizando Google Cloud API Gateway. El propósito es servir como una base para exponer servicios (como Google Cloud Functions o otros backends HTTP) de manera segura y gestionada.

La configuración de la API Gateway se define mediante un archivo OpenAPI 2.0 (Swagger), permitiendo especificar paths, métodos, backends y esquemas de seguridad.

Alcance:

Definición de una API Gateway.
Integración con un backend (ej. Google Cloud Function).
Configuración de mecanismos de autenticación: API Key, Google ID Token (OAuth2), Azure AD ID Token (OAuth2).
Despliegue automatizado a través de un pipeline de Jenkins.
Configuración por entorno (dev, intg, prod).

Arquitectura

El proyecto implementa una capa de API Gateway sobre Google Cloud Platform. La arquitectura general consiste en:

Google API Gateway: Actúa como el punto de entrada para las solicitudes de los clientes. Gestiona la autenticación, el enrutamiento y otras políticas de API.
Backend Service: El servicio real que procesa la lógica de negocio. Típicamente, este sería una Google Cloud Function, Cloud Run, o cualquier otro servicio HTTP accesible. La plantilla está configurada para apuntar a una URL de backend (ej. <CLOUDFUNCTION-URL>).
OpenAPI Definition (openapi.yaml.erb): Un archivo de plantilla ERB (Embedded Ruby) que genera la especificación OpenAPI 2.0 para la API Gateway. Este archivo define los endpoints, métodos, parámetros de solicitud/respuesta y la configuración de seguridad.
Archivos de Configuración de Entorno (deploy/env/*.yaml): Archivos YAML que contienen variables específicas para cada entorno (desarrollo, integración, producción), como IDs de proyecto, cuentas de servicio y audiencias para tokens.
Pipeline CI/CD (Jenkins): Utiliza el Jenkinsfile para automatizar el proceso de despliegue de la API Gateway en los diferentes entornos.

No se proporciona un diagrama visual, pero la interacción es: Cliente -> Google API Gateway -> Backend Service (ej. Cloud Function)

Tecnologías y Dependencias

Google Cloud API Gateway: Servicio gestionado para crear, asegurar y monitorizar APIs.
Google Cloud Functions (o similar): Backend para las APIs (implícito, no incluido en este template, pero es el objetivo).
OpenAPI Specification (Swagger) 2.0: Formato estándar para describir APIs REST.
YAML: Utilizado para los archivos de configuración de entorno y la especificación OpenAPI.
ERB (Embedded Ruby): Utilizado para la plantilla openapi.yaml.erb, permitiendo la inyección de variables de entorno.
Jenkins: Para la automatización del despliegue (CI/CD) a través del Jenkinsfile.
Git / GitLab: Para el control de versiones y repositorio del proyecto.
- Repositorio: https://gitlab.com/latamairlines/tech/enterprise-architecture/arquitectura-central/tmpl_arq/corporate-architecture/templates/google-api-gateway.git

Configuración Local

Prerrequisitos

Git: Para clonar el repositorio.
gcloud CLI (SDK de Google Cloud): Opcional, pero útil para interactuar con GCP y probar configuraciones.
Ruby: Necesario si se desea procesar localmente el archivo openapi.yaml.erb. Sin embargo, el procesamiento usualmente ocurre en el pipeline de CI/CD.
Acceso al repositorio de GitLab.

Pasos de Configuración y Entendimiento

Clonar el repositorio: Sigue los siguientes pasos

Revisar la Definición de la API (deploy/gateway/openapi.yaml.erb): Este archivo es la plantilla principal para la configuración de la API Gateway. Contiene placeholders que serán reemplazados durante el despliegue.

swagger: "2.0"
info:
  title: ${{ NAME }} # Será reemplazado por el nombre de la API
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
# ... (resto del archivo) ...
paths:
  /path-name:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: <CLOUDFUNCTION-URL> # Placeholder para la URL del backend
      # ... (respuestas y seguridad) ...
securityDefinitions:
  api_key:
    type: "apiKey"
    name: "<% apikey_name %>" # Placeholder para el nombre del query param de la API key
    in: "query"
  google_id_token:
    # ... (configuración para Google OAuth2)
    x-google-audiences: "<%= gsuite_client_id %>" # Placeholder
  azure_id_token:
    # ... (configuración para Azure AD OAuth2)
    x-google-audiences: "<% audiences %>" # Placeholder

Revisar Archivos de Configuración de Entorno (deploy/env/): Estos archivos (dev.yaml, intg.yaml, prod.yaml) definen las variables que se usarán para reemplazar los placeholders en openapi.yaml.erb para cada entorno. Ejemplo de deploy/env/dev.yaml:
```
service_account: <service-account-name>
project_id: <project-id>
environment: "dev"
location: "us-east1"
audiences: <audences> # Usado por azure_id_token
gsuite_client_id: <gsuite_client_id> # Usado por google_id_token
```
Nota: Los valores <placeholder> deben ser reemplazados con valores reales para cada entorno. Estos usualmente se gestionan como secretos en el sistema CI/CD.
"Ejecución Local": Una API Gateway es un servicio en la nube y no se "ejecuta" localmente como una aplicación tradicional. La configuración local se centra en preparar los archivos de definición. Para probar, se debe desplegar la configuración en un entorno de GCP.

Despliegue

El despliegue de la API Gateway está automatizado mediante Jenkins.

Pipeline de Jenkins: El archivo Jenkinsfile en la raíz del proyecto define el pipeline a utilizar:
```
pipelineLatam('gcloud-api-gateway-deploy')
```
Este pipeline se encarga de:
- Tomar la plantilla openapi.yaml.erb.
- Procesar la plantilla ERB, inyectando las variables correspondientes del archivo de entorno (dev.yaml, intg.yaml, o prod.yaml) según el entorno de despliegue.
- Desplegar la configuración resultante de OpenAPI a Google Cloud API Gateway en el proyecto y región especificados.

Configuración de Entornos (deploy/env/*.yaml): Antes de desplegar a un nuevo entorno o realizar cambios, asegúrate de que el archivo YAML correspondiente (dev.yaml, intg.yaml, prod.yaml) esté correctamente configurado con los siguientes parámetros:

Parámetro	Descripción	Ejemplo (Placeholder)
`service_account`	La cuenta de servicio de GCP que utilizará la API Gateway.	`<service-account-name>`
`project_id`	El ID del proyecto de Google Cloud donde se desplegará la API Gateway.	`<project-id>`
`environment`	Identificador del entorno (ej. "dev", "intg", "prod").	`"dev"`
`location`	La región de GCP donde se desplegará la API Gateway (ej. "us-east1").	`"us-east1"`
`audiences`	Audiencias para la validación de tokens de Azure AD (usado en `azure_id_token`).	`<audiences>`
`gsuite_client_id`	Client ID de GSuite para la validación de tokens de Google (usado en `google_id_token`).	`<gsuite_client_id>`

Importante: Los valores sensibles o específicos del entorno deben ser gestionados a través de mecanismos seguros (ej. variables de entorno o secretos en Jenkins), no commiteados directamente en los archivos deploy/env/*.yaml si son críticos.

Endpoints de la API

La plantilla openapi.yaml.erb define los siguientes endpoints de ejemplo. Estos pueden ser modificados o extendidos según las necesidades del proyecto.

Método	Path	Resumen	Operación ID	Backend (Ejemplo)	Seguridad Aplicada
`GET`	`/path-name`	Greet a user	`hello`	`<CLOUDFUNCTION-URL>`	`api_key`, `google_id_token`, `azure_id_token`

Detalles del Backend:

x-google-backend:
- address: <CLOUDFUNCTION-URL> - Este placeholder debe ser reemplazado por la URL real del servicio backend (ej., la URL de trigger de una Google Cloud Function).

Respuestas Definidas (Ejemplo para GET /path-name):

200 OK: Respuesta exitosa.
- Schema: type: string
401 Unauthorized: Error de autenticación.
403 Forbidden: Error de autorización.
404 Not Found: Recurso no encontrado.

Componentes Específicos

1. Google API Gateway

Definición Principal: El archivo deploy/gateway/openapi.yaml.erb es el corazón de la configuración. Define todos los aspectos de la API.
Procesamiento de Plantilla: Usa ERB para permitir que los valores específicos del entorno (de deploy/env/*.yaml) se inserten en la especificación OpenAPI final durante el despliegue.
- ${{ NAME }}: Nombre de la API.
- <CLOUDFUNCTION-URL>: URL del servicio backend.
- <% apikey_name %>: Nombre del parámetro de query para la API Key.
- <%= gsuite_client_id %>: Audiencia para google_id_token.
- <% audiences %>: Audiencia para azure_id_token.

Esquemas de Seguridad: Configurados en la sección securityDefinitions de openapi.yaml.erb:

API Key (api_key):

securityDefinitions:
  api_key:
    type: "apiKey"
    name: "<% apikey_name %>" # ej. "key"
    in: "query"

Google ID Token (google_id_token): Autenticación OAuth2 usando tokens ID emitidos por Google.

securityDefinitions:
  google_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
    x-google-audiences: "<%= gsuite_client_id %>"
    x-google-jwt-locations:
      - header: "Authorization"
        value_prefix: "Bearer "

Azure AD ID Token (azure_id_token): Autenticación OAuth2 usando tokens ID emitidos por Azure Active Directory.

securityDefinitions:
  azure_id_token:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    x-google-issuer: "https://login.microsoftonline.com/99d911b9-6dc3-401c-9398-08fc6b377b74/v2.0" # Ejemplo de Tenant ID, ajustar según sea necesario
    x-google-jwks_uri: "https://login.microsoftonline.com/99d911b9-6dc3-401c-9398-08fc6b377b74/discovery/v2.0/keys" # Ejemplo de Tenant ID, ajustar
    x-google-audiences: "<% audiences %>"
    x-google-jwt-locations:
      - header: "Authorization"
        value_prefix: "Bearer "

2. Backend Service (Ej. Google Cloud Function)

Este template no incluye la implementación del servicio backend en sí mismo.
La API Gateway se configura para enrutar las solicitudes a una URL de backend especificada en openapi.yaml.erb bajo x-google-backend: address: <CLOUDFUNCTION-URL>.
Este backend debe ser un servicio HTTP/S accesible por la API Gateway.

Pruebas

Pruebas Unitarias/Integración Automatizadas: No se incluyen scripts de prueba automatizados específicos para la API Gateway dentro de este repositorio de plantilla. Las pruebas del backend (ej. Cloud Function) deben realizarse en su propio ciclo de desarrollo.
Pruebas de API Post-Despliegue: Una vez que la API Gateway está desplegada en un entorno de GCP, se pueden realizar pruebas utilizando herramientas estándar de cliente HTTP como:
- cURL
- Postman
- Cualquier otro cliente de API REST.
Pasos Generales para Probar:
1. Obtener la URL de la API Gateway desplegada.
2. Construir la solicitud según la definición de OpenAPI (método, path, headers, body).
3. Si la seguridad está habilitada para el endpoint:
  - Para api_key: Incluir la clave como un parámetro de query (ej. ?key=YOUR_API_KEY).
  - Para google_id_token o azure_id_token: Obtener un token válido e incluirlo en el header Authorization (ej. Authorization: Bearer YOUR_ID_TOKEN).
4. Enviar la solicitud y verificar la respuesta (código de estado, cuerpo, headers).

Consideraciones de Seguridad

Gestión de Credenciales:
- Las variables sensibles como service_account details, project_id, audiences, gsuite_client_id, y el valor de la API Key deben gestionarse de forma segura. Evita commitear valores reales directamente en los archivos deploy/env/*.yaml si son sensibles. Utiliza secretos de CI/CD (ej. Jenkins credentials, GCP Secret Manager) para inyectarlos durante el despliegue.
- La URL del repositorio en .git/config contiene un token de acceso (glpat-...). Asegúrate de que este token tenga los permisos mínimos necesarios y sea rotado si es necesario. Para la documentación pública, es mejor usar la URL HTTPS sin credenciales embebidas.
API Keys: Considera las políticas de restricción de API Keys en GCP para limitar su uso a IPs específicas, APIs o servicios.
OAuth2 Tokens (Google/Azure):
- Asegura que las audiences y issuer estén correctamente configurados para validar los tokens adecuadamente.
- Utiliza HTTPS para todas las comunicaciones.
Permisos de la Cuenta de Servicio: La cuenta de servicio (service_account) asociada con la API Gateway y/o el backend debe tener los permisos mínimos necesarios (Principio de Menor Privilegio).
Validación de Entradas: Aunque la API Gateway puede realizar algunas validaciones básicas basadas en OpenAPI, el backend service también debe implementar una validación robusta de todas las entradas.

Propósito y Alcance​

Arquitectura​

Tecnologías y Dependencias​

Configuración Local​

Prerrequisitos​

Pasos de Configuración y Entendimiento​

Despliegue​

Endpoints de la API​

Componentes Específicos​

1. Google API Gateway​

2. Backend Service (Ej. Google Cloud Function)​

Pruebas​

Consideraciones de Seguridad​