Upstream Configuration

Basic Upstream Block

upstream backend {
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
    server 10.0.0.3:8080;
}

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

Server Parameters

upstream backend {
    # Weight - traffic distribution
    server 10.0.0.1:8080 weight=5;
    server 10.0.0.2:8080 weight=3;
    server 10.0.0.3:8080 weight=1;

    # Max connections (requires zone)
    server 10.0.0.4:8080 max_conns=100;

    # Failure detection
    server 10.0.0.5:8080 max_fails=3 fail_timeout=30s;

    # Backup server
    server 10.0.0.6:8080 backup;

    # Mark as down (maintenance)
    server 10.0.0.7:8080 down;
}

Unix Sockets

upstream php-fpm {
    server unix:/var/run/php/php-fpm.sock;
}

upstream gunicorn {
    server unix:/var/run/gunicorn/socket;
}

server {
    location ~ \.php$ {
        fastcgi_pass php-fpm;
    }
}

Keepalive Connections

upstream backend {
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;

    # Keep connections open to backend
    keepalive 32;
    keepalive_requests 1000;
    keepalive_timeout 60s;
}

server {
    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

Shared Memory Zone

upstream backend {
    # Shared zone for runtime state
    zone backend_zone 64k;

    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
}

Hash Methods

IP Hash (Session Persistence)

upstream backend {
    ip_hash;
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
}

Generic Hash

# Hash by request URI
upstream backend {
    hash $request_uri consistent;
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
}

# Hash by cookie
upstream backend {
    hash $cookie_sessionid consistent;
    server 10.0.0.1:8080;
    server 10.0.0.2:8080;
}

Multiple Upstreams

upstream api_servers {
    server 10.0.0.1:3000;
    server 10.0.0.2:3000;
}

upstream static_servers {
    server 10.0.0.10:80;
    server 10.0.0.11:80;
}

upstream websocket_servers {
    server 10.0.0.20:8080;
    ip_hash;
}

server {
    location /api/ {
        proxy_pass http://api_servers;
    }

    location /static/ {
        proxy_pass http://static_servers;
    }

    location /ws/ {
        proxy_pass http://websocket_servers;
    }
}

Slow Start

upstream backend {
    server 10.0.0.1:8080 slow_start=30s;
    server 10.0.0.2:8080 slow_start=30s;
}

DNS Resolution

resolver 8.8.8.8 valid=30s;

upstream backend {
    zone backend 64k;
    server backend.example.com resolve;
}