Configure Load Balancing

AIStor’s distributed architecture allows any node to handle any request. While clients can connect directly to individual nodes, a load balancer provides a single endpoint that simplifies client configuration and automatically routes traffic to healthy nodes.

Load balancers also centralize SSL/TLS certificate management and can terminate encryption at the network edge, reducing computational overhead on AIStor nodes.

Prerequisites

Your load balancer configuration must support these AIStor requirements:

Dual-service routing: Configure separate routes for the S3 API (port 9000) and Console UI (port 9001).
Streaming uploads: Allow unlimited request body size and disable request buffering to support uploading objects of any size.
Streaming downloads: Disable response buffering to support downloading large objects.

Example configurations

These examples show how to implement the prerequisites for common reverse proxies.

NGINX

Add these directives to your NGINX server block:

# Allow unlimited upload size
client_max_body_size 0;

# Disable buffering for streaming
proxy_buffering off;
proxy_request_buffering off;

For additional NGINX proxy configuration options, see the NGINX Proxy Module Documentation.

HAProxy

Add these settings to your HAProxy configuration:

defaults
    # Extended timeouts for large operations
    timeout client  300s
    timeout server  300s

    # Disable response buffering
    option http-buffer-request

HAProxy does not buffer request bodies by default. The option http-buffer-request directive controls response buffering behavior.

For additional HAProxy configuration options, see the HAProxy Configuration Manual.

Configuration requirements

Configure AIStor with the appropriate environment variable and DNS settings to ensure proper communication through your load balancer.

Domain-based routing

Domain-based routing uses separate hostnames for the S3 API and Console UI (recommended for production deployments).

Configure your load balancer to route traffic based on hostname:
- aistor.example.com → Backend port 9000
- console.aistor.example.com → Backend port 9001
Set MINIO_BROWSER_REDIRECT_URL to your Console UI domain:
```
MINIO_BROWSER_REDIRECT_URL="https://console.aistor.example.com"
```
Add this variable to /etc/default/minio then restart the AIStor service:
```
sudo systemctl restart aistor-server
```

Path-based routing

Path-based routing uses a single hostname with different paths for the S3 API and Console UI.

Configure your load balancer to route traffic based on URL path:
- / (root path) → Backend port 9000 (S3 API)
- /console → Backend port 9001 (Console UI)
Set MINIO_BROWSER_REDIRECT_URL to your Console UI path:
```
MINIO_BROWSER_REDIRECT_URL="https://aistor.example.com/console"
```
Add this variable to /etc/default/minio then restart the AIStor service:
```
sudo systemctl restart aistor-server
```

For detailed information about the MINIO_BROWSER_REDIRECT_URL environment variable and additional console configuration options, see Console Environment Variables.

Verify your configuration

After configuring your load balancer, verify it works correctly using the load balancer’s client-facing IP or hostname before updating production DNS.

Test the health endpoint through your load balancer:
```
curl https://LOAD_BALANCER_IP_OR_HOSTNAME/minio/health/live
```
Expected response: 200 OK with body OK

Replace LOAD_BALANCER_IP_OR_HOSTNAME with your load balancer’s client-facing IP or hostname.

For comprehensive health check documentation, see Health Check Probes.
Configure and test the AIStor Client connection using your load balancer’s client-facing IP or hostname:
```
mc alias set myaistor https://LOAD_BALANCER_IP_OR_HOSTNAME ACCESS_KEY SECRET_KEY
mc ping myaistor
mc ready myaistor
```
Replace LOAD_BALANCER_IP_OR_HOSTNAME with your load balancer’s client-facing IP or hostname, and ACCESS_KEY and SECRET_KEY with appropriate credentials.
Verify Console UI access by opening https://LOAD_BALANCER_IP_OR_HOSTNAME in your web browser, logging in, and browsing objects.

Replace LOAD_BALANCER_IP_OR_HOSTNAME with your load balancer’s client-facing IP or hostname.

Update DNS for production

After successfully verifying your load balancer configuration, update your DNS records to point your production endpoints to the load balancer.

Domain-based routing Path-based routing

Once DNS propagates, clients can access AIStor through the configured domain names.