Configure Load Balancing

MinIO 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 MinIO AIStor nodes.

Prerequisites

Your load balancer configuration must support these MinIO 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 Ingress controllers.

Add these annotations to your Ingress resource:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/ignore-invalid-headers: "false"
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
    nginx.ingress.kubernetes.io/proxy-buffering: "off"
    nginx.ingress.kubernetes.io/proxy-request-buffering: "off"

If your MinIO AIStor backend uses HTTPS, also add:

    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

For additional NGINX Ingress annotations, see the NGINX Ingress Annotations Reference.

Deprecation warning

Open source Ingress NGINX version has been retired as of March 2026

Add these annotations to your Ingress resource:

metadata:
  annotations:
    haproxy.org/timeout-server: "300s"

HAProxy does not buffer request bodies by default, which supports streaming uploads. Use the backend-config-snippet annotation to add additional HAProxy directives if needed:

    haproxy.org/backend-config-snippet: |
      option http-keep-alive

If your MinIO AIStor backend uses HTTPS, also add:

    haproxy.org/server-ssl: "true"

For additional HAProxy Ingress annotations, see the HAProxy Ingress Controller Documentation.

Traefik does not buffer request bodies by default, which supports streaming uploads. Do not attach the Traefik buffering middleware, because it reads the whole request body before it forwards the request.

Route traffic to MinIO AIStor with an IngressRoute:

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: aistor-s3
spec:
  routes:
    - match: Host(`aistor.example.com`)
      kind: Rule
      services:
        - name: aistor-hl
          port: 9000

For additional Traefik configuration options, see the Traefik documentation.

Configuration requirements

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

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

Configure your load balancer or Ingress to route traffic based on hostname:
- aistor.example.com → Service port 9000
- console.aistor.example.com → Service port 9001
Obtain your load balancer’s client-facing IP or hostname:

For Kubernetes deployments using LoadBalancer services:
```
kubectl get svc -n primary-object-store
```
For Ingress-based deployments, use your Ingress controller’s external endpoint.

Set MINIO_BROWSER_REDIRECT_URL to your Console UI domain in your MinIO AIStor object store configuration.

Add the environment variable to your aistor-objectstore-values.yaml file:

objectStore:
  name: primary-object-store
  env:
    - name: MINIO_BROWSER_REDIRECT_URL
      value: "https://console.aistor.example.com"

Apply the configuration with Helm:

helm upgrade primary-object-store minio/aistor-objectstore \
  -n primary-object-store \
  -f aistor-objectstore-values.yaml

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

Configure your load balancer or Ingress to route traffic based on URL path:
- / (root path) → Service port 9000 (S3 API)
- /console → Service port 9001 (Console UI)
Obtain your load balancer’s client-facing IP or hostname:

For Kubernetes deployments using LoadBalancer services:
```
kubectl get svc -n primary-object-store
```
For Ingress-based deployments, use your Ingress controller’s external endpoint.

Set MINIO_BROWSER_REDIRECT_URL to your Console UI path in your MinIO AIStor object store configuration.

Add the environment variable to your aistor-objectstore-values.yaml file:

objectStore:
  name: primary-object-store
  env:
    - name: MINIO_BROWSER_REDIRECT_URL
      value: "https://aistor.example.com/console"

Apply the configuration with Helm:

helm upgrade primary-object-store minio/aistor-objectstore \
  -n primary-object-store \
  -f aistor-objectstore-values.yaml

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 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.

Create DNS A or CNAME records pointing to your load balancer’s client-facing IP or hostname:

aistor.example.com → Load balancer IP/hostname (S3 API)
console.aistor.example.com → Load balancer IP/hostname (Console UI)

Create a DNS A or CNAME record pointing to your load balancer’s client-facing IP or hostname:

aistor.example.com → Load balancer IP/hostname

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