kamal 2.8.2 → 2.10.0

data/lib/kamal/cli/secrets.rb

@@ -12,8 +12,9 @@ class Kamal::Cli::Secrets < Kamal::Cli::Base
     end
 
     results = adapter.fetch(secrets, **options.slice(:account, :from).symbolize_keys)
+    json = JSON.dump(results)
 
-    return_or_puts JSON.dump(results).shellescape, inline: options[:inline]
+    return_or_puts options[:inline] ? json.shellescape : json, inline: options[:inline]
   end
 
   desc "extract", "Extract a single secret from the results of a fetch call"

data/lib/kamal/cli/server.rb

@@ -6,6 +6,7 @@ class Kamal::Cli::Server < Kamal::Cli::Base
 
     cmd = Kamal::Utils.join_commands(cmd)
     hosts = KAMAL.hosts
+    quiet = options[:quiet]
 
     case
     when options[:interactive]
@@ -19,7 +20,7 @@ class Kamal::Cli::Server < Kamal::Cli::Base
 
       on(hosts) do |host|
         execute *KAMAL.auditor.record("Executed cmd '#{cmd}' on #{host}"), verbosity: :debug
-        puts_by_host host, capture_with_info(cmd)
+        puts_by_host host, capture_with_info(cmd), quiet: quiet
       end
     end
   end

data/lib/kamal/cli/templates/secrets

@@ -7,6 +7,7 @@
 
 # Option 2: Read secrets via a command
 # RAILS_MASTER_KEY=$(cat config/master.key)
+# KAMAL_REGISTRY_PASSWORD=$(rails credentials:fetch kamal.registry_password)
 
 # Option 3: Read secrets via kamal secrets helpers
 # These will handle logging in and fetching the secrets in as few calls as possible

data/lib/kamal/commander.rb

@@ -109,8 +109,8 @@ class Kamal::Commander
     @commands[:lock] ||= Kamal::Commands::Lock.new(config)
   end
 
-  def proxy
-    @commands[:proxy] ||= Kamal::Commands::Proxy.new(config)
+  def proxy(host)
+    Kamal::Commands::Proxy.new(config, host: host)
   end
 
   def prune
@@ -155,6 +155,7 @@ class Kamal::Commander
       SSHKit::Backend::Netssh.pool.idle_timeout = config.sshkit.pool_idle_timeout
       SSHKit::Backend::Netssh.configure do |sshkit|
         sshkit.max_concurrent_starts = config.sshkit.max_concurrent_starts
+        sshkit.dns_retries = config.sshkit.dns_retries
         sshkit.ssh_options = config.ssh.options
       end
       SSHKit.config.command_map[:docker] = "docker" # No need to use /usr/bin/env, just clogs up the logs

data/lib/kamal/commands/app/execution.rb

@@ -12,6 +12,7 @@ module Kamal::Commands::App::Execution
       (docker_interactive_args if interactive),
       ("--detach" if detach),
       ("--rm" unless detach),
+      "--name", container_name_for_exec,
       "--network", "kamal",
       *role&.env_args(host),
       *argumentize("--env", env),
@@ -22,11 +23,16 @@ module Kamal::Commands::App::Execution
       *command
   end
 
-  def execute_in_existing_container_over_ssh(*command,  env:)
+  def execute_in_existing_container_over_ssh(*command, env:)
     run_over_ssh execute_in_existing_container(*command, interactive: true, env: env), host: host
   end
 
   def execute_in_new_container_over_ssh(*command, env:)
     run_over_ssh execute_in_new_container(*command, interactive: true, env: env), host: host
   end
+
+  private
+    def container_name_for_exec
+      [ role.container_prefix, "exec", config.version, SecureRandom.hex(3) ].compact.join("-")
+    end
 end

data/lib/kamal/commands/app.rb

@@ -23,7 +23,7 @@ class Kamal::Commands::App < Kamal::Commands::Base
       "--env", "KAMAL_CONTAINER_NAME=\"#{container_name}\"",
       "--env", "KAMAL_VERSION=\"#{config.version}\"",
       "--env", "KAMAL_HOST=\"#{host}\"",
-      "--env", "KAMAL_DESTINATION=\"#{config.destination}\"",
+      *([ "--env", "KAMAL_DESTINATION=\"#{config.destination}\"" ] if config.destination),
       *role.env_args(host),
       *role.logging_args,
       *config.volume_args,

data/lib/kamal/commands/proxy.rb

@@ -1,8 +1,27 @@
 class Kamal::Commands::Proxy < Kamal::Commands::Base
   delegate :argumentize, :optionize, to: Kamal::Utils
+  attr_reader :proxy_run_config
+
+  def initialize(config, host:)
+    super(config)
+    @proxy_run_config = config.proxy_run(host)
+  end
 
   def run
-    pipe boot_config, xargs(docker_run)
+    if proxy_run_config
+      docker \
+        :run,
+        "--name", container_name,
+        "--network", "kamal",
+        "--detach",
+        "--restart", "unless-stopped",
+        "--volume", "kamal-proxy-config:/home/kamal-proxy/.config/kamal-proxy",
+        *proxy_run_config.docker_options_args,
+        *proxy_run_config.image,
+        *proxy_run_config.run_command
+    else
+      pipe boot_config, xargs(docker_run)
+    end
   end
 
   def start
@@ -82,7 +101,7 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
   end
 
   def read_image_version
-    read_file(config.proxy_boot.image_version_file, default: Kamal::Configuration::Proxy::Boot::MINIMUM_VERSION)
+    read_file(config.proxy_boot.image_version_file, default: Kamal::Configuration::Proxy::Run::MINIMUM_VERSION)
   end
 
   def read_run_command

data/lib/kamal/configuration/accessory.rb

@@ -74,25 +74,31 @@ class Kamal::Configuration::Accessory
   end
 
   def files
-    accessory_config["files"]&.to_h do |local_to_remote_mapping|
-      local_file, remote_file = local_to_remote_mapping.split(":")
-      [ expand_local_file(local_file), expand_remote_file(remote_file) ]
+    accessory_config["files"]&.to_h do |config|
+      parse_path_config(config, default_mode: "755") do |local, remote|
+        {
+          key: expand_local_file(local),
+          host_path: expand_remote_file(remote),
+          container_path: remote
+        }
+      end
     end || {}
   end
 
   def directories
-    accessory_config["directories"]&.to_h do |host_to_container_mapping|
-      host_path, container_path = host_to_container_mapping.split(":")
-      [ expand_host_path(host_path), container_path ]
+    accessory_config["directories"]&.to_h do |config|
+      parse_path_config(config, default_mode: nil) do |local, remote|
+        {
+          key: expand_host_path(local),
+          host_path: expand_host_path_for_volume(local),
+          container_path: remote
+        }
+      end
     end || {}
   end
 
-  def volumes
-    specific_volumes + remote_files_as_volumes + remote_directories_as_volumes
-  end
-
   def volume_args
-    argumentize "--volume", volumes
+    (specific_volumes + path_volumes(files) + path_volumes(directories)).flat_map(&:docker_args)
   end
 
   def option_args
@@ -142,17 +148,17 @@ class Kamal::Configuration::Accessory
 
     def expand_local_file(local_file)
       if local_file.end_with?("erb")
-        with_clear_env_loaded { read_dynamic_file(local_file) }
+        with_env_loaded { read_dynamic_file(local_file) }
       else
         Pathname.new(File.expand_path(local_file)).to_s
       end
     end
 
-    def with_clear_env_loaded
-      env.clear.each { |k, v| ENV[k] = v }
+    def with_env_loaded
+      env.to_h.each { |k, v| ENV[k] = v }
       yield
     ensure
-      env.clear.each { |k, v| ENV.delete(k) }
+      env.to_h.each { |k, v| ENV.delete(k) }
     end
 
     def read_dynamic_file(local_file)
@@ -164,27 +170,58 @@ class Kamal::Configuration::Accessory
     end
 
     def specific_volumes
-      accessory_config["volumes"] || []
+      (accessory_config["volumes"] || []).collect do |volume_string|
+        host_path, container_path, options = volume_string.split(":", 3)
+        Kamal::Configuration::Volume.new \
+          host_path: host_path,
+          container_path: container_path,
+          options: options
+      end
     end
 
-    def remote_files_as_volumes
-      accessory_config["files"]&.collect do |local_to_remote_mapping|
-        _, remote_file = local_to_remote_mapping.split(":")
-        "#{service_data_directory + remote_file}:#{remote_file}"
-      end || []
+    def path_volumes(paths)
+      paths.map do |local, config|
+        Kamal::Configuration::Volume.new \
+          host_path: config[:host_path],
+          container_path: config[:container_path],
+          options: config[:options]
+      end
     end
 
-    def remote_directories_as_volumes
-      accessory_config["directories"]&.collect do |host_to_container_mapping|
-        host_path, container_path = host_to_container_mapping.split(":")
-        [ expand_host_path(host_path), container_path ].join(":")
-      end || []
+    def parse_path_config(config, default_mode:)
+      if config.is_a?(Hash)
+        local, remote = config["local"], config["remote"]
+        expanded = yield(local, remote)
+        [
+          expanded[:key],
+          expanded.except(:key).merge(
+            options: config["options"],
+            mode: config["mode"] || default_mode,
+            owner: config["owner"]
+          )
+        ]
+      else
+        local, remote, options = config.split(":", 3)
+        expanded = yield(local, remote)
+        [
+          expanded[:key],
+          expanded.except(:key).merge(
+            options: options,
+            mode: default_mode,
+            owner: nil
+          )
+        ]
+      end
     end
 
     def expand_host_path(host_path)
       absolute_path?(host_path) ? host_path : File.join(service_data_directory, host_path)
     end
 
+    def expand_host_path_for_volume(host_path)
+      absolute_path?(host_path) ? host_path : File.join(service_name, host_path)
+    end
+
     def absolute_path?(path)
       Pathname.new(path).absolute?
     end

data/lib/kamal/configuration/boot.rb

@@ -22,4 +22,8 @@ class Kamal::Configuration::Boot
   def wait
     boot_config["wait"]
   end
+
+  def parallel_roles
+    boot_config["parallel_roles"]
+  end
 end

data/lib/kamal/configuration/builder.rb

@@ -177,8 +177,15 @@ class Kamal::Configuration::Builder
       [ server, cache_image ].compact.join("/")
     end
 
+    def cache_options
+      builder_config["cache"]&.fetch("options", nil)
+    end
+
     def cache_from_config_for_gha
-      "type=gha"
+      individual_options = cache_options&.split(",") || []
+      allowed_options = individual_options.select { |option| option =~ /^(url|url_v2|token|scope|timeout)=/ }
+
+      [ "type=gha", *allowed_options ].compact.join(",")
     end
 
     def cache_from_config_for_registry
@@ -186,11 +193,11 @@ class Kamal::Configuration::Builder
     end
 
     def cache_to_config_for_gha
-      [ "type=gha", builder_config["cache"]&.fetch("options", nil) ].compact.join(",")
+      [ "type=gha", cache_options ].compact.join(",")
     end
 
     def cache_to_config_for_registry
-      [ "type=registry", "ref=#{cache_image_ref}", builder_config["cache"]&.fetch("options", nil) ].compact.join(",")
+      [ "type=registry", "ref=#{cache_image_ref}", cache_options ].compact.join(",")
     end
 
     def repo_basename

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

@@ -90,22 +90,54 @@ accessories:
     # Copying files
     #
     # You can specify files to mount into the container.
-    # The format is `local:remote`, where `local` is the path to the file on the local machine
-    # and `remote` is the path to the file in the container.
     #
     # They will be uploaded from the local repo to the host and then mounted.
-    #
     # ERB files will be evaluated before being copied.
+    #
+    # You can use the string format: `local:remote` or `local:remote:options`
+    # where the options can be `ro` for read-only or `z`/`Z` for SELinux labels
     files:
       - config/my.cnf.erb:/etc/mysql/my.cnf
-      - config/myoptions.cnf:/etc/mysql/myoptions.cnf
+      - config/myoptions.cnf:/etc/mysql/myoptions.cnf:ro
+      - config/certs:/etc/mysql/certs:ro,Z
+    #
+    # Or you can use the hash format for custom mode and ownership.
+    #
+    # Note: Setting `owner` requires root access:
+    files:
+      - local: config/secret.key
+        remote: /etc/mysql/secret.key
+        mode: "0600"
+        owner: "mysql:mysql"
+      - local: config/ca-cert.pem
+        remote: /etc/mysql/certs/ca-cert.pem
+        mode: "0644"
+        owner: "1000:1000"
+        options: "Z"
 
     # Directories
     #
     # You can specify directories to mount into the container. They will be created on the host
-    # before being mounted:
+    # before being mounted.
+    #
+    # You can use the string format: `local:remote` or `local:remote:options`
+    # where the options can be `ro` for read-only or `z`/`Z` for SELinux labels
     directories:
       - mysql-logs:/var/log/mysql
+      - mysql-data:/var/lib/mysql:z
+    #
+    # Or you can use the hash format for custom mode and ownership.
+    #
+    # Note: Setting `owner` requires root access:
+    directories:
+      - local: mysql-data
+        remote: /var/lib/mysql
+        mode: "0750"
+        owner: "mysql:mysql"
+      - local: mysql-logs
+        remote: /var/log/mysql
+        mode: "0755"
+        options: "z"
 
     # Volumes
     #

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

@@ -4,16 +4,18 @@
 #
 # Kamal’s default is to boot new containers on all hosts in parallel. However, you can control this with the boot configuration.
 
-# Fixed group sizes
-#
-# Here, we boot 2 hosts at a time with a 10-second gap between each group:
 boot:
-  limit: 2
-  wait: 10
 
-# Percentage of hosts
-#
-# Here, we boot 25% of the hosts at a time with a 2-second gap between each group:
-boot:
+  # The number or percentage of hosts to boot at a time.
+  # This can be an integer (e.g., 3) or a percentage string (e.g., 25%).
   limit: 25%
-  wait: 2
+
+  # The number of seconds to wait between booting each group of hosts.
+  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.
+  parallel_roles: true

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

@@ -73,7 +73,10 @@ env:
 # This requires that file names change when the contents change
 # (e.g., by including a hash of the contents in the name).
 #
-# To configure this, set the path to the assets:
+# To configure this, set the path to the assets.
+#
+# You can also specify mount options after a colon, such as `ro` for read-only
+# or `z`/`Z` for SELinux labels
 asset_path: /path/to/assets
 
 # Hooks path
@@ -82,6 +85,12 @@ asset_path: /path/to/assets
 # See https://kamal-deploy.org/docs/hooks for more information:
 hooks_path: /user_home/kamal/hooks
 
+# Secrets path
+#
+# Path to secrets, defaults to `.kamal/secrets`.
+# Kamal will look for `<secrets_path>-common` and `<secrets_path>` (or `<secrets_path>.<destination>` when using destinations):
+secrets_path: /user_home/kamal/secrets
+
 # Error pages
 #
 # A directory relative to the app root to find error pages for the proxy to serve.

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

@@ -148,6 +148,30 @@ proxy:
       - X-Request-ID
       - X-Request-Start
 
+  # Run configuration
+  #
+  # These options are used when booting the proxy container.
+  #
+  run:
+    http_port: 8080                # HTTP port to use (default 80)
+    https_port: 8443               # HTTPS port to use (default 443)
+    metrics_port: 9090             # Port for Prometheus metrics
+    debug: true                    # Debug logging (default: false)
+    log_max_size: "30m"            # Maximum log file size (default: "10m")
+    publish: false                 # Publish ports to the host (default: true)
+    bind_ips:                      # List of IPs to bind to when publishing ports
+      - 0.0.0.0
+    registry: registry:4443        # Container registry for the kamal-proxy image
+                                   # (defaults to Docker Hub)
+    repository: myrepo/kamal-proxy # Container repository for the kamal-proxy image
+                                   # (defaults to `basecamp/kamal-proxy`)
+    version: v0.8.0                # Version tag of the kamal-proxy image to use
+    options:                       # Additional options to pass to `docker run`
+      label:
+        - custom.label=kamal-proxy
+      memory: 512m
+      cpus: 0.5
+
 # Enabling/disabling the proxy on roles
 #
 # The proxy is enabled by default on the primary role but can be disabled by

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

@@ -58,13 +58,16 @@ ssh:
 
   # Key data
   #
-  # An array of strings, with each element of the array being
-  # a raw private key in PEM format.
-  key_data: [ "-----BEGIN OPENSSH PRIVATE KEY-----" ]
+  # An array of strings, with each element of the array being a secret name.
+  key_data:
+    - SSH_PRIVATE_KEY
+  # You can also provide raw private key in PEM format, but this is deprecated.
+  key_data:
+    - "-----BEGIN OPENSSH PRIVATE KEY----- ..."
 
   # Config
   #
   # Set to true to load the default OpenSSH config files (~/.ssh/config,
   # /etc/ssh_config), to false ignore config files, or to a file path
   # (or array of paths) to load specific configuration. Defaults to true.
-  config: true
+  config: [ "~/.ssh/myconfig" ]

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

@@ -21,3 +21,11 @@ sshkit:
   # Kamal sets a long idle timeout of 900 seconds on connections to try to avoid
   # re-connection storms after an idle period, such as building an image or waiting for CI.
   pool_idle_timeout: 300
+
+  # DNS retry settings
+  #
+  # Some resolvers (mDNSResponder, systemd-resolved, Tailscale) can drop lookups during
+  # bursts of concurrent SSH starts. Kamal will retry DNS failures automatically.
+  #
+  # Number of retries after the initial attempt. Set to 0 to disable.
+  dns_retries: 3

data/lib/kamal/configuration/env.rb

@@ -1,7 +1,7 @@
 class Kamal::Configuration::Env
   include Kamal::Configuration::Validation
 
-  attr_reader :context, :clear, :secret_keys
+  attr_reader :context, :clear, :secrets, :secret_keys
   delegate :argumentize, to: Kamal::Utils
 
   def initialize(config:, secrets:, context: "env")
@@ -23,12 +23,16 @@ class Kamal::Configuration::Env
   def merge(other)
     self.class.new \
       config: { "clear" => clear.merge(other.clear), "secret" => secret_keys | other.secret_keys },
-      secrets: @secrets
+      secrets: secrets
+  end
+
+  def to_h
+    clear.merge(aliased_secrets)
   end
 
   private
     def aliased_secrets
-      secret_keys.to_h { |key| extract_alias(key) }.transform_values { |secret_key| @secrets[secret_key] }
+      secret_keys.to_h { |key| extract_alias(key) }.transform_values { |secret_key| secrets[secret_key] }
     end
 
     def extract_alias(key)

data/lib/kamal/configuration/proxy/boot.rb

@@ -1,9 +1,4 @@
 class Kamal::Configuration::Proxy::Boot
-  MINIMUM_VERSION = "v0.9.0"
-  DEFAULT_HTTP_PORT = 80
-  DEFAULT_HTTPS_PORT = 443
-  DEFAULT_LOG_MAX_SIZE = "10m"
-
   attr_reader :config
   delegate :argumentize, :optionize, to: Kamal::Utils
 
@@ -16,8 +11,8 @@ class Kamal::Configuration::Proxy::Boot
 
     (bind_ips || [ nil ]).map do |bind_ip|
       bind_ip = format_bind_ip(bind_ip)
-      publish_http = [ bind_ip, http_port, DEFAULT_HTTP_PORT ].compact.join(":")
-      publish_https = [ bind_ip, https_port, DEFAULT_HTTPS_PORT ].compact.join(":")
+      publish_http = [ bind_ip, http_port, Kamal::Configuration::Proxy::Run::DEFAULT_HTTP_PORT ].compact.join(":")
+      publish_https = [ bind_ip, https_port, Kamal::Configuration::Proxy::Run::DEFAULT_HTTPS_PORT ].compact.join(":")
 
       argumentize "--publish", [ publish_http, publish_https ]
     end.join(" ")
@@ -29,8 +24,8 @@ class Kamal::Configuration::Proxy::Boot
 
   def default_boot_options
     [
-      *(publish_args(DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT, nil)),
-      *(logging_args(DEFAULT_LOG_MAX_SIZE))
+      *(publish_args(Kamal::Configuration::Proxy::Run::DEFAULT_HTTP_PORT, Kamal::Configuration::Proxy::Run::DEFAULT_HTTPS_PORT, nil)),
+      *(logging_args(Kamal::Configuration::Proxy::Run::DEFAULT_LOG_MAX_SIZE))
     ]
   end