Implementing Gray Release for HTTP Read APIs with Nginx and Gateway Layers

Gray Release Requirement

In an advertising system where write operations are triggered by back‑office staff and read operations by client apps, frequent interface changes create a need for gray releases: after a new feature is deployed, a subset of requests to the historic API A should be routed to the new implementation to verify reliability while minimizing the risk of a full‑line upgrade.

Two‑Layer Implementation Options

1. Nginx Layer

Nginx can embed Lua scripts to query business data and, based on gray‑release logic, forward the request to the appropriate upstream HTTP endpoint.

This approach requires coordination between developers and operations because updating Nginx configuration typically involves a platform tool and operator assistance.

2. Gateway Layer

The in‑house KIEV framework supports versioned interfaces, allowing a client to call a default version (0) or specify another version. By inserting gray‑release rules into the gateway, requests that match certain criteria are directed to a new version without changing client code.

Key modifications compared with the original architecture include:

Adding gray‑release rules to the gateway layer.

Supporting hot‑loading of rule data.

Upgrading backend KIEV services without changing gateway code.

Enabling interface‑level granular management to prevent backend hangs.

3. Detailed Gateway Implementation

(1) Gray‑Release Rule Design

Proportional rollout: Route a configurable percentage of traffic from an old version (e.g., V1) to a new version (V2). Setting the percentage to 100 % achieves full rollout.

IMEI‑based routing: Direct requests from specific IMEI numbers or patterns (e.g., IMEI=123456 or IMEI=123456*) to the new version.

Global rule: High‑priority rules that apply across all versions, such as forcing certain IMEIs to receive special data regardless of the normal processing flow.

(2) Abstract RPC Handling in the Gateway

The gateway must construct RPC requests dynamically based on configuration, avoiding any dependency on KIEV service definitions. This is achieved by:

Storing the mapping between HTTP endpoints and RPC method names/parameters in a configuration center (later possibly persisted in a database with local caching).

Restricting RPC method parameters to primitive types only, eliminating the need for custom classes and simplifying serialization.

Remaining optimization areas include monitoring interface quality, automating service governance, and improving the manageability of the configuration center data.