How to Use Nginx split_clients and map for Traffic Splitting by Device and Version

1. Scenario Description

In production environments, traffic distribution has many cases; the article focuses on two scenarios:

When a new version is released, real‑traffic testing is needed with a gradual increase in traffic to the new version to limit impact if issues arise.

Because mobile and PC devices differ, traffic from each should be handled separately, allowing independent upgrades, strong controllability, and flexible architecture.

2. Nginx Strategy Configuration

For the above scenarios, Nginx as a powerful web server can satisfy the requirements with simple configuration.

nginx version: nginx/1.16.1
os version: centos 7

The solution relies on two Nginx modules:

ngx_http_split_clients_module – documentation: http://nginx.org/en/docs/http/ngx_http_split_clients_module.html

ngx_http_map_module – documentation: http://nginx.org/en/docs/http/ngx_http_map_module.html

3. Traffic Proportion Allocation with ngx_http_split_clients_module

Using the split_clients module, traffic is distributed proportionally based on client attributes (e.g., IP) via a hash algorithm, allowing a portion of traffic to be directed to a new version.

user nobody;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log  /var/log/nginx/access.log  main;
    include             /etc/nginx/mime.types;
    default_type        application/octet-stream;

    split_clients "${remote_addr}AAA" $version {
        50%   v1;
        *     v2;
    }

    server { listen 8081; location / { return 200 "v1
"; } }
    server { listen 8082; location / { return 200 "v2
"; } }

    server {
        listen 80;
        location / { proxy_pass http://127.0.0.1/$version; }
        location /v2 { proxy_pass http://127.0.0.1:8082/; }
        location /v1 { proxy_pass http://127.0.0.1:8081/; }
    }
}

The split_clients directive hashes $remote_addr and assigns $version as v1 or v2 according to the defined percentages; the asterisk represents the remaining traffic. The trailing slash in proxy_pass removes the version prefix, keeping the original request URI unchanged.

Actual effect:

4. Mobile and PC Traffic Allocation with ngx_http_map_module

The map module matches client attributes (e.g., User‑Agent) to a new variable, enabling traffic routing based on device type.

user nobody;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;

events { worker_connections 1024; }

http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log  /var/log/nginx/access.log  main;
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    map "$http_user_agent" $uatype {
        default   nomobile;
        "~*mobile" mobile;
    }

    server { listen 8082; location / { return 200 "nomobile
"; } }
    server { listen 8081; location / { return 200 "mobile
"; } }

    server {
        listen 80;
        location / { proxy_pass http://127.0.0.1/$uatype; }
        location /nomobile { proxy_pass http://127.0.0.1:8082/; }
        location /mobile { proxy_pass http://127.0.0.1:8081/; }
    }
}

The map directive uses a regular expression to detect "mobile" in the User‑Agent; matched clients get $uatype set to mobile, otherwise nomobile. The variable then determines which backend (mobile or PC) receives the request. Adding a trailing slash in proxy_pass removes the prefix, preserving the original URI.

Actual effect:

5. Summary

Beyond the examples shown, you can customize traffic splitting using variables such as $http_name or $arg_name to obtain custom headers or URI parameters, enabling more sophisticated routing scenarios like post‑login header injection combined with map directives.