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.

Practice

1. What is the main purpose of a canary deployment in NGINX?

easy

A. To gradually route traffic between old and new application versions

B. To block all traffic during deployment

C. To increase server CPU usage intentionally

D. To disable logging temporarily

Solution

1. Step 1: Understand canary deployment concept

   Canary deployment means sending some traffic to a new version while most traffic still goes to the old version.

2. Step 2: Identify NGINX role in canary deployment

   NGINX controls traffic split using weights in upstream blocks to route requests gradually.

3. Final Answer:

   To gradually route traffic between old and new application versions -> Option A

4. Quick Check:

   Canary deployment = gradual traffic routing [OK]

Hint: Canary means gradual traffic shift, not blocking or disabling [OK]

Common Mistakes:

• Thinking canary blocks all traffic
• Confusing canary with load increase
• Assuming canary disables logging

2. Which NGINX configuration snippet correctly sets a 90% traffic weight to the old version and 10% to the new version?

easy

A. upstream backend { server old.example.com weight=90; server new.example.com weight=10; }

B. upstream backend { server old.example.com weight=10; server new.example.com weight=90; }

C. upstream backend { server old.example.com; server new.example.com; }

D. upstream backend { server old.example.com weight=100; server new.example.com weight=0; }

Solution

1. Step 1: Understand weight meaning in NGINX upstream

   Weight controls traffic share; higher weight means more traffic.

2. Step 2: Match weights to desired traffic split

   Old version should get 90%, new version 10%, so old weight=90, new weight=10.

3. Final Answer:

   upstream backend { server old.example.com weight=90; server new.example.com weight=10; } -> Option A

4. Quick Check:

   Weight 90 old, 10 new = 90% old traffic [OK]

Hint: Higher weight means more traffic; assign accordingly [OK]

Common Mistakes:

• Swapping weights between old and new servers
• Omitting weights defaults to equal traffic
• Setting weight=0 disables server completely

3. Given this NGINX upstream configuration:

upstream backend {
  server old.example.com weight=80;
  server new.example.com weight=20;
}

What percentage of traffic will be routed to new.example.com?

medium

A. 80%

B. 20%

C. 50%

D. 100%

Solution

1. Step 1: Calculate total weight

   Total weight = 80 (old) + 20 (new) = 100.

2. Step 2: Calculate new server traffic percentage

   New server traffic = (20 / 100) * 100% = 20%.

3. Final Answer:

   20% -> Option B

4. Quick Check:

   New server weight 20 of 100 total = 20% traffic [OK]

Hint: Traffic % = server weight / total weight * 100 [OK]

Common Mistakes:

• Confusing weight with percentage directly
• Adding weights incorrectly
• Assuming equal traffic without weights

4. You wrote this NGINX upstream block for canary deployment:

upstream backend {
  server old.example.com weight=70
  server new.example.com weight=30;
}

But NGINX fails to start. What is the error?

medium

A. Cannot use weight in upstream block

B. Weight values must be equal

C. Missing semicolon after first server directive

D. Server names must be IP addresses

Solution

1. Step 1: Check syntax of upstream block

   Each server directive must end with a semicolon in NGINX config.

2. Step 2: Identify missing semicolon

   First server line lacks semicolon after weight=70, causing syntax error.

3. Final Answer:

   Missing semicolon after first server directive -> Option C

4. Quick Check:

   Semicolons required after each directive [OK]

Hint: Check semicolons after each server line [OK]

Common Mistakes:

• Ignoring missing semicolon errors
• Thinking weights must be equal
• Assuming server names must be IPs

5. You want to deploy a new version with 5% traffic initially, then increase to 50% after testing. Which NGINX configuration approach supports this canary deployment best?

hard

A. Use limit_conn to limit new server connections

B. Use proxy_pass without weights to split traffic

C. Set weight=0 for new server until ready

D. Manually update weight values in upstream block and reload NGINX

Solution

1. Step 1: Understand canary traffic control in NGINX

   NGINX uses weights in upstream blocks to control traffic percentage per server.

2. Step 2: Adjust weights gradually and reload NGINX

   Manually changing weights from 5 to 50 and reloading NGINX safely shifts traffic as needed.

3. Final Answer:

   Manually update weight values in upstream block and reload NGINX -> Option D

4. Quick Check:

   Weight changes + reload = traffic control [OK]

Hint: Change weights and reload to shift traffic gradually [OK]

Common Mistakes:

• Using proxy_pass without weights for traffic split
• Setting weight=0 disables server, not gradual traffic
• Using limit_conn limits connections, not traffic percentage