Nginx config invalid parameter even though it is in documentation - nginx

Question

I am tryin to run nginx latest version with the following configuration, but I get nginx: [emerg] invalid parameter "route=bloomberg" in /etc/nginx/nginx.conf:13
docker run --rm -ti -v root_to_local_nginx_directory:/etc/nginx:ro -p 3080:80 --name=mynginx --entrypoint nginx nginx
# nginx.conf file inside root_to_local_nginx_directory
http {
map $cookie_route $route_from_cookie {
~.(?P<version>w+)$ $route;
}
split_clients "${remote_addr}" $random_route {
50% server bloomberg.com route=bloomberg;
* server yahoo.com route=yahoo;
}
upstream backend {
zone backend 64k;
server bloomberg.com route=bloomberg;
server yahoo.com route=yahoo;
sticky route $route_from_cookie $randomroute;
}
server {
# ...
listen 80;
location / {
proxy_set_header Host $host;
proxy_pass http://backend;
}
}
}
Why is this? According to the documentation this should be correct http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream.

Answer 1

The route=string parameter of the server directive within the upstream context is considered to be an enterprise-grade feature, and is thus only available through the commercial subscription, in NGINX Plus, not in OSS NGINX. (If you look closer into the documentation, you'll notice it's grouped together with the other parameters under a separate "available as part of our commercial subscription" subsection.)
Additionally, you're also trying to use some similar "server" parameters within the split_clients context as if they were actual directives interpreted by nginx, even though everything is supposed to be string literals in that context; it's unclear whether or not that part is responsible for any errors, but even if not, it's a bad style to introduce such confusion into your configuration.
References:
http://nginx.org/en/docs/http/ngx_http_upstream_module.html#server
http://nginx.org/en/docs/http/ngx_http_split_clients_module.html#split_clients
https://www.nginx.com/products/nginx/

Answer 2

The reason why you are seeing the error is because the split_clients module does not support the route parameter. Alternatively, you can do something along the lines:
upstream bloomberg {
server bloomberg.com route=bloomberg;
}
upstream yahoo {
server yahoo.com route=yahoo;
}
split_clients "${remote_addr}" $random_route {
50% bloomberg;
* yahoo;
}