Proxy Configuration & Routing
Relevant source files
The following files were used as context for generating this wiki page:
Kamal utilizes a specialized component called kamal-proxy to manage incoming traffic, facilitate zero-downtime deploys, and handle sophisticated routing logic. The system operates by placing a proxy container on application hosts (per-role) or a dedicated load balancer host, which then routes requests to the appropriate application containers.
The proxy handles SSL termination, health checking, traffic shaping (headers, redirects, rewrites), and access control (IP allow lists and rate limiting). It is deeply integrated into the deployment lifecycle, ensuring that new versions of an application are ready to receive traffic before the proxy switches over and old versions are drained.
Sources: README.md, lib/kamal/configuration.rb:108-112, lib/kamal/cli/main.rb:39-40
Architecture and Components
The proxy architecture is split into two primary modes: per-host proxying and dedicated load balancing. By default, every role designated as a "proxy role" runs its own kamal-proxy instance. If a primary role has multiple hosts, Kamal can auto-enable a load balancer tier.
Core Components
Kamal::Configuration::Proxy: Manages the parsing and validation of proxy-related settings indeploy.yml.Kamal::Cli::Proxy: Provides the CLI interface for booting, rebooting, and managing proxy containers.Kamal::Configuration::Validator::Proxy: Ensures configuration integrity, such as validating IP ranges and ensuring SSL hosts are defined.- Load Balancer: A specialized proxy instance that acts as an edge layer, aggregating traffic across multiple application hosts.
The diagram above illustrates the request flow through either a dedicated load balancer or a direct role-based proxy.
Sources: lib/kamal/configuration.rb:115-125, lib/kamal/configuration/validator/proxy.rb:3-50, lib/kamal/cli/proxy.rb:5-103
Deployment & Lifecycle Management
Proxy management is a critical phase of the kamal deploy and kamal upgrade commands. Before application containers boot, Kamal ensures the proxy is running and updated.
Zero-Downtime Handoff
Kamal supports a "port-holder" architecture for zero-downtime proxy reboots. A holder container (kamal-proxy-net) maintains the network ports while the proxy container is replaced.
- Drain: The existing proxy is instructed to finish active requests via the
kamal-proxy draincommand. - Handoff: A new proxy generation is started, inheriting the network namespace from the holder.
- Promotion: The new container is promoted to the primary
kamal-proxyname.
Config Drift Detection
Kamal calculates a digest of the proxy configuration. During deployment, if the running proxy's digest differs from the current configuration, Kamal triggers an automatic reboot (unless reboot_on_deploy is set to false).
Sources: lib/kamal/cli/proxy.rb:33-65, test/cli/proxy_test.rb:122-140, lib/kamal/commands/proxy.rb:195-215
Traffic Shaping and Routing
The proxy supports advanced HTTP manipulation techniques defined in the proxy: block of the configuration.
Header Manipulation
Rules can be set to set, add, or remove headers for both requests and responses. Headers are encoded as name: value flags passed to the proxy container.
Redirects and Rewrites
- Redirects: Emit HTTP status codes (301, 302, 303, 307, 308) to move clients to new URLs.
- Rewrites: Modify the internal request path before it reaches the application.
| Feature | Key | Parameters |
|---|---|---|
| Redirect | redirects | from, to, status |
| Rewrite | rewrites | from, to |
| Headers | headers | request/response -> set/add/remove |
Traffic shaping logic determines how requests are modified or responded to before hitting the backend.
Sources: test/configuration/proxy/traffic_test.rb:23-50, lib/kamal/configuration/validator/proxy.rb:250-290
Access Control and Security
The proxy provides security layers to protect applications from unauthorized access and excessive traffic.
IP Allow Lists
Users can define allow_ips as a list of CIDR ranges. The proxy will return a 403 Forbidden for any requests originating from IPs outside these ranges.
Rate Limiting
Rate limiting is implemented using a token bucket algorithm.
requests: The number of requests allowed per second.burst: The maximum number of requests allowed to exceed the rate briefly.exempt: CIDR ranges that are not subject to rate limits.
Trusted Proxies
When Kamal is behind another load balancer (e.g., Cloudflare), the client_ip configuration allows defining a header (like CF-Connecting-IP) and trusted_proxies. The proxy will only honor the header if the request comes from a trusted IP.
Sources: test/configuration/proxy/access_control_test.rb:24-60, lib/kamal/configuration/validator/proxy.rb:340-380
SSL and Certificate Management
The proxy handles automatic SSL termination via ACME (Let's Encrypt) or custom certificates.
- Automatic SSL: Requires a
hostorhostsdefinition. It supports SAN cert batching and wildcard certificates via DNS-01 challenges. - On-Demand TLS: Can issue certificates at handshake time by consulting an
askendpoint. - Custom Certificates: Users can provide
certificate_pemandprivate_key_pemvia secrets.
Validation Rules
- SSL is only supported on a single server per role unless custom certificates or a load balancer are configured.
on_demand_urlcannot be combined with statichostdefinitions.
Sources: lib/kamal/configuration/validator/proxy.rb:13-25, lib/kamal/configuration/role.rb:211-215, test/configuration/proxy_test.rb:215-235
Summary
Proxy Configuration & Routing in Kamal provides a robust, container-aware entry point for web applications. By utilizing kamal-proxy, the system achieves zero-downtime deployments through intelligent request draining and handovers. Its configuration-driven approach allows developers to manage complex routing, security, and SSL requirements directly within the deploy.yml file, maintaining infrastructure-as-code principles while ensuring high availability.
Sources: lib/kamal/cli/proxy.rb