Introduction to API Gateway and Kong Implementation at Haodf

1. Introduction to API Gateway

API Gateway (API‑Gateway) is the single entry point of the whole system, handling traffic uniformly. Its traditional functions include reverse proxy and load balancing, dynamic upstreams, SSL certificates, dynamic rate limiting, and active/passive health checks of upstream services.

Additional features: authentication, rate limiting, statistics, performance analysis, etc.

Two main types of gateways:

Access‑layer gateway: provides a unified traffic entry for diverse clients, performs routing, rate limiting, logging, caching, etc. Haodf uses Kong for this layer.

Application‑layer gateway: offers service registration, discovery, and circuit‑breaker functions. Haodf uses a sidecar (ZuulFilter) for this.

2. Haodf Gateway Development

Initially Haodf used Nginx as the access‑layer gateway; in early 2020 it was replaced by Kong.

2.1 Why we replaced Nginx with Kong

Key terms:

BFF (Backend For Frontend) aggregation layer: adapts backend micro‑services to different front‑ends.

Sidecar: the application‑layer gateway used for service registration, discovery, and circuit‑breaker/flow‑control.

Microservices.

Our architecture consists of:

API gateway layer – the sole entry for client traffic, originally Nginx providing routing, caching, access control, etc.

BFF layer – PHP (legacy) and Node.js (new) for API aggregation and business‑logic permission checks.

Backend layer – multi‑language micro‑services (PHP, Java, Python). PHP and Python register via sidecar to Eureka; Java uses native service registration.

Introducing Kong was driven by a surge of simulated‑user crawling traffic that caused QPS spikes, overloading backend services and risking an avalanche effect.

Before Kong, traffic control was attempted at the Nginx level and via the sidecar, but both approaches suffered from static configuration (Nginx) and coarse‑grained control (sidecar).

2.2 Gateway selection – why Kong

Kong has a vibrant community, many built‑in plugins, and its tech stack (nginx + lua + openresty) matches our existing Nginx expertise, reducing learning and migration costs.

2.3 Kong gateway overview

Kong is an open‑source, high‑availability, extensible API gateway built on OpenResty (Nginx + Lua). It stores configuration in PostgreSQL or Cassandra and provides RESTful APIs for management.

Kong advantages:

Scalable: data stored in PostgreSQL; nodes sharing the same DB form a cluster.

Modular: functionality extended via plugins; official plugins are free, custom plugins are straightforward; configuration via RESTful APIs.

Visualizable: all rule objects have RESTful interfaces, enabling visual management tools such as Konga.

2.3.1 Core concepts

Route – matches client requests by host, path, header, etc.

Service – abstraction of a backend service.

Upstream – load‑balancing object with health‑check and balancing algorithms.

Target – actual IP and port of a backend instance.

Plugin – adds features such as authentication, rate limiting, etc., applicable at Route, Service, or global level.

Request flow: client → Kong (Route matching) → Service → Upstream (load‑balancing) → backend, with plugins applied at appropriate stages.

2.3.2 Kong plugin loading

Kong implements its functionality by injecting Lua code into OpenResty phases. The following snippet shows a simplified Nginx configuration used by Kong.

init_by_lua_block {
    kong = require 'kong'
    kong.init() -- initialize Kong, create routes, preload plugins
}
init_worker_by_lua_block {
    kong.init_worker() -- worker‑level events, clustering, caching
}

upstream kong_upstream {
    server 0.0.0.1;
    balancer_by_lua_block {
        kong.balancer() -- load balancing
    }
    keepalive 60;
}

location / {
    rewrite_by_lua_block {
        kong.rewrite() -- apply global/rewrite plugins
    }
    access_by_lua_block {
        kong.access() -- route matching, plugin loading, balancer phase
    }
    header_filter_by_lua_block {
        kong.header_filter() -- execute header‑filter plugins
    }
    body_filter_by_lua_block {
        kong.body_filter() -- execute body‑filter plugins
    }
    log_by_lua_block {
        kong.log() -- log plugins
    }
}

The source code below iterates loaded plugins during the rewrite phase and invokes each plugin's rewrite handler.

for plugin, plugin_conf in plugins_iterator(singletons.loaded_plugins, true) do
  plugin.handler:rewrite(plugin_conf)
end

2.3.3 Haodf plugin usage

Native plugins used:

rate‑limiting

file‑log

acl

key_auth

Custom plugins:

Canary (gray) release plugin

rate‑limiting‑agent plugin

Rate limiting with role‑based control

Traffic is divided into normal user traffic, spider traffic, and malicious crawling traffic. Spiders are identified by User‑Agent strings; malicious traffic shows a sudden surge from the same UA.

Rate‑limiting workflow

key_auth plugin distinguishes spider vs. user traffic by UA.

rate‑limiting plugin applied to spider routes, with limits derived from load testing.

rate‑limiting‑agent plugin applied to user routes to cap requests per UA during short bursts.

Alert monitoring

Long‑term observation adjusts rate limits; monitoring dashboards show abnormal UA spikes, trigger alerts, and display backend metrics (capacity, throughput, latency) to evaluate limit adequacy.

Separation of Kong proxy and admin nodes

Proxy nodes listen on port 8000 for client traffic; admin nodes listen on 8001 for configuration. Admin interface is bound to 127.0.0.1 for security, and only proxy nodes can forward configuration requests via internal headers.

Canary release plugin

The plugin supports gray releases based on fixed IP/IP range or cookie values, enabling targeted traffic (e.g., 10% of non‑logged‑in users in Beijing) to be routed to a specific cluster for testing.

2.3.4 Issues encountered

Nginx file‑cache replacement

We evaluated two options: Kong's proxy_cache plugin (in‑memory, lost on restart) and a custom Kong plugin combined with Nginx's file cache (blocked by the inability to use variables in purge_cache_valid). Consequently, file‑level caching remains on the Nginx layer.

3. Conclusion

This article presented the basic concepts of API gateways and detailed Haodf's practical deployment of Kong, including ongoing research on replacing Nginx file cache. Readers with related experience are invited to share insights.

Author: You Jinzhong – Haodf online system engineer, responsible for core framework development and Kong gateway implementation.