How to Implement Gray Release with Nginx: Step‑by‑Step Strategies

In a high‑availability software deployment architecture, gray release gradually pushes a new version of an application or feature to a subset of users instead of all users at once.

Nginx, as a high‑performance reverse proxy server, is an essential component for implementing gray release because of its powerful traffic control and routing capabilities.

Gray Release Schemes

We can implement gray release using the following strategies:

Header‑based (e.g., X-GrayRelease)

Cookie‑based

IP‑address‑based

Assume two Tomcat nodes, a production node ( tomcat-prod) and a canary node ( tomcat-canary) that hosts the new code but is not publicly exposed.

Scheme 1: Header‑based Gray Release

Use a custom request header such as X-GrayRelease to decide which node receives the request.

Nginx configuration example:

http {
    upstream tomcat_prod {
        server tomcat-prod1.example.com:8080;
    }
    upstream tomcat_canary {
        server tomcat-canary1.example.com:8080;
    }
    server {
        listen 80;
        server_name example.com;
        location / {
            # Check if X-GrayRelease header exists
            if ($http_x_grayrelease = "true") {
                # Route to canary environment
                proxy_pass http://tomcat_canary;
            }
            # Otherwise route to production
            proxy_pass http://tomcat_prod;
        }
    }
}

If the request contains X-GrayRelease: true, traffic is forwarded to tomcat_canary (the canary version).

Without the header or with any other value, traffic defaults to tomcat_prod (the production version).

Scheme 2: Cookie‑based Gray Release

Check a specific cookie value to decide routing.

Nginx configuration example:

http {
    upstream tomcat_prod {
        server tomcat-prod1.example.com:8080;
        server tomcat-prod2.example.com:8080;
    }
    upstream tomcat_canary {
        server tomcat-canary1.example.com:8080;
        server tomcat-canary2.example.com:8080;
    }
    server {
        listen 80;
        server_name example.com;
        location / {
            # Check if grayrelease cookie is "true"
            if ($cookie_grayrelease = "true") {
                proxy_pass http://tomcat_canary;
            }
            # Default to production
            proxy_pass http://tomcat_prod;
        }
    }
}

If the request carries a cookie grayrelease=true, traffic goes to tomcat_canary.

Otherwise, traffic goes to tomcat_prod.

Scheme 3: IP‑address‑based Gray Release

Route traffic based on the client’s IP address, e.g., a fixed IP for testers.

Nginx configuration example:

http {
    upstream tomcat_prod {
        server tomcat-prod1.example.com:8080;
    }
    upstream tomcat_canary {
        server tomcat-canary1.example.com:8080;
    }
    server {
        listen 80;
        server_name example.com;
        location / {
            # Route specific IP to canary
            if ($remote_addr = "192.168.1.100") {
                proxy_pass http://tomcat_canary;
            }
            # Default to production
            proxy_pass http://tomcat_prod;
        }
    }
}

Requests from IP 192.168.1.100 are routed to tomcat_canary.

All other users are routed to tomcat_prod.

2. Deployment Process

Typical steps for a gray‑release rollout:

Deploy the new version to the canary environment (e.g., tomcat-canary).

Configure Nginx routing rules according to the chosen gray‑release strategy and gradually increase the traffic share.

Test and verify the canary version using the designated header, cookie, or IP.

Full release – once validation succeeds, shift all traffic to the new version by updating Nginx to point to the canary (or production) node and remove the gray‑release conditions.

http {
    upstream tomcat_prod {
        server tomcat-prod1.example.com:8080 weight=90; # production weight 90
        server tomcat-canary1.example.com:8080 weight=10; # canary weight 10
    }
    server {
        listen 80;
        server_name example.com;
        location / {
            # Distribute traffic based on weight
            proxy_pass http://tomcat_prod;
        }
    }
}

3. Summary

By configuring Nginx for gray release using request headers, cookies, or IP addresses, you can expose a new version to a limited audience, verify its stability, and gradually increase traffic until the full rollout is safe.