Roles & Server Resolution

Relevant source files

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

• lib/kamal/configuration/role.rb
• lib/kamal/configuration.rb
• lib/kamal/commander.rb
• lib/kamal/commander/specifics.rb
• lib/kamal/configuration/accessory.rb
• lib/kamal/utils.rb

Roles and Server Resolution constitute the core logic for determining which commands execute on which physical or virtual infrastructure. In Kamal, a Role represents a logical grouping of servers running the same application container (e.g., web or workers), while Server Resolution is the process of filtering and prioritizing these hosts based on configuration, command-line arguments, and primary status.

This system ensures that deployments are targeted correctly, whether updating the entire fleet, a single role, or a specific set of hosts. It manages the intersection of roles, accessories, and destinations to create a precise execution plan for SSH-based commands.

Role Configuration and Specialization

Each role in Kamal is defined within the servers block of the configuration. A role encapsulates host lists, specialized environment variables, logging configurations, and healthcheck definitions.

The Role Object

The Kamal::Configuration::Role class manages the attributes for a specific role. It identifies its hosts by parsing the servers configuration, which can be a simple array of IP addresses or a complex mapping of roles to host groups.

Specialized Configurations

Roles can override global settings to provide specialized behavior. These specializations include:

• Environment Variables: Merged from global env, role-specific env, and host-specific tags.
• Logging: Role-specific logging arguments that override global logging defaults.
• Healthchecks: Definitions used to gate the readiness of a container before stopping old versions.
• Proxy Options: Configurations for kamal-proxy, which are mandatory for the primary role and optional for others.

Sources: lib/kamal/configuration/role.rb:16-36, lib/kamal/configuration/role.rb:133-140

Server Resolution Logic

Server resolution is managed primarily by the Kamal::Commander and its Specifics helper. This logic resolves the set of target hosts by intersecting the configured infrastructure with user-provided filters.

Target Filtering

Resolution follows a hierarchy where explicit filters narrow the scope of available hosts and roles.

Primary Host & Role Resolution

Kamal identifies a "Primary" target for operations that should only run once (e.g., interactive consoles or migrations).

• Primary Role: Defaults to web unless specified by primary_role in the configuration.
• Primary Host: The first host listed in the primary role's configuration.
• Resolution Priority: If specific roles or hosts are provided via the CLI, the primary host is re-calculated to be the first host within that narrowed scope.

Sources: lib/kamal/configuration.rb:183-193, lib/kamal/commander/specifics.rb:10-12

Host Resolution for Accessories

Accessories (like databases or caches) have a distinct resolution path compared to application roles. They can define their hosts through multiple keys:

Key	Resolution Strategy
host	A single specific host string.
hosts	An array of specific host strings.
role/roles	Resolves to all hosts currently assigned to the named application roles.
tag/tags	Resolves to hosts within application roles that carry specific tags in the servers config.

Sources: lib/kamal/configuration/accessory.rb:39-66

Execution Order and Pacing

The resolution process also determines the order of execution. Kamal ensures that the primary role and its hosts are prioritized.

Boot Groups

During application booting, hosts are sliced into groups based on the boot/limit configuration. Resolution logic ensures that if parallel_roles is false, Kamal iterates host-first (all roles on one host, then the next). If true, it iterates role-first (one role across all its hosts, then the next role).

Sources: lib/kamal/configuration.rb:162-165, lib/kamal/cli/app.rb:453-458

Summary of Resolution Parameters

Component	Responsibility	Relevant Files
Kamal::Configuration	Loads raw YAML and initializes Role and Accessory objects.	configuration.rb
Kamal::Commander	Holds the singleton state for the current execution (specific hosts/roles).	commander.rb
Kamal::Commander::Specifics	Performs the set logic to intersect config with CLI filters.	commander/specifics.rb
Kamal::Configuration::Role	Handles host-to-tag mapping and role-level specializations.	configuration/role.rb
Kamal::Utils	Provides filter_specific_items using File.fnmatch for wildcards.	utils.rb

Role and server resolution provides the necessary precision to manage complex deployments by bridging the gap between static configuration files and dynamic operational requirements. By utilizing roles as the primary unit of organization, Kamal allows for both granular control over specific hosts and high-level orchestration of entire service tiers.

Sources: lib/kamal/commander.rb:53-73, lib/kamal/configuration.rb:142-160