Deployment Rollout Strategies
Relevant source files
The following files were used as context for generating this wiki page:
Kamal provides several strategies for updating application versions on server clusters, ranging from standard rolling deployments to sophisticated canary rollouts facilitated by kamal-proxy. These strategies ensure service availability while managing the transition between different container versions.
Standard Rolling Deployment
The standard deployment strategy in Kamal involves booting new containers in groups and stopping old ones after the new versions are confirmed healthy. This process is governed by the deploy and redeploy commands.
Deployment Process Flow
The standard deployment logic validates secrets, builds or pulls the application image, ensures the proxy is running, and then boots the application across hosts.
Boot Pacing and Grouping
Kamal can stagger the boot process using limit and wait configurations. This prevents simultaneous downtime across the entire cluster by only updating a subset of hosts at a time.
| Configuration | Description |
|---|---|
boot/limit | The number of hosts to process in a single group (can be integer or percentage). |
boot/wait | The duration to wait (in seconds) between host groups. |
parallel_roles | Boolean determining if different roles (e.g., web, workers) boot simultaneously or sequentially. |
Sources: lib/kamal/configuration.rb:304-308, lib/kamal/cli/app.rb:26-34, test/cli/app_test.rb:39-65
Canary Rollout Strategy
Canary rollouts allow developers to deploy a new version alongside the live version and gradually shift traffic. This is managed via the kamal app rollout command and integrated with kamal-proxy.
Rollout Lifecycle
The rollout strategy consists of three primary actions: deploy, set, and stop.
- Deploy: Boots the new version (the "rollout target") alongside the existing container without stopping the live version.
- Set: Configures the traffic split or specific cookie-based routing for the rollout target.
- Stop: Removes the rollout target and reverts all traffic to the live version.
Traffic Control Options
When a rollout is active, traffic can be directed using the following parameters:
| Parameter | Type | Description |
|---|---|---|
--percent | Numeric | Percentage of random traffic to send to the rollout target. |
--list | Array | List of values to match against the kamal-rollout cookie for targeted routing. |
Sources: lib/kamal/cli/app.rb:271-285, test/cli/app_test.rb:490-505
Readiness Gates and Health Checks
To ensure stability during rollouts, Kamal uses readiness gates. A container is not considered "ready" until it passes health checks, which varies by role type.
Readiness Logic
- Proxied Roles: Rely on
kamal-proxyto determine health via HTTP endpoints. - Unproxied Roles: Use Docker health checks or custom
execprobes. If no check is defined, Kamal waits for areadiness_delay(default 7s) before assuming success.
Rollback Strategy
The rollback strategy allows for an immediate return to a previous version if a deployment fails.
Rollback Requirements
A rollback is only possible if the target version's container is still available on the hosts. The strategy involves:
- Identifying the previous container ID for the requested version.
- Tagging that version's image as
latest. - Booting the container and updating the proxy to point to the old version.
- Stopping the failed version's container.
Sources: lib/kamal/cli/main.rb:83-104, test/cli/app_test.rb:208-228
Summary of Rollout Components
| Component | Responsibility |
|---|---|
Kamal::Cli::App::Boot | Manages the sequence of starting a new container and checking health. |
Kamal::Cli::App::RolloutBoot | Specifically handles side-by-side container execution for canaries. |
kamal-proxy | Dynamically routes traffic between versions based on deployment status. |
Kamal::Cli::Healthcheck::Barrier | Ensures primary roles (usually web) are healthy before proceeding to secondary roles. |
Sources: lib/kamal/cli/app/boot.rb, lib/kamal/cli/app/rollout_boot.rb, lib/kamal/cli/app.rb:15-18