gateway-controller

Gateway-Controller

The Gateway-Controller is the xDS control plane that manages API configurations and dynamically configures the Router (Envoy Proxy).

Features

REST API: Submit, update, delete, and query API configurations via HTTP
Validation: Comprehensive validation with field-level error messages
Persistence: Embedded SQLite database for configuration storage
In-Memory Cache: Fast access with thread-safe operations
xDS Server: gRPC server implementing xDS State-of-the-World protocol to serve Envoy
Zero-Downtime Updates: Configuration changes applied without dropping connections (restarts)

Architecture

REST API (Port 9090)
      ↓
  Validation
      ↓
Persistence (SQLite) + In-Memory Cache
      ↓
  xDS Translator
      ↓
xDS gRPC Server (Port 18000)
      ↓
  Router (Envoy)

Building

Prerequisites

Go 1.25.1+
Make

Build from Source

# Generate API code from OpenAPI spec
make generate

# Build binary
make build

# Run tests
make test

# Build Docker image
make docker

Running

Local Development

# Run with default settings
make run

# Or run the binary directly
./bin/controller

Docker

docker run -p 9090:9090 -p 18000:18000 \
  -v $(pwd)/data:/data \
  wso2/gateway-controller:latest

Configuration

The Gateway-Controller supports configuration via:

Configuration file (YAML)
Environment variables (prefix: APIP_GW_)
Command-line flags

Priority: Environment variables > Config file > Defaults

Configuration File

Create a config.yaml file (default location: /etc/gateway-controller/config.yaml):

# Server configuration
server:
  api_port: 9090          # REST API port
  xds_port: 18000         # xDS gRPC server port
  shutdown_timeout: 15s   # Graceful shutdown timeout

# Storage configuration
storage:
  type: sqlite            # "sqlite", "postgres", or "memory"
  sqlite:
    path: ./data/gateway.db  # SQLite database file path
  postgres:               # Used when type=postgres
    host: localhost
    port: 5432
    database: gateway
    user: gateway
    password: ""
    sslmode: require      # disable, require, verify-ca, verify-full
    connect_timeout: 5s
    max_open_conns: 25
    max_idle_conns: 5
    conn_max_lifetime: 30m
    conn_max_idle_time: 5m
    application_name: gateway-controller

# Router (Envoy) configuration
router:
  access_logs:
    enabled: true         # Enable/disable access logs
    format: json          # "json" or "text"
  listener_port: 8080     # Envoy proxy port

# Logging configuration
logging:
  level: info             # "debug", "info", "warn", "error"
  format: json            # "json" or "text"

Command-Line Flags

# Specify custom config file location
./bin/controller --config /path/to/config.yaml

Environment Variables

Override any configuration value using the APIP_GW_ prefix:

# Override server API port
export APIP_GW_GATEWAY__CONTROLLER_SERVER_API__PORT=9091

# Set storage type to memory
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_TYPE=memory

# Override SQLite database path
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_SQLITE_PATH=/custom/path/gateway.db

# Configure PostgreSQL storage
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_TYPE=postgres
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_POSTGRES_HOST=postgres.example.internal
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_POSTGRES_PORT=5432
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_POSTGRES_DATABASE=gateway
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_POSTGRES_USER=gateway
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_POSTGRES_PASSWORD=secret
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_POSTGRES_SSLMODE=require
export APIP_GW_GATEWAY__CONTROLLER_STORAGE_POSTGRES_MAX__OPEN__CONNS=25

# Disable access logs
export APIP_GW_GATEWAY__CONTROLLER_ROUTER_ACCESS__LOGS_ENABLED=false

# Set debug logging
export APIP_GW_GATEWAY__CONTROLLER_LOGGING_LEVEL=debug

./bin/controller

Environment variable naming: APIP_GW_<SECTION>_<KEY> (uppercase, underscore-separated, double underscores preserve literal underscores in field names)

Configuration Modes

Persistent Mode with SQLite (Default)

Use SQLite database for persistence across restarts:

storage:
  type: sqlite
  sqlite:
    path: ./data/gateway.db

Persistent Mode with PostgreSQL

Use an external PostgreSQL server for persistence:

storage:
  type: postgres
  postgres:
    host: postgres.example.internal
    port: 5432
    database: gateway
    user: gateway
    password: ${DB_PASSWORD}
    sslmode: require
    connect_timeout: 5s
    max_open_conns: 25
    max_idle_conns: 5
    conn_max_lifetime: 30m
    conn_max_idle_time: 5m
    application_name: gateway-controller

Memory-Only Mode

No persistent storage (useful for testing):

storage:
  type: memory

Access Logs

JSON Format (Default)

Structured logs for aggregation:

router:
  access_logs:
    enabled: true
    format: json

Example output:

{"start_time":"2025-10-12T15:45:00Z","method":"GET","path":"/weather/US/Seattle","response_code":200,"duration":125}

Text Format

Human-readable format:

router:
  access_logs:
    enabled: true
    format: text

Example output:

[2025-10-12T15:45:00Z] "GET /weather/US/Seattle HTTP/1.1" 200 - 512 1024 125 "10.0.0.1" "curl/7.68.0"

Disable Access Logs

For performance or privacy:

router:
  access_logs:
    enabled: false

Example Configurations

See config/ directory for examples:

config.yaml - Default production configuration
config-memory-only.yaml - Testing/development configuration

API Reference

The Gateway-Controller exposes a REST API for managing API configurations.

Base URL

http://localhost:9090

Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2025-10-12T15:45:00Z"
}

Create API Configuration

POST /apis
Content-Type: application/yaml

version: api-platform.wso2.com/v1
kind: RestApi
data:
  name: Weather API
  version: v1.0
  context: /weather
  upstream:
    - url: http://api.weather.com/api/v2
  operations:
    - method: GET
      path: /{country}/{city}

Response:

{
  "status": "success",
  "message": "API configuration created successfully",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2025-10-12T15:45:00Z"
}

List All APIs

GET /apis

Get API by Name and Version

GET /apis/{name}/{version}

Example:

GET /apis/Weather%20API/v1.0

Update API

PUT /apis/{name}/{version}
Content-Type: application/yaml

<updated configuration>

Example:

PUT /apis/Weather%20API/v1.0
Content-Type: application/yaml

version: api-platform.wso2.com/v1
kind: RestApi
data:
  name: Weather API
  version: v1.0
  context: /weather
  upstream:
    - url: http://api.weather.com/api/v3
  operations:
    - method: GET
      path: /{country}/{city}

Delete API

DELETE /apis/{name}/{version}

Example:

DELETE /apis/Weather%20API/v1.0

Data Storage

The Gateway-Controller uses SQLite (embedded relational database) for persistent storage of API configurations.

Database Schema

The SQLite database contains the following table:

deployments - Stores API configurations with full lifecycle metadata

Table Structure

Column	Type	Description
`id`	TEXT (PRIMARY KEY)	Unique UUID identifier
`name`	TEXT	API name (indexed for fast lookups)
`version`	TEXT	API version (indexed for fast lookups)
`context`	TEXT	Base path (e.g., "/weather")
`kind`	TEXT	API type ("RestApi", "graphql", etc.)
`configuration`	TEXT	Full JSON-serialized API configuration
`status`	TEXT	Deployment status ("pending", "deployed", "failed")
`created_at`	TIMESTAMP	Record creation timestamp
`updated_at`	TIMESTAMP	Last modification timestamp
`deployed_at`	TIMESTAMP	Timestamp of successful deployment (NULL if never deployed)
`deployed_version`	INTEGER	xDS snapshot version number

Unique Constraint: (name, version) - prevents duplicate API versions

Database Configuration

SQLite is configured with the following settings for optimal performance:

Journal Mode: WAL (Write-Ahead Logging) - enables concurrent reads during writes
Busy Timeout: 5000ms - retries locked database for 5 seconds before failing
Synchronous: NORMAL - balanced durability (faster than FULL, safer than OFF)
Cache Size: 2000 pages (~2MB in-memory cache)
Foreign Keys: ON - enables referential integrity

Database Files

When using SQLite storage, the following files are created in the data directory:

./data/gateway.db - Main database file
./data/gateway.db-wal - Write-Ahead Log (transactions)
./data/gateway.db-shm - Shared memory for WAL

Inspecting the Database

You can inspect the SQLite database using the sqlite3 command-line tool:

# Connect to the database
sqlite3 ./data/gateway.db

# List all API configurations
SELECT name, version, status FROM deployments;

# View specific API configuration (pretty-print JSON)
SELECT json(configuration) FROM deployments WHERE name = 'Weather API';

# Count configurations by status
SELECT status, COUNT(*) FROM deployments GROUP BY status;

# Check database size and schema
.dbinfo
.schema deployments

# Exit
.quit

Database Backup

To backup the SQLite database:

# 1. Checkpoint WAL to main database file
sqlite3 ./data/gateway.db "PRAGMA wal_checkpoint(TRUNCATE);"

# 2. Copy database file
cp ./data/gateway.db ./backups/gateway-$(date +%Y%m%d-%H%M%S).db

# 3. Verify backup integrity
sqlite3 ./backups/gateway-*.db "PRAGMA integrity_check;"

Troubleshooting

Database is Locked Error

If you encounter "database is locked" errors:

Check for active connections:
```
lsof ./data/gateway.db
```
Ensure only one gateway-controller instance is running: SQLite with a single writer connection is designed for single-instance deployments.
Restart the gateway-controller: The controller will fail-fast on startup if the database is locked, with a clear error message.

Force unlock (DANGER: only if no processes are running):

rm ./data/gateway.db-wal ./data/gateway.db-shm
sqlite3 ./data/gateway.db "PRAGMA integrity_check;"

Empty Database on Startup

The gateway-controller automatically creates the database schema if it doesn't exist. If you see "schema initialization" in the logs, this is normal behavior on first startup.

Performance Issues

SQLite is optimized for up to 100+ API configurations. If you experience performance issues with larger datasets, consider:

Check index usage:

sqlite3 ./data/gateway.db
EXPLAIN QUERY PLAN SELECT * FROM deployments WHERE name = 'MyAPI' AND version = 'v1';

Verify WAL mode is enabled:

sqlite3 ./data/gateway.db "PRAGMA journal_mode;"
# Should return: wal

For very large deployments (1000+ configurations), consider migrating to PostgreSQL (future support planned)

xDS Protocol

The Gateway-Controller implements Envoy's State-of-the-World (SotW) xDS protocol:

Router connects to Gateway-Controller on port 18000
Gateway-Controller generates complete xDS snapshot from in-memory configurations
On configuration change, new snapshot is created and pushed to Router
Router applies configuration gracefully (in-flight requests complete)

Development

Project Structure

gateway-controller/
├── cmd/
│   └── controller/
│       └── main.go           # Entry point
├── pkg/
│   ├── api/
│   │   ├── generated/        # Generated from OpenAPI spec
│   │   ├── handlers/         # REST API handlers
│   │   └── middleware/       # Logging, error handling
│   ├── config/
│   │   ├── config.go         # Configuration loader (Koanf)
│   │   ├── parser.go         # YAML/JSON parsing
│   │   └── validator.go      # Configuration validation
│   ├── models/
│   │   └── stored_config.go     # Data structures
│   ├── storage/
│   │   ├── interface.go      # Storage abstraction
│   │   ├── memory.go         # In-memory cache
│   │   └── sqlite.go         # SQLite implementation
│   ├── xds/
│   │   ├── server.go         # xDS gRPC server
│   │   ├── snapshot.go       # Snapshot manager
│   │   └── translator.go     # Config → Envoy translation
│   └── logger/
│       └── logger.go         # Zap logger setup
├── api/
│   └── openapi.yaml          # OpenAPI 3.0 specification
├── config/
│   ├── config.yaml           # Default configuration
│   └── config-memory-only.yaml  # Memory-only example
├── oapi-codegen.yaml         # Code generation config
├── Dockerfile
└── Makefile

Code Generation

The REST API is generated from the OpenAPI specification using oapi-codegen:

make generate

This creates pkg/api/generated/generated.go with:

ServerInterface - Handler interface
Request/response types
Route registration

Logging

The Gateway-Controller uses structured logging (Zap) with configurable levels.

Debug Mode

# Using environment variable
APIP_GW_GATEWAY__CONTROLLER_LOGGING_LEVEL=debug ./bin/controller

# Or using config file
export APIP_GW_GATEWAY__CONTROLLER_LOGGING_LEVEL=debug
./bin/controller

Debug logs include:

Complete API configuration payloads
xDS snapshot details
Configuration diffs for updates

Performance

Configuration validation: < 1 second
xDS update push: < 5 seconds
Supports 100+ API configurations
Thread-safe concurrent operations

Name		Name	Last commit message	Last commit date
parent directory ..
api		api
certificates		certificates
cmd/controller		cmd/controller
data		data
default-llm-provider-templates		default-llm-provider-templates
default-policies		default-policies
listener-certs		listener-certs
lua		lua
pkg		pkg
resources		resources
tests/integration		tests/integration
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
authentication.md		authentication.md
go.mod		go.mod
go.sum		go.sum
oapi-codegen-admin.yaml		oapi-codegen-admin.yaml
oapi-codegen.yaml		oapi-codegen.yaml

FilesExpand file tree

gateway-controller

Directory actions

More options

Directory actions

More options

Latest commit

History

gateway-controller

Folders and files

parent directory

README.md

Gateway-Controller

Features

Architecture

Building

Prerequisites

Build from Source

Running

Local Development

Docker

Configuration

Configuration File

Command-Line Flags

Environment Variables

Configuration Modes

Persistent Mode with SQLite (Default)

Persistent Mode with PostgreSQL

Memory-Only Mode

Access Logs

JSON Format (Default)

Text Format

Disable Access Logs

Example Configurations

API Reference

Base URL

Endpoints

Health Check

Create API Configuration

List All APIs

Get API by Name and Version

Update API

Delete API

Data Storage

Database Schema

Table Structure

Database Configuration

Database Files

Inspecting the Database

Database Backup

Troubleshooting

Database is Locked Error

Empty Database on Startup

Performance Issues

xDS Protocol

Development

Project Structure

Code Generation

Logging

Debug Mode

Performance