Load Balancers

Hubfly load balancers distribute public traffic across multiple container targets behind a single domain or managed endpoint. Use them when one application needs more than one backend container, when traffic should be shared across replicas, or when a stable hostname should stay in front of changing backend services.

Load balancers are part of Hubfly’s production networking layer. They connect project containers, target ports, health checks, balancing algorithms, SSL, edge templates, Hubfly-managed domains, and verified custom domains into one routing group.

Overview

A load balancer group is a project-level routing object. It has one or more container targets, a traffic algorithm, health check settings, and one or more domains that send traffic into the group.

When a domain is attached to a load balancer group, Hubfly creates or updates the proxy configuration for that domain and routes requests to the configured upstream targets. With more than one target, load balancing is enabled automatically.

Load balancers are commonly used for:

• Multiple replicas of the same web service
• Horizontally scaled APIs
• Shared entry points for backend containers
• Blue/green-style target preparation
• Weighted traffic distribution
• Sticky client routing by source IP
• Public custom domains in front of multiple containers
• Production services that need stable routing while containers change

Core Concepts

Use Cases

Use load balancers for horizontal scaling. If an API has three replicas, a load balancer can route api.example.com to all three instead of pointing the domain at one container.

Use load balancers for stable production routing. The domain stays attached to the group while backend containers are added, removed, replaced, or resized.

Use weighted targets for controlled rollout patterns. For example, you can give a new backend a smaller weight while it is being observed, then increase traffic after validation.

Use least_conn when requests are long-lived or connection-heavy and you want the balancer to prefer targets with fewer active connections.

Use ip_hash when client stickiness matters and the same client should generally return to the same backend target.

Avoid load balancers when only one container needs a public hostname. In that case, attach a public endpoint or custom domain directly to the container.

Architecture And Workflow Overview

A production load balancing workflow usually looks like this:

1. Deploy multiple backend containers in the same project.
2. Make sure each target container listens on the expected port.
3. Create a load balancer group.
4. Choose a balancing algorithm.
5. Configure the health check path and interval.
6. Add container targets with ports and optional weights.
7. Attach a Hubfly-managed domain or verified custom domain.
8. Enable SSL and force SSL for production HTTP traffic.
9. Apply edge templates such as security-headers or basic-caching where appropriate.
10. Test the domain and monitor target health, logs, and response behavior.

The load balancer should sit in front of stateless or horizontally safe application containers. Stateful services such as databases, queues, and object stores usually should not be load-balanced this way unless the application is specifically designed for it.

Requirements

Before creating a production load balancer, prepare:

• A Hubfly project with at least one deployed target container
• One or more target containers listening on a known port
• A health check path that returns success when the app is ready
• A selected balancing algorithm
• Target weights if traffic distribution should be uneven
• A Hubfly-managed domain or verified custom domain
• SSL and force SSL settings for public traffic
• A rollback plan for domain or target changes

A group can exist before domains are attached, but a domain should not be attached until at least one target is configured.

Supported Environments

Load balancers are best for HTTP-style application traffic across containers in the same Hubfly project.

Good fits include:

• Multiple replicas of a web app
• Multiple API containers
• Stateless frontend or backend services
• Containers serving the same application version
• Canary or weighted rollout experiments
• Services with a health endpoint such as /health

Less ideal fits include:

• Databases and stateful primary/replica systems without app-level routing support
• Redis or queue services that require protocol-aware clustering
• Single-container apps that do not need traffic distribution
• Targets that do not expose a predictable port
• Backends with inconsistent application versions or incompatible sessions

Create A Load Balancer Group

The load balancer studio uses a staged setup:

1. Group
2. Targets
3. Domains
4. Review

This flow keeps the routing configuration explicit. You define group behavior first, choose targets next, attach domains after targets exist, then review the complete routing setup before applying it.

Group Settings

When creating or editing a group, you can configure:

• Group name
• Description
• Balancing algorithm
• Health check path
• Health check interval
• Active or inactive state

Health check paths should be lightweight and application-aware. Use a route such as /health, /ready, /status, or / only if it accurately represents whether the backend should receive traffic.

Health check intervals should be frequent enough to detect failure but not so aggressive that they create unnecessary load. The supported interval range is designed for operational checks rather than high-frequency probing.

Balancing Algorithms

Available algorithms are:

round_robin

Use round_robin as the default for most stateless web apps and APIs. It is simple, predictable, and works well when all targets have similar capacity.

least_conn

Use least_conn when some requests take longer than others. It can help avoid sending too much new traffic to a backend already holding many active connections.

ip_hash

Use ip_hash when client stickiness matters. This can help with applications that keep session state, local cache, or temporary client-specific data on a backend. For truly production-grade session handling, prefer external shared session storage when possible.

Targets

Targets are backend containers inside the same project. Each target points to a container and a port.

For each target, configure:

• Container
• Port
• Weight

Target ports must match the port where the backend application actually listens. If the container listens on 3000, the target should use 3000. If the app only binds to localhost, the balancer may not be able to reach it; production services should bind to 0.0.0.0 inside the container.

Target weights are integers used for relative traffic distribution. A target with weight 2 can receive more traffic than a target with weight 1 when the algorithm uses weights.

Hubfly prevents removing the last remaining target from a group while domains are attached. This protects public traffic from being routed to an empty backend set.

Domains

A load balancer group can receive traffic through:

• A Hubfly-managed domain
• A verified custom domain

Custom domain attachment supports:

• SSL
• Force SSL
• Edge templates
• Transfer confirmation if the domain is already attached elsewhere

Attach a Hubfly-managed domain for quick testing or preview access. Attach a verified custom domain for production services such as app.example.com, api.example.com, or www.example.com.

Custom Domain Transfer

If a custom domain is already attached to a container or another load balancer, Hubfly asks for transfer confirmation before moving it. Treat transfer as a production routing change because traffic will move from the old target to the new load balancer group.

Before confirming transfer, verify:

• The load balancer has healthy targets
• The target ports are correct
• The SSL and force SSL settings are correct
• The old service no longer needs the domain
• The team expects the routing change

SSL, Force SSL, And Edge Templates

Load balancer domains support SSL and force SSL. Use SSL for production HTTP traffic and force SSL when clients should always use HTTPS.

Edge templates include:

Use security-headers for public services unless the app needs fully custom header behavior.

Use basic-caching only when the response is safe to cache. Avoid basic caching for authenticated dashboards, personalized responses, rapidly changing API data, or sensitive content.

Health Checks

A health check tells the load balancer whether a target should receive traffic. Configure a path and interval that reflect real readiness.

Good health check paths:

/health
/ready
/status

A good health check should verify the app process is ready. For APIs, it may check that required dependencies are reachable. For static apps, a lightweight route may be enough.

Avoid expensive health checks. Do not use endpoints that trigger database writes, external API calls, slow reports, or heavy authentication flows.

Redirects

Load balancer domains can be redirected to another domain where supported by the studio. Redirects are useful when you want one hostname to forward to a canonical hostname or move traffic away from an old domain.

Use redirects carefully:

• The redirect target should be different from the source domain
• HTTPS redirect behavior should match your SSL policy
• Production redirects should be tested before old URLs are published widely
• Avoid redirect loops between domains

Setup Steps

Create A Load Balancer For App Replicas

1. Deploy two or more containers that serve the same app.
2. Confirm each container listens on the same application port.
3. Open the load balancer studio.
4. Create a group with a clear name such as api-production.
5. Choose round_robin for a normal stateless app.
6. Set the health check path, such as /health.
7. Add each container as a target with its listening port.
8. Use equal weights if all targets have similar capacity.
9. Attach a managed domain or verified custom domain.
10. Enable SSL and force SSL.
11. Apply security-headers for public HTTP traffic.
12. Review and create the group.
13. Test the domain and monitor logs on each target.

Add A Target

1. Open the existing load balancer group.
2. Select a target container in the same project.
3. Enter the target port.
4. Set the target weight.
5. Save the target.
6. Confirm health checks pass before relying on the new target for production traffic.

Attach A Custom Domain

1. Verify domain ownership in Hubfly.
2. Open the load balancer group.
3. Attach the verified custom domain.
4. Enable SSL and force SSL for production.
5. Choose edge templates.
6. Confirm transfer if the domain is already attached elsewhere.
7. Wait for proxy and certificate status to settle.
8. Test the domain with realistic traffic.

Perform A Weighted Rollout

1. Add the new backend container as a target.
2. Give the new target a lower weight than stable targets.
3. Watch logs, latency, error rates, and health checks.
4. Increase the new target weight gradually.
5. Remove or reduce old targets when the new version is proven healthy.

Configuration Examples

Simple API Load Balancer

Group: api-production
Algorithm: round_robin
Healthcheck path: /health
Healthcheck interval: 30 seconds
Targets:
  - api-1:3000 weight 1
  - api-2:3000 weight 1
Domain: api.example.com
SSL: enabled
Force SSL: enabled
Edge templates: security-headers

Use this for a normal stateless API with two or more equal replicas.

Connection-Heavy Service

Group: websocket-api
Algorithm: least_conn
Healthcheck path: /health
Targets:
  - realtime-1:8080 weight 1
  - realtime-2:8080 weight 1
Domain: realtime.example.com
SSL: enabled
Force SSL: enabled

Use this when active connection count matters more than simple request sequence.

Sticky Client Routing

Group: session-web
Algorithm: ip_hash
Healthcheck path: /ready
Targets:
  - web-1:3000
  - web-2:3000
Domain: app.example.com
SSL: enabled
Force SSL: enabled

Use this when client affinity is useful. For long-term production reliability, still prefer shared session storage where possible.

CI/CD Integration

Load balancers should be part of the release workflow for horizontally scaled applications.

A practical CI/CD pattern is:

1. Build and test the new application image.
2. Deploy a new container or replica with the new image.
3. Add it to the load balancer at a low weight.
4. Run smoke checks through the load balancer domain.
5. Watch backend logs, status codes, and latency.
6. Increase traffic weight after validation.
7. Remove old targets after the rollout is complete.

For safer releases, avoid changing target containers, domain attachments, SSL settings, and balancing algorithms all in one deployment unless you have a clear rollback path.

Docker And Compose Usage

For single-container deployments, use a normal public endpoint or custom domain unless you need multiple targets.

For Compose deployments, expose only the services that should receive public traffic. If multiple API or web service containers need one hostname, put those target containers behind a load balancer. Keep databases, Redis, queues, and internal services private.

A Compose stack can provide the backend services, while the load balancer handles public routing at the project level.

Example service layout:

Public domain: api.example.com
Load balancer targets:
  - api-1:3000
  - api-2:3000
Private dependencies:
  - postgres:5432
  - redis:6379

Networking Considerations

All targets should be in the same project as the load balancer group. The load balancer routes to container targets by port, so each backend must listen on the configured port.

Use one public domain per externally visible service when possible. Avoid publishing internal services through the load balancer unless they are intended for public traffic.

Use health check paths that represent backend readiness. A process can be running but still unable to serve traffic if it cannot reach its database, cache, or required configuration.

Keep target versions compatible. If a load balancer routes to multiple app versions, make sure they can safely handle the same requests, sessions, database schema, and API contracts.

Security Best Practices

Enable SSL and force SSL for production domains.

Use security-headers for public HTTP services unless your application requires custom header control.

Do not put databases, Redis, queues, or admin-only services behind a public load balancer.

Review custom domain transfers before confirming them. Moving a domain changes live traffic routing.

Use least exposure. If a service does not need public traffic, keep it private and use HubTunnels for maintenance access.

Avoid caching sensitive or personalized responses with basic-caching.

Remove stale targets after rollout. Old targets can continue receiving traffic if they remain in the group.

Scaling Considerations

Load balancers help distribute traffic, but target containers must still have enough CPU, RAM, and application capacity.

Scale horizontally when one container cannot handle traffic alone or when availability benefits from multiple replicas.

Use weights when targets have different capacity. For example, a larger container can receive a higher weight than a smaller one.

Use least_conn for traffic with uneven request duration or long-lived connections.

Use ip_hash when client stickiness matters, but avoid depending on sticky routing as the only session strategy for critical applications.

Scale private dependencies separately. Adding API replicas can increase pressure on PostgreSQL, Redis, object storage, and external APIs.

Performance Notes

Load balancing improves distribution, not application efficiency. Slow code, slow databases, and overloaded dependencies still need direct optimization.

Health checks should be lightweight. Expensive health checks can create unnecessary load on every target.

Weighted routing can help rollout control, but it is not a full feature flag or release management system.

Caching can reduce repeated work for safe content, but incorrect caching can return stale or private data.

Backend containers should serve the same app behavior unless you are intentionally testing a controlled rollout.

Monitoring And Logging

Monitor both the load balancer and the targets.

Watch:

• Domain availability
• SSL and certificate status
• Health check failures
• Target container logs
• HTTP status codes
• Latency and timeout patterns
• Traffic distribution between targets
• Backend CPU and memory usage
• Error rates after adding or removing targets
• Domain transfer or redirect changes

Application logs should include enough context to identify target-specific failures: request ID, target container, route, status code, upstream dependency, and error type.

Troubleshooting

Domain Does Not Route To Targets

Check that the domain is attached to the load balancer group, the group has at least one target, proxy configuration has applied, DNS is correct, and SSL or certificate status is not blocking traffic.

Some Targets Receive No Traffic

Check the balancing algorithm, target weights, target health, and whether the target port is correct. With ip_hash, traffic distribution may not look even because clients are sticky by source IP.

Target Is Marked Unhealthy

Check the health check path, target port, application logs, and whether the app binds to 0.0.0.0. Verify the health route returns success without requiring authentication or heavy dependencies.

Removing A Target Fails

If domains are attached and the group would have no remaining targets, Hubfly prevents removing the last target. Add another target first or detach the domain before removing the final target.

Custom Domain Transfer Warning Appears

The domain is already attached somewhere else. Confirm transfer only if you intend to move live traffic to this load balancer group.

HTTPS Does Not Work

Verify SSL is enabled, DNS points correctly, certificate issuance has completed, and force SSL settings match your expected behavior.

Users See Stale Content

Check whether basic-caching is enabled and whether the application sends cacheable responses. Disable caching for dynamic or personalized traffic.

Common Errors

Best Practices

Use load balancers for horizontally scaled services, not for every single-container app.

Keep backend targets stateless when possible.

Use a real health endpoint such as /health or /ready.

Enable SSL and force SSL on production domains.

Use round_robin for normal stateless traffic, least_conn for long-lived connections, and ip_hash when client affinity matters.

Use weights for controlled rollout and unequal target capacity.

Keep databases and internal services private.

Review domain transfer prompts carefully.

Remove old targets after a rollout is complete.

Production Recommendations

For a production API, create a group with at least two API targets, use round_robin or least_conn, attach api.example.com, enable SSL and force SSL, and configure /health as the health check path.

For a real-time service with long connections, consider least_conn and monitor active connection distribution across targets.

For apps with session affinity requirements, prefer external shared sessions first. Use ip_hash only when client stickiness is acceptable and understood.

For rollout workflows, add the new version as a weighted target, observe it, then gradually increase traffic.

For operational safety, avoid deleting the old target until the new target has passed health checks and real traffic validation.

Limitations

Load balancer targets must be container targets in the same project.

A group needs at least one target before a domain can route useful traffic.

Hubfly prevents removing the last target while domains are attached.

Load balancing does not replace application-level health checks, database scaling, or release testing.

ip_hash prioritizes client stickiness and may not produce even traffic distribution.

Edge caching must be used carefully for dynamic or authenticated content.

FAQ

When Should I Use A Load Balancer?

Use a load balancer when one hostname should route to multiple container targets. For one container, use a normal endpoint or custom domain.

Which Algorithm Should I Choose?

Use round_robin for normal stateless apps, least_conn for long-lived or uneven connections, and ip_hash when client stickiness matters.

Can I Attach A Custom Domain?

Yes. Load balancer groups support verified custom domains with SSL, force SSL, and edge templates.

Can I Use A Hubfly-Managed Domain?

Yes. A managed domain is useful for quick setup, testing, and preview traffic before attaching a custom domain.

Can I Remove All Targets?

Not while domains are attached. Hubfly requires at least one target so public domains do not route to an empty backend set.

Do Load Balancers Replace Auto Scaling?

No. A load balancer routes traffic across targets. You still decide how many targets exist and how each backend is sized.

Should Databases Go Behind A Load Balancer?

Usually no. Databases need database-aware clustering, replication, and failover patterns. Keep databases private unless the database system is explicitly designed for this topology.

Real-World Examples

Production API Replicas

Deploy api-1 and api-2, both listening on port 3000. Create a load balancer group with round_robin, attach api.example.com, enable SSL and force SSL, and use /health for target readiness.

Gradual Release Rollout

Deploy api-v2 next to existing api-v1 targets. Add api-v2 with a lower weight, monitor logs and errors, then increase the weight after validation. Remove api-v1 only after the rollout is stable.

Real-Time App

Deploy multiple real-time service containers on port 8080. Use least_conn so new connections prefer less busy targets. Monitor active connections and target memory usage.

Sticky Dashboard Sessions

Deploy multiple dashboard containers and use ip_hash when clients should generally stay on the same backend. For more robust production behavior, store sessions in Redis or another shared session store.

Related Docs

• Networking
• Platform
• Compose
• HubTunnels
• Deploy From Image
• Deploy From Git