api7-demo/web/docs/architecture.md

Architecture Overview

Infrastructure Architecture

Internet
   ↓
Load Balancer (External IP)
   ↓
Ingress Controller
   ↓
TLS Termination (Wildcard Certificate)
   ↓
┌─────────────────────────────────────────────────────┐
│         Gateway Ingress                             │
│  (*.domain.com / domain.com)                        │
└─────────────────────────────────────────────────────┘
   ↓
┌─────────────────────────────────────────────────────┐
│      Gateway Service (ClusterIP)                    │
│   gateway-service (Internal IP)                     │
│   Ports: 80 (→9080), 443 (→9443)                   │
└─────────────────────────────────────────────────────┘
   ↓
┌─────────────────────────────────────────────────────┐
│         Gateway Pods (Multiple Replicas)            │
│   - gateway-pod-1                                   │
│   - gateway-pod-2                                   │
│   - gateway-pod-3                                   │
└─────────────────────────────────────────────────────┘
   ↓
[Route Matching & Service Discovery]
   ↓
┌──────────────────┬──────────────────┐
│  Backend         │  Backend         │
│  Services        │  Services        │
│  (ClusterIP)     │  (ClusterIP)     │
└──────────────────┴──────────────────┘
   ↓
Application Pods

Component Details

1. External Access Layer

Load Balancer

• Provides external IP address
• Supports LoadBalancer service type
• Exposes Ingress Controller to the internet

Ingress Controller

• Handles HTTP/HTTPS traffic
• TLS termination point
• Routes to appropriate backend services

2. Control Plane

Deployment Method: Helm Chart Namespace: Dedicated namespace for gateway components

Components

Dashboard

• Function: Web UI for gateway management
• Service Type: ClusterIP
• Ports: Management ports (HTTP/HTTPS)
• Replicas: Configurable

Developer Portal

• Function: API documentation and developer access
• Service Type: ClusterIP
• Ports: Web service port
• Replicas: Configurable

Data Plane Manager

• Function: Data Plane management and configuration distribution
• Service Type: ClusterIP
• Ports: Management and proxy ports
• Replicas: Configurable

PostgreSQL Database

• Function: Configuration and metadata storage
• Service Type: ClusterIP
• Port: 5432/TCP
• Storage: Persistent volume with configurable size
• Deployment: StatefulSet for data persistence

Prometheus Server

• Function: Metrics collection and monitoring
• Service Type: ClusterIP
• Port: 9090/TCP
• Storage: Persistent volume for metrics retention

3. Gateway Data Plane

Deployment Method: Helm Chart High Availability: Multiple replicas for fault tolerance

Gateway Deployment

• Replicas: Configurable (recommended: 3+)
• Strategy: RollingUpdate for zero-downtime deployments
• Max Unavailable: 25% during updates

Gateway Groups:

• Logical grouping of gateway instances
• Environment-based separation (dev/staging/prod)
• Independent configuration per group

Gateway Service

• Type: ClusterIP for internal routing
• Ports:
  • HTTP: 80/TCP → 9080/TCP
  • HTTPS: 443/TCP → 9443/TCP

Gateway Configuration

Configuration Store:

• Connection: Secure connection to control plane
• TLS: Mutual authentication enabled
• Certificates: Managed via Kubernetes secrets

Configuration Volumes:

• Gateway configuration via ConfigMap
• TLS certificates for secure communication
• Service discovery configuration

4. Ingress Configuration

Gateway Ingress Resource

Hosts:
  - *.domain.com
  - domain.com

Backend:
  Service: gateway-service
  Port: 80

TLS:
  - hosts:
      - *.domain.com
      - domain.com
    secretName: wildcard-tls-secret

Access Points:

• External IP: Provided by Load Balancer
• Protocols: HTTP (80), HTTPS (443)
• Ingress Class: Configurable

5. Storage Architecture

Persistent Volumes:

Component	Recommended Size	Usage
PostgreSQL Database	10Gi+	Configuration and metadata storage
Prometheus Metrics	100Gi+	Time-series metrics retention
Configuration Store	8Gi per node	Distributed configuration (if using etcd)

Storage Classes:

• Distributed storage for database persistence
• Local or network storage for metrics
• High-performance storage for configuration

Network Flow

External Request Flow

1. Client Request → Domain URL (HTTP/HTTPS)
2. DNS Resolution → External Load Balancer IP
3. Ingress Controller → TLS termination with wildcard certificate
4. Ingress Routing → Gateway service endpoint
5. Gateway Service → Load balances across gateway pod replicas
6. Route Matching → Gateway evaluates routes based on host/path/priority
7. Service Discovery → Gateway fetches backend endpoints from Kubernetes
8. Backend Request → Proxies to backend service pods
9. Response → Returns through the chain to client

Control Plane Communication

1. Dashboard → Database (configuration storage)
2. Dashboard → Data Plane Manager (gateway group management)
3. Data Plane Manager → Configuration store (configuration distribution)
4. Gateway Pods → Control plane endpoint (fetch routes/services)
5. Prometheus → Gateway Pods (scrape metrics)

Security Architecture

TLS/SSL Configuration

External TLS (Ingress Layer):

• Certificate: Wildcard certificate (Let's Encrypt or commercial)
• Secret: Kubernetes TLS secret
• Domains: Wildcard and root domain support

Internal TLS (Control Plane):

• Dashboard: Secure HTTPS access
• Developer Portal: Encrypted portal access
• Data Plane Manager: Secure management interface

Gateway Communication TLS:

• Mutual TLS: Enabled for secure communication
• CA Certificate: Certificate authority validation
• Client Certificates: Individual component authentication

Service Accounts & RBAC

Gateway Service Account: Dedicated service account per namespace

Required Permissions:

• list/watch endpoints (for service discovery)
• Read access to services and pods
• Typically bound to appropriate ClusterRole

High Availability

Gateway Layer

• Multiple replicas for fault tolerance (3+ recommended)
• RollingUpdate strategy for zero-downtime deployments
• Load balancing across all healthy instances

Control Plane

• Database: StatefulSet with persistent storage
• Monitoring: Persistent metrics storage
• Management Components: Stateless, scalable replicas

Storage

• Database: Distributed or replicated storage
• Metrics: Persistent volume with retention policy
• Configuration: Highly available storage backend

Monitoring & Observability

Metrics Collection:

• Time-series metrics from all gateway pods
• Persistent storage for historical data
• Query interface for metrics analysis

Gateway Metrics:

• HTTP request rates and throughput
• Latency percentiles (p50, p95, p99)
• Error rates and status codes
• Active connections and concurrency
• Upstream service health status

Health Checks:

• Gateway readiness and liveness probes
• Service health endpoints
• Automated recovery mechanisms

Scalability Considerations

Horizontal Scaling:

• Gateway pods: Scale based on traffic patterns
• Backend services: Auto-scaling based on metrics
• Control plane: Scale management components as needed

Vertical Scaling:

• Database: Expand storage as data grows
• Metrics storage: Adjust retention and volume size
• Gateway resources: Tune CPU/memory for performance

Configuration Management

Gateway Configuration:

• Source: Dashboard UI or CLI tools
• Storage: Centralized database
• Distribution: Control plane to data plane synchronization
• Format: YAML configuration or Web-based management

Kubernetes Resources:

• Deployment: Helm charts for standardized installation
• Management: Kubernetes-native resource management
• Namespaces: Logical separation of environments

---

This architecture provides enterprise-grade API Gateway capabilities with high availability, scalability, and comprehensive monitoring.