Load Balancer Auto-Activation

Relevant source files

The following files were used as context for generating this wiki page:

• lib/kamal/cli/main.rb
• lib/kamal/configuration.rb
• lib/kamal/configuration/validator/proxy.rb
• test/cli/proxy_test.rb
• test/commands/loadbalancer_test.rb
• test/configuration/proxy_test.rb

Load Balancer Auto-Activation in Kamal is a mechanism that automatically provisions and configures a top-level load balancer when a multi-host deployment is detected. This feature ensures that traffic is distributed across multiple application instances without requiring manual infrastructure setup. It leverages kamal-proxy to act as the entry point, routing requests to the kamal-proxy instances running on individual application servers.

The system determines the need for a load balancer based on the primary role's host count. If the primary role (typically web) contains more than one host and no explicit load balancer is configured, Kamal auto-enables this layer to maintain high availability and seamless request switching.

Sources: lib/kamal/cli/main.rb:250-255, test/configuration/proxy_test.rb:69-73

Activation Logic and Triggering

The auto-activation logic is evaluated during the configuration phase. Kamal inspects the proxy configuration block and the host distribution of the primary role.

Automatic Trigger Conditions

A load balancer is automatically enabled if the following conditions are met:

• The primary role (defaulting to web) has two or more hosts.
• The proxy is enabled for that role.
• The user has not explicitly set proxy: loadbalancer: false.

Sources: lib/kamal/configuration.rb:246-248, test/configuration/proxy_test.rb:69-73

Manual Overrides

Users can explicitly control the behavior using the loadbalancer key within the proxy configuration:

Value	Effect
true	Forces activation using the primary role's first host as the LB target.
false	Explicitly disables the load balancer layer regardless of host count.
"hostname"	Designates a specific host (which can be external to the app servers) to act as the LB.

Sources: lib/kamal/configuration/validator/proxy.rb:85-93, test/configuration/proxy_test.rb:75-80

The following diagram illustrates the decision flow for activating the load balancer layer:

Deployment Integration

The load balancer lifecycle is integrated into the standard deployment workflows (setup, deploy, and redeploy).

Deployment Sequence

When load_balancing? returns true, the CLI invokes specialized load balancer commands. During a deploy, the following sequence occurs:

1. Boot Phase: The proxy boot process ensures a container named load-balancer (or kamal-proxy if on a shared host) is running on the designated LB host.
2. Configuration Update: After the application containers are booted, Kamal executes kamal:cli:proxy:loadbalancer deploy.
3. Target Registration: The load balancer is updated with the IPs of all app hosts serving the proxied roles.

Sources: lib/kamal/cli/main.rb:52-55, test/cli/proxy_test.rb:456-460

Multi-Layer Proxy Architecture

In this configuration, requests flow through two layers of kamal-proxy:

1. Edge Layer (Load Balancer): Terminates SSL (if configured at this level), handles session affinity, and routes to backend app hosts.
2. App Layer (Per-Host Proxy): Receives traffic from the LB and switches between the "current" and "new" application containers on the local host.

Sources: test/commands/loadbalancer_test.rb:140-155, test/configuration/proxy_test.rb:225-235

Configuration and Management

The load balancer behaves as a specialized instance of the kamal-proxy. It uses the same image but different runtime flags.

Technical Implementation Details

• Container Naming: Defaults to load-balancer. If the load balancer is assigned to a host already running an application proxy, it reuses the kamal-proxy container name to avoid conflicts.
• Persistent State: Uses a Docker volume named kamal-loadbalancer-config to persist routing information across reboots.
• Image: Uses ghcr.io/mhenrixon/kamal-proxy (or the configured registry).

Sources: test/commands/loadbalancer_test.rb:20-25, test/cli/proxy_test.rb:495-505

Command Reference

The kamal proxy loadbalancer subcommand provides administrative access to the LB layer:

Command	Description
info	Shows the status of the load balancer container.
logs	Retrieves logs from the load balancer.
deploy	Manually pushes current app host targets to the load balancer.
reboot	Restarts the load balancer container to apply proxy/run configuration changes.

Sources: test/cli/proxy_test.rb:410-460

Security and SSL

When auto-activation is triggered, SSL termination typically moves to the edge (Load Balancer). Kamal automatically disables SSL on the individual app-host proxies if a load balancer is detected, preventing "double encryption" and ensuring the LB can handle session affinity and path-based routing effectively.

Sources: lib/kamal/configuration/validator/proxy.rb:10-15, test/configuration/proxy_test.rb:120-125

Conclusion

Load Balancer Auto-Activation simplifies scaling Kamal deployments from single-server to multi-server environments. By automatically detecting the need for a distribution layer and configuring kamal-proxy as a shared entry point, it provides a zero-config path to high-availability web application hosting.