What upstream means in Nginx

An upstream is a backend Nginx talks to while handling a request. An upstream block gives a group of backend servers a name that a directive such as proxy_pass can reference. You can also proxy directly to an address without defining a group.

Define and reference a backend group

Inside http:

upstream myapp {
    server 10.0.0.5:8080;
    server 10.0.0.6:8080;
    server 10.0.0.7:8080 weight=3;
    server 10.0.0.8:8080 backup;
}

server {
    listen 80;
    location / {
        proxy_pass http://myapp;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

The normal policy is weighted round robin. Among the three available primary servers shown, the weights are 1:1:3. They express relative selection share, not a promise of equal CPU work or exact percentages in every short interval. The backup handles requests when primary servers cannot be used, subject to the configured balancing method.

Choose a policy for the workload

least_conn prefers fewer active connections while accounting for weights. ip_hash uses the client address for affinity. hash $cookie_sessionid consistent; is an example of key-based selection when that cookie is suitable and present.

These are alternative policies, not directives to enable simultaneously. Feature combinations have restrictions: for example, backup servers are not compatible with every hash-based method. A routing key does not provide shared application state or authentication.

Understand passive failure detection

upstream myapp {
    server 10.0.0.5:8080 max_fails=3 fail_timeout=30s;
    server 10.0.0.6:8080 max_fails=3 fail_timeout=30s;
}

Qualifying failures within the interval can make a peer temporarily unavailable for that interval. What counts as failure depends in part on the upstream protocol and retry configuration. This is passive behavior based on requests, not a continuously running active probe.

For a group containing only one server, max_fails and fail_timeout are ignored; that server is not marked unavailable by this mechanism. A one-server group is still useful for naming and shared configuration, but does not create a failover target.

Retries are constrained by response progress, request replayability, and configured limits. Do not assume Nginx can safely replay a non-idempotent operation after the backend has received it.

Observe individual backend attempts

Record $upstream_addr, $upstream_status, and $upstream_response_time. These variables also work with direct proxy destinations; they are not exclusive to named groups. A single request can have multiple values after retries. Validate parsing before comparing peers through the Guance Nginx integration.

FAQ

Can a server entry use a hostname?

Yes. Without dynamic resolution, names are resolved when configuration is loaded. Open-source Nginx supports the upstream resolve parameter from 1.27.3; it requires the documented resolver and shared-memory-zone setup. Older versions or other approaches have different constraints. A variable in proxy_pass is not the only possible solution.

Can weights implement a gradual rollout?

They can approximate request shares under the selected balancing policy. Compare outcomes and capacity, and account for failed peers, persistent sessions, and request variability. A 1:9 weight does not guarantee exactly 10% of users or processing cost.

Must every proxy use an upstream block?

No. Use it when group configuration, naming, balancing, or connection management benefits the service. A direct destination can be appropriate for a simple case.

Reference: Nginx upstream module.