Canary deployments in Nginx - Commands & Configuration

Introduction

Canary deployments let you release new versions of your app to a small group of users first. This helps catch problems early without affecting everyone. Nginx can help route some traffic to the new version while most users stay on the old one.

When you want to test a new app version with a small group before full release

When you want to reduce risk by slowly rolling out changes

When you want to compare performance between old and new versions

When you want to quickly rollback if the new version has issues

When you want to gather user feedback on new features safely

Config File - nginx.conf

nginx.conf

http {
    upstream backend {
        server 192.168.1.10 weight=9;
        server 192.168.1.11 weight=1;
    }

    server {
        listen 80;

        location / {
            proxy_pass http://backend;
        }
    }
}

This config defines two backend servers. The first server (192.168.1.10) is the stable version getting 90% of traffic (weight=9). The second server (192.168.1.11) is the new canary version getting 10% of traffic (weight=1). Nginx balances requests based on these weights.

Commands

Check the Nginx configuration file for syntax errors before applying changes.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload Nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Send a request to Nginx to verify it routes traffic correctly to backend servers.

Terminal

curl -I http://localhost

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Wed, 01 Jan 2025 12:00:00 GMT

Content-Type: text/html

Content-Length: 612

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: Canary deployments send a small portion of traffic to the new version to test it safely before full rollout.

Common Mistakes

Setting equal weights for all backend servers during canary deployment

This sends equal traffic to old and new versions, defeating the purpose of a small test group.

Assign a smaller weight to the new version server to limit traffic during testing.

Reloading Nginx without testing the config syntax first

If the config has errors, Nginx may fail to reload, causing downtime.

Always run 'nginx -t' to verify config syntax before reloading.

Summary

Configure Nginx upstream with weighted backend servers to control traffic split.

Test the Nginx configuration syntax with 'nginx -t' before applying changes.

Reload Nginx to apply the new routing rules without downtime.

Verify traffic routing by sending requests and checking responses.