Kong API Gateway

Kong serves as the central API gateway for all iHospita services, providing rate limiting, authentication validation, load balancing, and request routing.

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         KONG API GATEWAY                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                       │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                      KONG GATEWAY                            │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │    │
│  │  │   Plugins   │  │   Routes    │  │   Services  │         │    │
│  │  └─────────────┘  └─────────────┘  └─────────────┘         │    │
│  │                                                               │    │
│  │  Port 8000: Proxy (HTTP)                                     │    │
│  │  Port 8443: Proxy (HTTPS)                                    │    │
│  │  Port 8001: Admin API                                        │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                              │                                        │
│                              ▼                                        │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │                    KONG DATABASE                             │    │
│  │                   (PostgreSQL)                               │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                       │
└─────────────────────────────────────────────────────────────────────┘

---

Docker Compose Configuration

# docker-compose.kong.yml
version: '3.8'

services:
  kong-database:
    image: postgres:15-alpine
    container_name: ihospita-kong-db
    environment:
      POSTGRES_USER: kong
      POSTGRES_PASSWORD: ${KONG_DB_PASSWORD}
      POSTGRES_DB: kong
    volumes:
      - kong_data:/var/lib/postgresql/data
    networks:
      - ihospita-network
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kong"]
      interval: 10s
      timeout: 5s
      retries: 5

  kong-migrations:
    image: kong:3.5
    command: kong migrations bootstrap
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: ${KONG_DB_PASSWORD}
    depends_on:
      kong-database:
        condition: service_healthy
    networks:
      - ihospita-network

  kong:
    image: kong:3.5
    container_name: ihospita-kong
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: ${KONG_DB_PASSWORD}
      KONG_PROXY_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_LISTEN: 0.0.0.0:8001
      KONG_PROXY_LISTEN: 0.0.0.0:8000, 0.0.0.0:8443 ssl
      KONG_PLUGINS: bundled,prometheus
    ports:
      - "8000:8000"   # Proxy HTTP
      - "8443:8443"   # Proxy HTTPS
      - "8001:8001"   # Admin API
    networks:
      - ihospita-network
    healthcheck:
      test: ["CMD", "kong", "health"]
      interval: 10s

networks:
  ihospita-network:
    external: true

volumes:
  kong_data:

---

Service Routes

Declarative Configuration (kong.yml)

_format_version: "3.0"
_transform: true

services:
  # Keycloak Authentication Service
  - name: keycloak-service
    url: http://keycloak:8080
    routes:
      - name: keycloak-route
        paths:
          - /auth
        strip_path: false

  # HMS Service (Hospital Management)
  - name: hms-service
    url: http://hms-service:3000
    routes:
      - name: hms-route
        paths:
          - /api/hms
        strip_path: false
    plugins:
      - name: jwt
      - name: rate-limiting
        config:
          minute: 100
          hour: 1000
      - name: prometheus

  # CRM Service
  - name: crm-service
    url: http://crm-service:3001
    routes:
      - name: crm-route
        paths:
          - /api/crm
    plugins:
      - name: jwt
      - name: rate-limiting
        config:
          minute: 100
          hour: 1000

  # Payment Service
  - name: payment-service
    url: http://payment-service:3002
    routes:
      - name: payment-route
        paths:
          - /api/payment
    plugins:
      - name: jwt
      - name: rate-limiting
        config:
          minute: 50
          hour: 500

  # Queue Service
  - name: queue-service
    url: http://queue-service:3003
    routes:
      - name: queue-route
        paths:
          - /api/queue
    plugins:
      - name: jwt
      - name: rate-limiting
        config:
          minute: 200
          hour: 2000

  # Report Service
  - name: report-service
    url: http://report-service:3004
    routes:
      - name: report-route
        paths:
          - /api/report
    plugins:
      - name: jwt
      - name: rate-limiting
        config:
          minute: 30
          hour: 300

---

Plugin Configuration

Essential Plugins

Plugin	Purpose	Configuration
jwt	Validate Keycloak tokens	RS256 signature verification
rate-limiting	Prevent abuse	Per-minute/hour limits
cors	Cross-origin requests	Allow Portal/Console origins
prometheus	Metrics export	Expose /metrics endpoint
request-size-limiting	Limit payload	10MB default
correlation-id	Request tracing	UUID in X-Request-ID

CORS Configuration

plugins:
  - name: cors
    config:
      origins:
        - https://portal.ihospita.com
        - https://console.ihospita.com
      methods:
        - GET
        - POST
        - PUT
        - DELETE
        - OPTIONS
      headers:
        - Authorization
        - Content-Type
      credentials: true
      max_age: 3600

JWT Plugin

plugins:
  - name: jwt
    config:
      uri_param_names:
        - jwt
      header_names:
        - Authorization
      claims_to_verify:
        - exp
      key_claim_name: iss
      run_on_preflight: true

---

Rate Limits by Service

Service	Per Minute	Per Hour	Notes
HMS	100	1000	Standard operations
CRM	100	1000	Standard operations
Payment	50	500	Sensitive operations
Queue	200	2000	High frequency
Report	30	300	Resource intensive

---

Health Checks

upstreams:
  - name: hms-upstream
    targets:
      - target: hms-service-1:3000
        weight: 100
      - target: hms-service-2:3000
        weight: 100
    healthchecks:
      active:
        healthy:
          interval: 5
          successes: 2
        unhealthy:
          interval: 5
          http_failures: 3
          tcp_failures: 3
        type: http
        http_path: /health

---

Admin API Examples

List Services

curl http://localhost:8001/services

Create Route

curl -X POST http://localhost:8001/services/hms-service/routes \
  -d "name=hms-patients" \
  -d "paths[]=/api/hms/patients"

Enable Plugin

curl -X POST http://localhost:8001/services/hms-service/plugins \
  -d "name=rate-limiting" \
  -d "config.minute=100"

Check Health

curl http://localhost:8001/status

---

Monitoring

Kong exposes Prometheus metrics at /metrics:

# HELP kong_http_requests_total HTTP requests
# TYPE kong_http_requests_total counter
kong_http_requests_total{service="hms-service",route="hms-route",code="200"} 1234

# HELP kong_latency_ms Request latency
# TYPE kong_latency_ms histogram
kong_latency_ms_bucket{service="hms-service",le="100"} 500

---

Troubleshooting

Common Issues

Issue	Solution
502 Bad Gateway	Check upstream service health
429 Too Many Requests	Rate limit exceeded, wait or increase limit
401 Unauthorized	Invalid or expired JWT token
503 Service Unavailable	All upstream targets unhealthy

Debug Mode

# Enable debug logging
docker exec kong kong config -c /etc/kong/kong.conf

# View logs
docker logs -f ihospita-kong