Header title

Nginx Upstream & Load Balancing Configuration Generator

Generate production-ready Nginx upstream blocks with round-robin, least_conn, ip_hash, keepalive, and health check parameters.

Presets label
Input label
Server nodes label4 nodes
#1
Weight:
Max Fails:
Fail Timeout:
Max Conns (0=inf):
#2
Weight:
Max Fails:
Fail Timeout:
Max Conns (0=inf):
#3
Weight:
Max Fails:
Fail Timeout:
Max Conns (0=inf):
#4
Weight:
Max Fails:
Fail Timeout:
Max Conns (0=inf):
Performance tuning
Synchronizes node states across worker processes in multi-core environments.
Pool Conns:
Idle Timeout:
Reduces TCP handshake latency up to 60% by maintaining persistent HTTP/1.1 sockets.
Proxy settings
Server Port:
Server Name:
Location Path:
1# ========================================================
2# Upstream Pool: microservice_api_cluster
3# Load Balancing Method: LEAST_CONN
4# Generated by ToolsAA (100% Client-Side Private Generator)
5# ========================================================
6upstream microservice_api_cluster {
7 # Shared memory zone across all worker processes
8 zone microservice_api_zone 64k;
9
10 # Directs traffic to the server with fewest active connections
11 least_conn;
12
13 # Backend server cluster nodes
14 server 10.0.1.11:8080 weight=5 max_fails=3 max_conns=500;
15 server 10.0.1.12:8080 weight=5 max_fails=3 max_conns=500;
16 server 10.0.1.13:8080 weight=3 max_fails=3 max_conns=300;
17 server 10.0.1.99:8080 max_fails=3 backup;
18
19 # Upstream HTTP/1.1 persistent connection pool
20 keepalive 32;
21 keepalive_requests 1000;
22 keepalive_timeout 60s;
23}
Stats card1
3 Primaries/1 Backups
Active cluster load capacity: 75%
Stats card2
least conn
Worker sync enabled via 64k memory zone
Stats card3
32 idle sockets pool
Standard HTTP/1.1 connection reuse

Client-Side Processing

High-performance processing executed entirely in browser memory.

Zero Server Upload Privacy

All data payloads remain strictly local with zero external server communication.

Production Ready Export

Clean, optimized output formats ready for immediate deployment.

Technical Reference & Architecture Guide

Nginx Upstream & Load Balancing Configuration Generator Developer Guide — Reference Guide

Generate production-ready Nginx upstream blocks with round-robin, least_conn, ip_hash, keepalive, and passive health check parameters.

Key Parameters & Controls

serverdirective (string)

Specifies the backend server address (IP or FQDN), port, and optional control flags such as weight, max_fails, fail_timeout, backup, and down.

Default: server 127.0.0.1:8080 weight=1 max_fails=1 fail_timeout=10s
algorithmdirective (enum)

Selects the distribution method: weighted round-robin (default), least_conn (fewest active connections), ip_hash (client IPv4/IPv6 sticky sessions), or generic hash (consistent hashing).

Default: round-robin (implicit)
keepaliveinteger

Sets the maximum number of idle keepalive connections to upstream servers preserved in the cache of each worker process.

Default: 32
keepalive_requestsinteger

Sets the maximum number of requests that can be served through one keepalive connection before closing it.

Default: 1000
keepalive_timeouttime (string)

Sets a timeout during which an idle keepalive connection to an upstream server will stay open.

Default: 60s
zonestring

Defines the name and allocation size of the shared memory zone that stores the upstream group runtime state and configuration across all worker processes.

Default: upstream_backend 64k

Pro Tips & Best Practices

Enable HTTP/1.1 for Upstream Keepalive

Declaring 'keepalive 32;' alone does not enable persistent connections. In your location block, you must explicitly set 'proxy_http_version 1.1;' and clear the connection header with 'proxy_set_header Connection "";'. Otherwise, Nginx defaults to HTTP/1.0 with Connection: close, creating a new TCP handshake for every request.

Zero-Downtime Maintenance with Backup & Down Flags

Mark deprecated instances with the 'down;' parameter to stop routing without altering upstream indexing. Use 'backup;' on fallback cluster instances so they receive traffic only when all primary backend nodes become unavailable due to fail_timeout.

Consistent Hashing for Cache Clusters

When distributing requests across stateful cache or rendering services, use 'hash $request_uri consistent;' instead of round-robin. Consistent hashing minimizes cache re-sharding when upstream nodes are dynamically added or removed.

Fine-Tune proxy_next_upstream Failovers

Protect your database against duplicate mutating transactions by configuring 'proxy_next_upstream error timeout http_502 http_503;'. Avoid adding 'non_idempotent' unless your backend API design is completely idempotent for POST and PATCH requests.

Common Gotchas & Troubleshooting

Upstream timed out (110: Connection timed out) or 504 Gateway Timeout

Verify backend firewall rules and verify that 'proxy_connect_timeout', 'proxy_read_timeout', and 'proxy_send_timeout' match application execution times. Ensure worker connections and file descriptor limits (worker_rlimit_nofile) are elevated on high-concurrency systems.

ip_hash routes all incoming traffic to a single backend node

If Nginx is behind Cloudflare, AWS ALB, or an outer CDN, client IPs will all resolve to the reverse proxy subnet. Replace 'ip_hash' with 'hash $http_cf_connecting_ip consistent;' or configure the real_ip module with 'set_real_ip_from' and 'real_ip_header X-Forwarded-For;'.

502 Bad Gateway during worker reloads or traffic surges

The upstream application queue may be overflowing. Increase the OS socket listen backlog (net.core.somaxconn) on the backend and configure 'max_conns' on the upstream server directive to prevent saturating application processes.

Frequently Asked Questions

What is the difference between Round Robin, least_conn, and ip_hash?▼

Round Robin distributes requests sequentially weighted by server capacity. least_conn routes each request to the server with the lowest number of active connections, making it ideal for workloads with varying response durations. ip_hash uses the first three octets of an IPv4 address (or full IPv6) to route a client reliably to the same server, providing basic sticky session persistence.

How do passive health checks work in open-source Nginx?▼

Open-source Nginx employs passive monitoring via 'max_fails' and 'fail_timeout'. If an upstream fails max_fails consecutive attempts within fail_timeout, Nginx temporarily pauses sending requests to that server for the duration of fail_timeout. Active synthetic probing ('health_check') requires Nginx Plus or third-party Lua modules.

Why is 'proxy_set_header Connection "";' necessary for upstream keepalive?▼

By default, Nginx reverse proxy forwards incoming client headers, and HTTP/1.0 uses 'Connection: close'. Setting 'proxy_http_version 1.1;' and removing the Connection header signals to backend servers that the TCP socket should remain open for subsequent requests from the keepalive pool.

How does dynamic DNS resolution work with Nginx upstream servers?▼

In open-source Nginx, server domain names defined in upstream blocks are resolved once at startup. If IPs change dynamically (e.g., in AWS ECS or Kubernetes), Nginx will not re-resolve them without reload. To enable dynamic DNS resolution, use a variable with proxy_pass (e.g., 'set $backend "http://api.internal:8080"; proxy_pass $backend;') alongside a configured 'resolver' directive.

Related Tools & Utilities

All Tools →