Explain the configuration and function of nginx upstream

Configuration example

upstream backend {
  server backend1.example.com    weight=5;
  server backend2.example.com:8080;
  server unix:/tmp/backend3;

  server backup1.example.com:8080  backup;
  server backup2.example.com:8080  backup;
}

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

instruction

语法:	upstream name { ... }
默认值:	―
上下文:	http

Define 1 set of servers. These servers can listen on different ports. Also, servers listening on sockets in the TCP and UNIX domains can be mixed.

Example:

upstream backend {
  server backend1.example.com weight=5;
  server 127.0.0.1:8080    max_fails=3 fail_timeout=30s;
  server unix:/tmp/backend3;
}

By default, nginx distributes requests to servers in a weighted rotation. In the example above, every 7 requests are distributed as follows: 5 requests to backend1.example.com, 1 request to a second server, and 1 request to a third server. When communicating with a server, if an error occurs, the request is passed to the next server until all available servers have been tried. If all servers return a failure, the client will get a (failed) response from the last server to communicate.

语法:	server address [parameters];
默认值:	―
上下文:	upstream

Define the server's address address and other parameters parameters. The address can be a domain name or an IP address, with an optional port, or the path to an UNIX domain socket with the "unix:" prefix. If no port is specified, port 80 is used. If one domain name resolves to more than one IP, you are essentially defining more than one server.

You can define the following parameters: weight=number set the weight of the server, default is 1. max_fails=number sets the number of failed attempts by Nginx to communicate with the server. If the number of failures reaches this value during the time period defined by the fail_timeout parameter, Nginx considers the server unavailable. In the next fail_timeout period, the server will not be tried again. The default number of failed attempts is 1. Setting it to 0 will stop counting the number of attempts, considering the server to be 1 directly available. You can configure what a failed attempt is by the proxy_next_upstream, fastcgi_next_upstream, and memcached_next_upstream directives. When configured by default, the http_404 state is not considered a failed attempt. fail_timeout = time setting

Time period for counting failed attempts. During this time, the server is considered unavailable when the number of server failures reaches the specified number of attempts. The time period during which the server is considered unavailable.

By default, this timeout is 10 seconds. backup is marked as a secondary server. When the primary server becomes unavailable, the request is passed to these servers. The down flag server is permanently unavailable and can be used with ip_hash directive 1.

Example:

upstream backend {
  server backend1.example.com   weight=5;
  server 127.0.0.1:8080      max_fails=3 fail_timeout=30s;
  server unix:/tmp/backend3;

  server backup1.example.com:8080 backup;
}

语法:	ip_hash;
默认值:	―
上下文:	upstream

Specify a load balancing method for the server group, where requests are distributed between servers based on the client's IP address. The first three bytes of the IPv4 address, or the entire address of IPv6, will be used as a hash key. This approach ensures that requests from the same client are passed to the same server. Except when the server is deemed unavailable, these client requests are passed to other servers, most likely the same server.

IPv6 addresses are supported starting with versions 1.3.2 and 1.2.2.

If one of the servers wants to be temporarily removed, add the down parameter. This preserves the current client IP address hash distribution.

Example:

upstream backend {
  ip_hash;

  server backend1.example.com;
  server backend2.example.com;
  server backend3.example.com down;
  server backend4.example.com;
}

Starting with versions 1.3.1 and 1.2.2, the load balancing method of ip_hash supports setting server weights.

语法:	keepalive connections;
默认值:	―
上下文:	upstream

This directive appears in version 1.1.4.

Enable caching of connections to upstream servers.

The connections parameter sets the maximum number of connections that each worker process can maintain with the back-end server. The remaining connections are put into the cache. If the number of connections is greater than this value, the longest unused connection is closed.

It is important to note that the keepalive directive does not limit the total number of connections between the Nginx process and the upstream server. New connections are always created on demand. The connections parameter should be set a little less than 1 point so that the upstream server can also handle additional incoming connections.

Example of configuring memcached upstream server to connect to keepalive:

upstream memcached_backend {
  server 127.0.0.1:11211;
  server 10.0.0.2:11211;

  keepalive 32;
}

server {
  ...

  location /memcached/ {
    set $memcached_key $uri;
    memcached_pass memcached_backend;
  }

}

For the HTTP proxy, the proxy_http_version directive should be set to "1.1" and the value of the "Connection" header should be cleared.

upstream http_backend {
  server 127.0.0.1:8080;

  keepalive 16;
}

server {
  ...

  location /http/ {
    proxy_pass http://http_backend;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    ...
  }
}

Alternatively, a persistent connection for the HTTP/1.0 protocol can also be made by sending the "Connection: Keep-Alive" header. It's not recommended.

For FastCGI servers, the fastcgi_keep_conn directive needs to be set to make the keepalive connection work:

upstream fastcgi_backend {
  server 127.0.0.1:9000;

  keepalive 8;
}

server {
  ...

  location /fastcgi/ {
    fastcgi_pass fastcgi_backend;
    fastcgi_keep_conn on;
    ...
  }
}

When the load balancing method used is not the default rotation method, it must be configured before the keepalive directive.

There are no plans to implement the keepalive connection for the SCGI and uwsgi protocols.

语法:	least_conn;
默认值:	―
上下文:	upstream

This directive appears in versions 1.3.1 and 1.2.2.

Specifies a load balancing method for a server group that sends requests to the server with the lowest number of active connections, based on its weight. If there are multiple such servers, try a weighted rotation method.

Embedded variables

The ngx_http_upstream_module module supports the following embedded variables:

$upstream_addr saves the server's IP address and port or the path of the UNIX domain socket. During request processing, if multiple servers are tried, their addresses are spliced together, separated by commas, such as "192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock". If there is an internal jump between servers via the "X-Accel-Redirect" header or error_page, these server groups are separated by a colon, such as "192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock: 192.168.10.1:80, 192.168.10.2:80". $upstream_response_time reserves the server's response time in milliseconds, in seconds. When multiple responses occur, they are also separated by a comma and a colon. $upstream_status saves the server's response code. When multiple responses occur, they are also separated by a comma and a colon. $upstream_http_... Saves the value of the server's response header. For example, the value of the "Server" response header can be obtained by the $upstream_http_server variable. It is important to note that only the last responding head is retained.