kamal 2.9.0 → 2.10.0

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/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

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,9 +58,12 @@ 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
   #

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
 

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

@@ -0,0 +1,143 @@
+class Kamal::Configuration::Proxy::Run
+  MINIMUM_VERSION = "v0.9.0"
+  DEFAULT_HTTP_PORT = 80
+  DEFAULT_HTTPS_PORT = 443
+  DEFAULT_LOG_MAX_SIZE = "10m"
+
+  attr_reader :config, :run_config
+  delegate :argumentize, :optionize, to: Kamal::Utils
+
+  def initialize(config, run_config:, context: "proxy/run")
+    @config = config
+    @run_config = run_config
+    @context = context
+  end
+
+  def debug?
+    run_config.fetch("debug", nil)
+  end
+
+  def publish?
+    run_config.fetch("publish", true)
+  end
+
+  def http_port
+    run_config.fetch("http_port", DEFAULT_HTTP_PORT)
+  end
+
+  def https_port
+    run_config.fetch("https_port", DEFAULT_HTTPS_PORT)
+  end
+
+  def bind_ips
+    run_config.fetch("bind_ips", nil)
+  end
+
+  def publish_args
+    if publish?
+      (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(":")
+
+        argumentize "--publish", [ publish_http, publish_https ]
+      end.join(" ")
+    end
+  end
+
+  def log_max_size
+    run_config.fetch("log_max_size", DEFAULT_LOG_MAX_SIZE)
+  end
+
+  def logging_args
+    argumentize "--log-opt", "max-size=#{log_max_size}" if log_max_size.present?
+  end
+
+  def version
+    run_config.fetch("version", MINIMUM_VERSION)
+  end
+
+  def registry
+    run_config.fetch("registry", nil)
+  end
+
+  def repository
+    run_config.fetch("repository", "basecamp/kamal-proxy")
+  end
+
+  def image
+    "#{[ registry, repository ].compact.join("/")}:#{version}"
+  end
+
+  def container_name
+    "kamal-proxy"
+  end
+
+  def options_args
+    if args = run_config["options"]
+      optionize args
+    end
+  end
+
+  def run_command
+    [ "kamal-proxy", "run", *optionize(run_command_options) ].join(" ")
+  end
+
+  def metrics_port
+    run_config["metrics_port"]
+  end
+
+  def run_command_options
+    { debug: debug? || nil, "metrics-port": metrics_port }.compact
+  end
+
+  def docker_options_args
+    [
+      *apps_volume_args,
+      *publish_args,
+      *logging_args,
+      *("--expose=#{metrics_port}" if metrics_port.present?),
+      *options_args
+    ].compact
+  end
+
+  def host_directory
+    File.join config.run_directory, "proxy"
+  end
+
+  def apps_directory
+    File.join host_directory, "apps-config"
+  end
+
+  def apps_container_directory
+    "/home/kamal-proxy/.apps-config"
+  end
+
+  def apps_volume
+    Kamal::Configuration::Volume.new \
+      host_path: apps_directory,
+      container_path: apps_container_directory
+  end
+
+  def apps_volume_args
+    [ apps_volume.docker_args ]
+  end
+
+  def app_directory
+    File.join apps_directory, config.service_and_destination
+  end
+
+  def app_container_directory
+    File.join apps_container_directory, config.service_and_destination
+  end
+
+  private
+    def format_bind_ip(ip)
+      # Ensure IPv6 address inside square brackets - e.g. [::1]
+      if ip =~ Resolv::IPv6::Regex && ip !~ /\A\[.*\]\z/
+        "[#{ip}]"
+      else
+        ip
+      end
+    end
+end

data/lib/kamal/configuration/proxy.rb

@@ -6,8 +6,7 @@ class Kamal::Configuration::Proxy
 
   delegate :argumentize, :optionize, to: Kamal::Utils
 
-  attr_reader :config, :proxy_config, :role_name, :secrets
-
+  attr_reader :config, :proxy_config, :role_name, :run, :secrets
   def initialize(config:, proxy_config:, role_name: nil, secrets:, context: "proxy")
     @config = config
     @proxy_config = proxy_config
@@ -15,6 +14,7 @@ class Kamal::Configuration::Proxy
     @role_name = role_name
     @secrets = secrets
     validate! @proxy_config, with: Kamal::Configuration::Validator::Proxy, context: context
+    @run = Kamal::Configuration::Proxy::Run.new(config, run_config: @proxy_config["run"], context: "#{context}/run") if @proxy_config && @proxy_config["run"].present?
   end
 
   def app_port

data/lib/kamal/configuration/role.rb

@@ -127,7 +127,7 @@ class Kamal::Configuration::Role
 
 
   def asset_path
-    specializations["asset_path"] || config.asset_path
+    asset_path_config&.dig(0)
   end
 
   def assets?
@@ -137,10 +137,14 @@ class Kamal::Configuration::Role
   def asset_volume(version = config.version)
     if assets?
       Kamal::Configuration::Volume.new \
-        host_path: asset_volume_directory(version), container_path: asset_path
+        host_path: asset_volume_directory(version), container_path: asset_path, options: asset_path_options
     end
   end
 
+  def asset_path_options
+    asset_path_config&.dig(1)
+  end
+
   def asset_extracted_directory(version = config.version)
     File.join config.assets_directory, "extracted", [ name, version ].join("-")
   end
@@ -219,4 +223,12 @@ class Kamal::Configuration::Role
         labels.merge!(specializations["labels"]) if specializations["labels"].present?
       end
     end
+
+    def asset_path_config
+      raw_path = specializations["asset_path"] || config.asset_path
+      return nil unless raw_path.present?
+
+      parts = raw_path.split(":", 2)
+      [ parts[0], parts[1] ]
+    end
 end

data/lib/kamal/configuration/ssh.rb

@@ -3,10 +3,11 @@ class Kamal::Configuration::Ssh
 
   include Kamal::Configuration::Validation
 
-  attr_reader :ssh_config
+  attr_reader :ssh_config, :secrets
 
   def initialize(config:)
     @ssh_config = config.raw_config.ssh || {}
+    @secrets = config.secrets
     validate! ssh_config
   end
 
@@ -35,7 +36,17 @@ class Kamal::Configuration::Ssh
   end
 
   def key_data
-    ssh_config["key_data"]
+    key_data = ssh_config["key_data"]
+    return unless key_data
+
+    key_data.map do |k|
+      if secrets.key?(k)
+        secrets[k]
+      else
+        warn "Inline key_data usage is deprecated and will be removed in Kamal 3. Please store your key_data in a secret."
+        k
+      end
+    end
   end
 
   def config

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

@@ -20,6 +20,26 @@ class Kamal::Configuration::Validator::Proxy < Kamal::Configuration::Validator
           error "Missing certificate_pem setting (required when private_key_pem is present)"
         end
       end
+
+      if run_config = config["run"]
+        if run_config["bind_ips"].present?
+          ensure_valid_bind_ips(config["bind_ips"])
+        end
+
+        if run_config["publish"] == false
+          if run_config["bind_ips"].present? || run_config["http_port"].present? || run_config["https_port"].present?
+            error "Cannot set http_port, https_port or bind_ips when publish is false"
+          end
+        end
+      end
     end
   end
+
+  private
+    def ensure_valid_bind_ips(bind_ips)
+      bind_ips.present? && bind_ips.each do |ip|
+        next if ip =~ Resolv::IPv4::Regex || ip =~ Resolv::IPv6::Regex
+        error "Invalid publish IP address: #{ip}"
+      end
+    end
 end

data/lib/kamal/configuration/validator.rb

@@ -36,6 +36,8 @@ class Kamal::Configuration::Validator
                 validate_array_of_or_type! value, example_value.first.class
               elsif key.to_s == "config"
                 validate_ssh_config!(value)
+              elsif key.to_s == "files" || key.to_s == "directories"
+                validate_paths!(value)
               else
                 validate_array_of! value, example_value.first.class
               end
@@ -141,6 +143,24 @@ class Kamal::Configuration::Validator
       end
     end
 
+    def validate_paths!(paths)
+      validate_type! paths, Array
+
+      paths.each_with_index do |path, index|
+        with_context(index) do
+          validate_type! path, String, Hash
+
+          if path.is_a?(Hash)
+            %w[local remote mode owner options].each do |key|
+              with_context(key) do
+                validate_type! path[key], String if path.key?(key)
+              end
+            end
+          end
+        end
+      end
+    end
+
     def validate_type!(value, *types)
       type_error(*types) unless types.any? { |type| valid_type?(value, type) }
     end

data/lib/kamal/configuration/volume.rb

@@ -1,14 +1,21 @@
 class Kamal::Configuration::Volume
-  attr_reader :host_path, :container_path
+  attr_reader :host_path, :container_path, :options
   delegate :argumentize, to: Kamal::Utils
 
-  def initialize(host_path:, container_path:)
+  def initialize(host_path:, container_path:, options: nil)
     @host_path = host_path
     @container_path = container_path
+    @options = options
   end
 
   def docker_args
-    argumentize "--volume", "#{host_path_for_docker_volume}:#{container_path}"
+    argumentize "--volume", docker_args_string
+  end
+
+  def docker_args_string
+    volume_string = "#{host_path_for_docker_volume}:#{container_path}"
+    volume_string += ":#{options}" if options.present?
+    volume_string
   end
 
   private
@@ -16,7 +23,7 @@ class Kamal::Configuration::Volume
       if Pathname.new(host_path).absolute?
         host_path
       else
-        File.join "$(pwd)", host_path
+        "$PWD/#{host_path}"
       end
     end
 end