dash 2.12.0 → 3.0.1

data/lib/kamal/commands/loadbalancer.rb

@@ -9,17 +9,18 @@ class Kamal::Commands::Loadbalancer < Kamal::Commands::Base
   end
 
   def run
-    pipe \
-      [ :echo, proxy_image ],
-      xargs(docker(:run,
-        "--name", container_name,
-        "--network", "kamal",
-        "--detach",
-        "--restart", "unless-stopped",
-        "--publish", "80:80",
-        "--publish", "443:443",
-        "--label", label,
-        *volume_mounts))
+    docker \
+      :run,
+      "--name", container_name,
+      "--network", "kamal",
+      "--detach",
+      "--restart", "unless-stopped",
+      "--label", label,
+      "--label", "#{Kamal::Commands::Proxy::CONFIG_DIGEST_LABEL}=#{loadbalancer_config.run_config_digest}",
+      *config_volume,
+      *run_args,
+      *loadbalancer_config.run.image,
+      *loadbalancer_config.run.run_command
   end
 
   def start
@@ -35,16 +36,35 @@ class Kamal::Commands::Loadbalancer < Kamal::Commands::Base
   end
 
   def deploy(targets: [])
-    target_args = targets.map { |t| "#{t}:80" }
+    docker :exec, container_name, "kamal-proxy", "deploy", loadbalancer_config.config.service,
+      *loadbalancer_config.deploy_command_args(targets: targets)
+  end
+
+  def domains(subcommand)
+    docker :exec, container_name, "kamal-proxy", "domains", subcommand
+  end
+
+  def list(json: false)
+    docker :exec, container_name, "kamal-proxy", :list, *("--json" if json)
+  end
 
-    hosts = loadbalancer_config.hosts
+  # Cache policy is edge-only under load balancing (see the layering contract),
+  # so the cache admin surface lives here - registered under the bare service
+  # name, unlike the per-role services on the proxy hosts.
+  def cache_stats(count: false, json: false)
+    docker :exec, container_name, "kamal-proxy", :cache, :stats, *optionize({ count: count || nil, json: json || nil }.compact)
+  end
 
-    options = []
-    options << "--target=#{target_args.join(',')}"
-    options << "--host=#{hosts.join(',')}"
-    options << "--tls" if loadbalancer_config.ssl?
+  def cache_purge(service, path_prefix: nil)
+    docker :exec, container_name, "kamal-proxy", :cache, :purge, service, *optionize({ "path-prefix": path_prefix }.compact)
+  end
+
+  def config_digest
+    docker :inspect, container_name, "--format", "'{{ index .Config.Labels \"#{Kamal::Commands::Proxy::CONFIG_DIGEST_LABEL}\" }}'"
+  end
 
-    docker :exec, container_name, "kamal-proxy", "deploy", loadbalancer_config.config.service, *options
+  def container_id
+    container_id_for(container_name: container_name)
   end
 
   def info
@@ -70,22 +90,49 @@ class Kamal::Commands::Loadbalancer < Kamal::Commands::Base
     ).join(" "), host: host
   end
 
+  # Prune by the label the container was actually created with - on a shared
+  # proxy host that is the kamal-proxy title, and pruning by the loadbalancer
+  # title would leave the container behind for `run` to collide with.
   def remove_container
-    docker :container, :prune, "--force", "--filter", "label=org.opencontainers.image.title=kamal-loadbalancer"
+    docker :container, :prune, "--force", "--filter", "label=#{label}"
   end
 
+  # Image label filters match labels baked into the image, and the load balancer
+  # runs the kamal-proxy image whichever host it sits on.
   def remove_image
-    docker :image, :prune, "--all", "--force", "--filter", "label=org.opencontainers.image.title=kamal-loadbalancer"
+    docker :image, :prune, "--all", "--force", "--filter", "label=org.opencontainers.image.title=kamal-proxy"
   end
 
   def ensure_directory
     make_directory loadbalancer_config.directory
   end
 
+  # Where the proxy secrets env file lands (see Proxy::Run#secrets_path) -
+  # the same .kamal/proxy directory the per-app proxy hosts use.
+  def ensure_proxy_directory
+    make_directory loadbalancer_config.run.host_directory
+  end
+
+  def remove_proxy_secrets_file
+    remove_file loadbalancer_config.run.secrets_path
+  end
+
   def ensure_apps_config_directory
     make_directory config.proxy_boot.apps_directory
   end
 
+  def ensure_services_directory
+    make_directory loadbalancer_config.services_directory
+  end
+
+  def read_service_owner
+    read_file loadbalancer_config.service_owner_file
+  end
+
+  def read_run_config_record
+    read_file loadbalancer_config.run_config_file
+  end
+
   def remove_directory
     super(loadbalancer_config.directory)
   end
@@ -95,11 +142,8 @@ class Kamal::Commands::Loadbalancer < Kamal::Commands::Base
   end
 
   private
-    def proxy_image
-      [
-        loadbalancer_config.config.proxy_boot.image_default,
-        Kamal::Configuration::Proxy::Run::MINIMUM_VERSION
-      ].join(":")
+    def run_args
+      loadbalancer_config.run_args
     end
 
     def on_proxy_host?
@@ -114,17 +158,15 @@ class Kamal::Commands::Loadbalancer < Kamal::Commands::Base
       end
     end
 
-    def volume_mounts
+    # kamal-proxy keeps its state under /home/kamal-proxy/.config/kamal-proxy
+    # whichever host it runs on - only the volume name differs, so a dedicated
+    # load balancer and a shared proxy host never fight over the same volume.
+    # (The apps-config mount comes with run_args, via the proxy's run surface.)
+    def config_volume
       if on_proxy_host?
-        # When on a proxy host, use same volume mounts as proxy for app deployments
-        [
-          "--volume", "kamal-proxy-config:/home/kamal-proxy/.config/kamal-proxy",
-          "--volume", "$PWD/#{config.proxy_boot.apps_directory}:/home/kamal-proxy/.apps-config"
-        ]
+        [ "--volume", "kamal-proxy-config:/home/kamal-proxy/.config/kamal-proxy" ]
       else
-        [
-          "--volume", "kamal-loadbalancer-config:/home/kamal-loadbalancer/.config/kamal-loadbalancer"
-        ]
+        [ "--volume", "kamal-loadbalancer-config:/home/kamal-proxy/.config/kamal-proxy" ]
       end
     end
 end

data/lib/kamal/commands/proxy.rb

@@ -2,25 +2,28 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
   delegate :argumentize, :optionize, to: Kamal::Utils
   attr_reader :proxy_run_config
 
+  CONFIG_DIGEST_LABEL = "org.kamal.proxy-config-digest"
+
   def initialize(config, host:)
     super(config)
     @proxy_run_config = config.proxy_run(host)
   end
 
-  def run
+  def run(digest: nil, name: nil)
     if proxy_run_config
       docker \
         :run,
-        "--name", container_name,
-        "--network", "kamal",
+        "--name", name || container_name,
+        *proxy_run_config.network_args,
         "--detach",
         "--restart", "unless-stopped",
         "--volume", "kamal-proxy-config:/home/kamal-proxy/.config/kamal-proxy",
+        *config_digest_label_args(digest),
         *proxy_run_config.docker_options_args,
         *proxy_run_config.image,
         *proxy_run_config.run_command
     else
-      pipe boot_config, xargs(docker_run)
+      pipe boot_config, xargs(docker_run(digest: digest))
     end
   end
 
@@ -28,12 +31,12 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
     docker :container, :start, container_name
   end
 
-  def stop(name: container_name)
-    docker :container, :stop, name
+  def stop(name: container_name, timeout: nil)
+    docker :container, :stop, *("--time #{timeout}" if timeout), name
   end
 
-  def start_or_run
-    combine start, run, by: "||"
+  def start_or_run(digest: nil)
+    combine start, run(digest: digest), by: "||"
   end
 
   def info
@@ -46,6 +49,92 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
       [ :awk, "-F:", "'{print \$NF}'" ]
   end
 
+  def config_digest
+    docker :inspect, container_name, "--format", "'{{ index .Config.Labels \"#{CONFIG_DIGEST_LABEL}\" }}'"
+  end
+
+  def container_id(only_running: false)
+    container_id_for(container_name: container_name, only_running: only_running)
+  end
+
+  def pull
+    if proxy_run_config
+      docker :pull, proxy_run_config.image
+    else
+      docker :pull, "#{substitute(read_image)}:#{substitute(read_image_version)}"
+    end
+  end
+
+  def list(name: container_name, json: false)
+    docker :exec, name, "kamal-proxy", :list, *("--json" if json)
+  end
+
+  def cache_stats(count: false, json: false)
+    docker :exec, container_name, "kamal-proxy", :cache, :stats, *optionize({ count: count || nil, json: json || nil }.compact)
+  end
+
+  def cache_purge(service, path_prefix: nil)
+    docker :exec, container_name, "kamal-proxy", :cache, :purge, service, *optionize({ "path-prefix": path_prefix }.compact)
+  end
+
+  # One mount destination per line - what the running container was actually
+  # booted with, as opposed to what the current configuration would mount.
+  def mount_destinations
+    docker :inspect, container_name, "--format", "'{{range .Mounts}}{{println .Destination}}{{end}}'"
+  end
+
+  # Zero-downtime handoff commands (proxy/run port_holder mode)
+
+  def port_holder?
+    proxy_run_config&.port_holder? || false
+  end
+
+  def next_container_name
+    "#{container_name}-next"
+  end
+
+  def run_holder
+    docker \
+      :run,
+      "--name", proxy_run_config.holder_container_name,
+      "--network", "kamal",
+      "--detach",
+      "--restart", "unless-stopped",
+      *proxy_run_config.holder_docker_args,
+      *proxy_run_config.image,
+      "kamal-proxy", "hold"
+  end
+
+  def start_holder_or_run
+    combine docker(:container, :start, proxy_run_config.holder_container_name), run_holder, by: "||"
+  end
+
+  def holder_container_id
+    container_id_for(container_name: proxy_run_config.holder_container_name, only_running: true)
+  end
+
+  # Cancel the restart policy before draining: drain makes the proxy exit on
+  # its own, which - unlike `docker stop` - an active restart policy would undo.
+  def disable_restart
+    docker :update, "--restart=no", container_name
+  end
+
+  def drain(timeout: nil)
+    docker :exec, container_name, "kamal-proxy", :drain, *("--drain-timeout=#{timeout}s" if timeout)
+  end
+
+  def wait_for_exit(name: container_name)
+    docker :wait, name
+  end
+
+  def remove_stopped_container(name: container_name)
+    docker :container, :rm, name
+  end
+
+  def promote_next_container
+    docker :container, :rename, next_container_name, container_name
+  end
+
   def logs(timestamps: true, since: nil, lines: nil, grep: nil, grep_options: nil)
     pipe \
       docker(:logs, container_name, ("--since #{since}" if since), ("--tail #{lines}" if lines), ("--timestamps" if timestamps), "2>&1"),
@@ -59,6 +148,10 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
     ).join(" "), host: host
   end
 
+  def domains(subcommand)
+    docker :exec, container_name, "kamal-proxy", "domains", subcommand
+  end
+
   def remove_container
     docker :container, :prune, "--force", "--filter", "label=org.opencontainers.image.title=kamal-proxy"
   end
@@ -88,6 +181,12 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
     make_directory config.proxy_boot.apps_directory
   end
 
+  # Static path rather than proxy_run_config.secrets_path: the file must be
+  # removable precisely when the run config (or its secrets) is gone.
+  def remove_proxy_secrets_file
+    remove_file File.join(config.proxy_boot.host_directory, Kamal::Configuration::Proxy::Run::SECRETS_FILENAME)
+  end
+
   def boot_config
     [ :echo, "#{substitute(read_boot_options)} #{substitute(read_image)}:#{substitute(read_image_version)} #{substitute(read_run_command)}" ]
   end
@@ -133,11 +232,11 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
       config.proxy_boot.container_name
     end
 
-    def read_file(file, default: nil)
-      combine [ :cat, file, "2>", "/dev/null" ], [ :echo, "\"#{default}\"" ], by: "||"
+    def config_digest_label_args(digest)
+      [ "--label", "#{CONFIG_DIGEST_LABEL}=#{digest}" ] if digest
     end
 
-    def docker_run
+    def docker_run(digest: nil)
       docker \
         :run,
         "--name", container_name,
@@ -145,6 +244,7 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
         "--detach",
         "--restart", "unless-stopped",
         "--volume", "kamal-proxy-config:/home/kamal-proxy/.config/kamal-proxy",
+        *config_digest_label_args(digest),
         *config.proxy_boot.apps_volume.docker_args
     end
 end

data/lib/kamal/commands/prune.rb

@@ -13,9 +13,15 @@ class Kamal::Commands::Prune < Kamal::Commands::Base
       "while read image tag; do docker rmi $tag; done"
   end
 
-  def app_containers(retain:)
+  # Scoped to one role so a busy sibling role cannot push another role's newest
+  # container past the retain window. That matters beyond disk hygiene: a
+  # container kamal-proxy has put to sleep is `exited`, so it is a removal
+  # candidate, and once it is gone every wake 404s. With `retain >= 1` a role's
+  # newest container always survives, and the slept one is always the newest —
+  # sleeping happens to the current release.
+  def app_containers(retain:, role:)
     pipe \
-      docker(:ps, "-q", "-a", *service_filter, *stopped_containers_filters),
+      docker(:ps, "-q", "-a", *service_filter, *destination_filter, *role_filter(role), *stopped_containers_filters),
       "tail -n +#{retain + 1}",
       "while read container_id; do docker rm $container_id; done"
   end
@@ -35,4 +41,12 @@ class Kamal::Commands::Prune < Kamal::Commands::Base
     def service_filter
       [ "--filter", "label=service=#{config.service}" ]
     end
+
+    def destination_filter
+      [ "--filter", "label=destination=#{config.destination}" ]
+    end
+
+    def role_filter(role)
+      [ "--filter", "label=role=#{role}" ]
+    end
 end

data/lib/kamal/commands/server.rb

@@ -12,4 +12,9 @@ class Kamal::Commands::Server < Kamal::Commands::Base
       [ :ls, config.apps_directory ],
       [ :wc, "-l" ]
   end
+
+  # Lists TCP listeners on the given port, one line per listener, no header.
+  def listeners_on(port)
+    [ :ss, "-ltnH", :sport, "=", ":#{port}" ]
+  end
 end

data/lib/kamal/configuration/accessory.rb

@@ -127,12 +127,16 @@ class Kamal::Configuration::Accessory
         context: "accessories/#{name}/env"
     end
 
+    # The load balancer fans the app's own service out to role targets only
+    # (see Kamal::Cli::Proxy#loadbalancer), so an accessory is never behind it
+    # and must keep the host/TLS it registers with kamal-proxy directly.
     def initialize_proxy
       Kamal::Configuration::Proxy.new \
         config: config,
         proxy_config: accessory_config["proxy"],
         context: "accessories/#{name}/proxy",
-        secrets: config.secrets
+        secrets: config.secrets,
+        load_balanced: false
     end
 
     def initialize_registry
@@ -256,14 +260,11 @@ class Kamal::Configuration::Accessory
       end
     end
 
+    # Ask each role for its own tagged hosts instead of re-parsing raw_config.servers here:
+    # a role may be written as a bare list or as a `hosts:` mapping, and Role already reads
+    # both. A second parser with a shape assumption dropped tagged hosts silently.
     def extract_hosts_from_config_with_tag(tag)
-      if (servers_with_roles = config.raw_config.servers).is_a?(Hash)
-        servers_with_roles.flat_map do |role, servers_in_role|
-          servers_in_role.filter_map do |host|
-            host.keys.first if host.is_a?(Hash) && host.values.first.include?(tag)
-          end
-        end
-      end
+      config.roles.flat_map { |role| role.hosts_with_tag(tag) }
     end
 
     def network

data/lib/kamal/configuration/boot.rb

@@ -1,24 +1,36 @@
 class Kamal::Configuration::Boot
   include Kamal::Configuration::Validation
 
-  attr_reader :boot_config, :host_count
+  attr_reader :boot_config
 
-  def initialize(config:)
-    @boot_config = config.raw_config.boot || {}
-    @host_count = config.all_hosts.count
-    validate! boot_config
+  # Pass boot_config/context to scope this to a single role: the role's own `boot:` hash,
+  # and a context that points at the role in validation errors.
+  def initialize(config:, boot_config: nil, context: nil)
+    @boot_config = boot_config || config.raw_config.boot || {}
+    validate! @boot_config, context: context
   end
 
-  def limit
+  # The group size to slice `hosts` by. A percentage only means something against the set
+  # it will actually be applied to, and that set is not known until run time — `--roles`
+  # and `--hosts` narrow it, and accessories are never booted at all. So callers pass the
+  # hosts they are about to group rather than Boot reaching for a host list of its own.
+  def limit_for(hosts)
     limit = boot_config["limit"]
 
     if limit.to_s.end_with?("%")
-      [ host_count * limit.to_i / 100, 1 ].max
+      [ hosts.count * limit.to_i / 100, 1 ].max
     else
       limit
     end
   end
 
+  # Whether a limit is configured at all. Deliberately not a reader for the raw value:
+  # a percentage means nothing without the hosts it slices, so anything that needs the
+  # group size has to go through limit_for.
+  def limit?
+    boot_config["limit"].present?
+  end
+
   def wait
     boot_config["wait"]
   end
@@ -26,4 +38,23 @@ class Kamal::Configuration::Boot
   def parallel_roles
     boot_config["parallel_roles"]
   end
+
+  # SSHKit runner options expressing this pacing over `hosts`. Without a limit there is
+  # nothing to pace and `on` keeps its default parallel runner.
+  #
+  # `wait` is always explicit: SSHKit::Runner::Sequential and ::Group both fall back to a
+  # 2 second interval, where Kamal's own boot wait means "no sleep unless you asked for
+  # one". A limit of 1 goes through Sequential rather than Group, which runs one host per
+  # slice without spawning a thread to do it. Neither trails a wait past the last group —
+  # Sequential pops its final host, and Kamal patches Group to match (sshkit_with_ext.rb).
+  def runner_options_for(hosts)
+    limit = limit_for(hosts)
+    return {} unless limit
+
+    if limit == 1
+      { in: :sequence, wait: wait.to_i }
+    else
+      { in: :groups, limit: limit, wait: wait.to_i }
+    end
+  end
 end

data/lib/kamal/configuration/docs/accessory.yml

@@ -155,6 +155,33 @@ accessories:
 
     # Proxy
     #
-    # You can run your accessory behind the Kamal proxy. See kamal docs proxy for more information
+    # You can run your accessory behind the Kamal proxy for hostname-based
+    # routing and automatic SSL. The block accepts the same schema as the
+    # app-level `proxy:` (see `kamal docs proxy`), though root-only keys such as
+    # `loadbalancer` and `reboot_on_deploy` have no effect inside an accessory.
+    # Declaring a proxy here makes the accessory's hosts proxy hosts:
+    # `kamal proxy boot` (and `kamal deploy`) will run kamal-proxy on them
+    # automatically.
+    #
+    # Accessories are never load balanced. The loadbalancer fans the app's own
+    # service out to its role targets, so an accessory always registers its
+    # hostname and TLS with the kamal-proxy on its own host — whether or not the
+    # loadbalancer is active for the app. Point the accessory's DNS record at the
+    # accessory host, not at the loadbalancer.
+    #
+    # One caveat: accessory restarts are stop-then-start (no old/new container
+    # overlap), so expect a brief interruption when restarting or rebooting.
+    #
+    # For example:
+    #
+    #   proxy:
+    #     host: mysql-admin.example.com   # Route this hostname to the accessory
+    #     ssl: true                       # Terminate SSL with a Let's Encrypt cert
+    #     app_port: 8080                  # Container port the accessory listens on (default: 80)
+    #     healthcheck:
+    #       path: /health                 # Health check endpoint (default: /up)
+    #
+    # The `...` below is a placeholder: accessory proxy configuration accepts the
+    # full proxy schema and is validated against it when the accessory is loaded.
     proxy:
       ...

data/lib/kamal/configuration/docs/boot.yml

@@ -3,19 +3,34 @@
 # When deploying to large numbers of hosts, you might prefer not to restart your services on every host at the same time.
 #
 # Kamal’s default is to boot new containers on all hosts in parallel. However, you can control this with the boot configuration.
+#
+# This is a whole-deploy setting: `limit` slices the combined host list of every role, so it cannot
+# hold one role back while another keeps booting. To pace a single role's hosts, set `boot` on that
+# role instead (see kamal docs role).
 
 boot:
 
-  # The number or percentage of hosts to boot at a time.
+  # The number or percentage of hosts to boot at a time, across all roles.
   # This can be an integer (e.g., 3) or a percentage string (e.g., 25%).
+  #
+  # A percentage counts the hosts this run is actually booting: app hosts only — accessories
+  # are not booted here — and narrowed by `--roles` / `--hosts`. So `25%` with `--roles web`
+  # is a quarter of web's hosts, not a quarter of the file.
   limit: 25%
 
   # The number of seconds to wait between booting each group of hosts.
+  #
+  # This fills the gap between one group and the next, so it needs `limit` to mean anything:
+  # without one, every host boots in a single group and there is no gap to fill. Kamal warns
+  # if you set `wait` on its own. Nothing waits after the final group either — the deploy
+  # moves on as soon as the last host is up.
   wait: 10
 
   # Whether to boot roles in parallel on a host.
   #
   # If a host has multiple roles, control whether they are booted in parallel or sequentially on that host.
   #
-  # Defaults to false.
+  # Defaults to false. A role that sets its own `boot` needs this on, since per-role pacing has no
+  # meaning when each host walks its roles in turn — Kamal turns it on for you if you have not set
+  # it, and refuses the deploy if you set it to false.
   parallel_roles: true

data/lib/kamal/configuration/docs/configuration.yml

@@ -136,7 +136,8 @@ allow_empty_roles: false
 
 # Retain containers
 #
-# How many old containers and images we retain, defaults to 5:
+# How many old containers we retain per role, and how many images we retain,
+# defaults to 5:
 retain_containers: 3
 
 # Minimum version