load-balancer

Configures nginx load balancing with upstream servers, health checks, and failover strategies. Use when setting up load balancing, distributing traffic across multiple servers, or configuring upstream backends.

⭐19stars🔀4forks📁View on GitHub🕐Updated Dec 2, 2025

When & Why to Use This Skill

This Claude skill automates the configuration of Nginx load balancing to ensure high availability and optimal traffic distribution. It provides comprehensive templates for setting up upstream server groups, implementing passive health checks, and configuring failover strategies. By supporting various algorithms like Round-robin, Least Connections, and IP Hash, it helps developers and DevOps engineers build resilient web architectures that can handle high traffic volumes and maintain session persistence.

Use Cases

  • High Availability Setup: Distributing incoming web traffic across multiple backend servers to prevent single points of failure.
  • Automatic Failover: Configuring health checks to detect server downtime and automatically reroute traffic to healthy instances or backup servers.
  • Session Persistence: Using IP Hash or sticky sessions to ensure users remain connected to the same backend server during their session.
  • Resource Optimization: Implementing weighted load balancing to distribute more traffic to high-capacity servers while protecting weaker ones.
  • WebSocket Support: Configuring proxy headers and connection upgrades to enable real-time communication through a load balancer.
nameload-balancer
descriptionConfigures nginx load balancing with upstream servers, health checks, and failover strategies. Use when setting up load balancing, distributing traffic across multiple servers, or configuring upstream backends.

Load Balancer Configuration

Quick Start

Configure nginx to distribute traffic across multiple backend servers with health checks and automatic failover.

Instructions

Step 1: Define upstream block

Create an upstream block with your backend servers:

upstream backend {
    # Load balancing method (optional, defaults to round-robin)
    least_conn;  # or ip_hash, or omit for round-robin
    
    # Backend servers
    server backend1.example.com:8080 weight=3;
    server backend2.example.com:8080 weight=2;
    server backend3.example.com:8080;
    
    # Backup server (used when all primary servers are down)
    server backup.example.com:8080 backup;
    
    # Health check parameters
    keepalive 32;
}

Step 2: Configure proxy in server block

Add proxy configuration to route traffic to the upstream:

server {
    listen 80;
    server_name example.com;
    
    location / {
        proxy_pass http://backend;
        
        # Essential proxy headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Timeouts
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
        
        # Buffering
        proxy_buffering on;
        proxy_buffer_size 4k;
        proxy_buffers 8 4k;
    }
}

Step 3: Add health checks

Configure passive health checks (active checks require nginx Plus):

upstream backend {
    server backend1.example.com:8080 max_fails=3 fail_timeout=30s;
    server backend2.example.com:8080 max_fails=3 fail_timeout=30s;
    server backend3.example.com:8080 max_fails=3 fail_timeout=30s;
}

Parameters:

  • max_fails: Number of failed attempts before marking server as unavailable
  • fail_timeout: Time to wait before retrying a failed server

Step 4: Test and reload

# Test configuration
nginx -t

# Reload nginx
nginx -s reload

Load Balancing Methods

Round-robin (default): Distributes requests evenly across servers

upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;
}

Least connections: Routes to server with fewest active connections

upstream backend {
    least_conn;
    server backend1.example.com:8080;
    server backend2.example.com:8080;
}

IP hash: Routes same client IP to same server (session persistence)

upstream backend {
    ip_hash;
    server backend1.example.com:8080;
    server backend2.example.com:8080;
}

Weighted: Distributes based on server capacity

upstream backend {
    server backend1.example.com:8080 weight=3;  # Gets 3x traffic
    server backend2.example.com:8080 weight=1;
}

Common Patterns

WebSocket proxying

location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}
upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;
    
    # Requires nginx Plus or third-party module
    sticky cookie srv_id expires=1h domain=.example.com path=/;
}

Slow start (nginx Plus)

upstream backend {
    server backend1.example.com:8080 slow_start=30s;
    server backend2.example.com:8080 slow_start=30s;
}

Advanced

For detailed information, see:

  • Upstream Patterns - Advanced load balancing algorithms and patterns
  • Health Checks - Comprehensive health check configuration
  • Caching - Proxy caching strategies for load-balanced backends