How to Implement Gray (Canary) Deployments with Nginx: Weight & Cookie Strategies

Gray release (also known as canary deployment) is a smooth transition method between old and new versions, allowing A/B testing by directing a portion of users to feature A and the rest to feature B, then gradually shifting all traffic to B once it proves stable.

It helps maintain overall system stability by detecting and fixing issues early during the rollout. Many large domestic companies already use gray release, and the following sections describe several Nginx‑based implementations.

1. Weight‑Based Implementation Using Nginx

First, take server A offline from Nginx’s upstream list, deploy the new code to it via Jenkins, and then update the Nginx configuration. The core configuration is the upstream block shown below.

<code>upstream webservers {
    server 192.168.201.121 weight=90;
    server 192.168.201.120 weight=10;
}

server {
    listen 80;
    location / {
        proxy_pass http://webservers;
    }
}
</code>

Weight values are not limited; a larger weight assigns more traffic to that server. After reloading Nginx, about 90 % of traffic goes to server B and 10 % to server A. If the new version passes validation, traffic can be fully shifted to server A, and the process repeated for server B. This approach is simple and relies solely on Nginx’s built‑in features.

2. Client‑Request Based Implementation

Again, take server A offline, deploy the latest code, and then configure Nginx to route requests based on client‑side markers such as cookies or custom headers.

<code>upstream webservers {
    server 192.168.201.121;
}
# Configuration for the new version server
upstream webservers_newweb {
    server 192.168.201.120;
}

server {
    listen 80;
    set $backend "webservers";
    # Check if request contains a specific marker; if present, forward to the new server
    if ($http_cookie ~* "A=a") {
        set $backend "webservers_newweb";
    }
    location / {
        # Forward to the server indicated by $backend
        proxy_pass http://$backend;
    }
}
</code>

In this method, Nginx examines the client’s Cookie or HTTP header (e.g., A=a ) and forwards matching requests to the new version (server A). Once the new version is verified, traffic can be switched entirely or partially to it, making this strategy suitable for targeting specific user groups.

Summary: Both approaches use Nginx and are straightforward to implement. Use the weight‑based method for general gradual rollouts, and the client‑request method when you need to direct a particular audience to the new version.