Front‑end Gray Release Strategies and Practical Implementation

Introduction

During a recent interview I was asked about front‑end gray (canary) releases. In my previous company we designed a gray‑release solution that has been validated in multiple systems, and I now share the design, implementation details, and sample code.

Tips

Algorithms for traffic‑shaping (bucket‑leak, token‑bucket, etc.) are easy to find; this article focuses on practical ways to apply gray release in real projects rather than on the algorithms themselves.

What Is Gray Release?

Gray release (also called canary release) gradually rolls out a new feature to a specific subset of online users to reduce risk. For example, version 1.0 is stable, version 1.1 is under test; only users matching a gray rule (e.g., region, device) see 1.1. If serious issues appear, the rollout can be halted and users revert to 1.0.

Common Gray‑Release Schemes

There is no single best solution; the choice depends on business scenarios. Below are five typical schemes.

1. Simple Nginx Weighted Routing (⭐️)

Deploy two builds (stable and beta) separately.

Use Nginx weighted round‑robin to control traffic percentage (requires a cookie that marks the user).

Front‑end SDK writes a random, mostly‑unique identifier into the cookie.

On subsequent visits Nginx reads the cookie and serves the corresponding version.

Pros: Simple, no back‑end changes. Cons:

Only percentage‑based control; cannot combine with business logic.

Low controllability – rollback requires Nginx config change.

Poor issue‑collection; relies on user feedback.

If the cookie is cleared, the user may be assigned a different version.

2. Nginx + Lua + Redis (⭐️⭐️)

When a request reaches Nginx, the embedded Lua script extracts the client IP, queries Redis for a stored flag, and decides whether to serve the beta version. If no flag exists, the request follows the normal production flow. This approach offers higher performance but is less flexible for complex business rules.

3. Server‑Side Rendering (SSR) Routing (⭐️⭐️⭐️)

Two bundles (stable and beta) are deployed on separate servers. The backend adds a version entry to a cookie and stores the mapping in Redis. On the first request the server decides the version based on the gray rule; subsequent requests use the cookie/Redis entry to serve the same version.

4. Client‑Side Comment‑Based Guard (hard to maintain, not recommended)

Uses conditional compilation comments in the front‑end code to enable/disable features based on gray rules. This method becomes difficult to maintain as the number of features grows.

5. Full Stack Solution: Nginx + Backend + Redis + Front‑end SDK (⭐️⭐️⭐️)

Stable (1.0) and beta (1.1) versions each run behind their own Nginx instance. An entry‑level Nginx forwards traffic to the appropriate instance based on a gray rule. The flow is:

Client requests the site; if a gray rule matches, the backend sets a cookie and stores the user‑id in Redis, then redirects to the beta version.

If the request already carries the cookie, the backend returns the corresponding version; otherwise it checks Redis.

The front‑end SDK controls when to request the gray rule, handles callbacks, and can trigger the gray flow on specific pages or user actions.

Key terminology:

stable : production version (1.0).

beta : gray version (1.1).

uuid : user identifier used in the demo (passed via URL).

Code Example (Node.js)

// Demo: get user id from query, decide gray version
const uuid = ctx.query.uuid; // In real scenario use session info
const uuids = ['123','456','789']; // Users allowed to enter gray version
// Simulated Redis storage of user‑id and version
const redisUuids = [
  {id: '789', version: 'beta'},
  {id: '333', version: 'stable'}
];
// If uuid is in the whitelist, serve beta; otherwise stable

The above logic shows that when uuid is 123, 456 or 789 the request matches the gray rule and receives the beta version.

Docker Commands for the Demo

docker-compose build

docker-compose up -d

# Access the demo at http://localhost:8000

Recent Status

The author is currently in a hand‑over period before leaving the company, focusing on management hand‑over, sharing technical articles on Juejin, and preparing to wrap up the project.

Conclusion

There are many gray‑release solutions; choose the one that fits your business scenario. The demo code is intentionally simple and not production‑ready; real projects should adapt the ideas to their own architecture.