kamal 2.11.0 → 2.12.0

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

@@ -0,0 +1,25 @@
+# Output
+#
+# Configure where Kamal sends command output logs.
+
+# Output options
+#
+# The options are specified under the output key in the configuration file.
+output:
+
+  # OTel
+  #
+  # Ship deploy logs to an OpenTelemetry-compatible endpoint via OTLP HTTP.
+  #
+  # Logs are sent as OTLP log records with resource attributes derived from
+  # Kamal's deploy tags (service, version, performer, destination, etc.)
+  otel:
+    endpoint: http://otel-gateway:4318
+
+  # File
+  #
+  # Write deploy logs to a file on the local machine.
+  #
+  # One log file is created per deploy, named with the timestamp and command.
+  file:
+    path: /var/log/kamal/

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

@@ -39,6 +39,7 @@ servers:
       - 172.1.0.3
       - 172.1.0.4: experiment1
     cmd: "bin/jobs"
+    stop_timeout: 30
     options:
       memory: 2g
       cpus: 4

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

@@ -71,3 +71,11 @@ ssh:
   # /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: [ "~/.ssh/myconfig" ]
+
+  # Forward agent
+  #
+  # Whether to forward the local SSH agent to the remote host. Defaults to
+  # true (sshkit's default). Set to false when connecting through a jump
+  # host or tunnel that does not support agent forwarding (for example,
+  # Cloudflare Access for Infrastructure with SSH).
+  forward_agent: false

data/lib/kamal/configuration/output.rb

@@ -0,0 +1,34 @@
+class Kamal::Configuration::Output
+  include Kamal::Configuration::Validation
+
+  LOGGER_TYPES = {
+    "otel" => "Kamal::Output::OtelLogger",
+    "file" => "Kamal::Output::FileLogger"
+  }
+
+  attr_reader :output_config, :loggers
+
+  def initialize(config:)
+    @config = config
+    @output_config = config.raw_config.output || {}
+    validate! @output_config unless @output_config.empty?
+    @loggers = build_loggers
+  end
+
+  def enabled?
+    output_config.present?
+  end
+
+  def to_h
+    output_config
+  end
+
+  private
+    def build_loggers
+      output_config.filter_map do |key, settings|
+        if (klass_name = LOGGER_TYPES[key])
+          klass_name.constantize.build(settings: settings || {}, config: @config)
+        end
+      end
+    end
+end

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

@@ -131,6 +131,15 @@ class Kamal::Configuration::Proxy::Run
     File.join apps_container_directory, config.service_and_destination
   end
 
+  def ==(other)
+    other.is_a?(self.class) && run_config == other.run_config
+  end
+  alias_method :eql?, :==
+
+  def hash
+    run_config.hash
+  end
+
   private
     def format_bind_ip(ip)
       # Ensure IPv6 address inside square brackets - e.g. [::1]

data/lib/kamal/configuration/role.rb

@@ -44,11 +44,11 @@ class Kamal::Configuration::Role
   end
 
   def option_args
-    if args = specializations["options"]
-      optionize args
-    else
-      []
-    end
+    optionize docker_options.reject { |key, _| key.to_s == "restart" }
+  end
+
+  def restart_policy
+    restart_policy_option || "unless-stopped"
   end
 
   def labels
@@ -81,11 +81,15 @@ class Kamal::Configuration::Role
 
   def stop_args
     # When deploying with the proxy, kamal-proxy will drain request before returning so we don't need to wait.
-    timeout = running_proxy? ? nil : config.drain_timeout
+    timeout = stop_timeout || (running_proxy? ? nil : config.drain_timeout)
 
     [ *argumentize("-t", timeout) ]
   end
 
+  def stop_timeout
+    specializations["stop_timeout"] || config.stop_timeout
+  end
+
   def env(host)
     @envs ||= {}
     @envs[host] ||= [ config.env, specialized_env, *env_tags(host).map(&:env) ].reduce(:merge)
@@ -217,6 +221,14 @@ class Kamal::Configuration::Role
       @role_config ||= config.raw_config.servers.is_a?(Array) ? {} : config.raw_config.servers[name]
     end
 
+    def docker_options
+      specializations["options"] || {}
+    end
+
+    def restart_policy_option
+      docker_options.find { |key, _| key.to_s == "restart" }&.last
+    end
+
     def custom_labels
       Hash.new.tap do |labels|
         labels.merge!(config.labels) if config.labels.present?

data/lib/kamal/configuration/ssh.rb

@@ -53,8 +53,12 @@ class Kamal::Configuration::Ssh
     ssh_config["config"]
   end
 
+  def forward_agent
+    ssh_config["forward_agent"]
+  end
+
   def options
-    { user: user, port: port, proxy: proxy, logger: logger, keepalive: true, keepalive_interval: 30, keys_only: keys_only, keys: keys, key_data: key_data, config: config  }.compact
+    { user: user, port: port, proxy: proxy, logger: logger, keepalive: true, keepalive_interval: 30, keys_only: keys_only, keys: keys, key_data: key_data, config: config, forward_agent: forward_agent }.compact
   end
 
   def to_h

data/lib/kamal/configuration/validator.rb

@@ -232,8 +232,20 @@ class Kamal::Configuration::Validator
     end
 
     def validate_docker_options!(options)
-      if options
-        error "Cannot set restart policy in docker options, unless-stopped is required" if options["restart"]
+      if restart_policy = options&.find { |key, _| key.to_s == "restart" }
+        validate_restart_policy!(restart_policy.last)
+      end
+    end
+
+    def validate_restart_policy!(restart_policy)
+      with_context("options/restart") do
+        unless restart_policy.is_a?(String)
+          error %(should be a string. Use "no" to disable restarts)
+        end
+
+        unless restart_policy.match?(/\A(?:no|always|unless-stopped|on-failure(?::\d+)?)\z/)
+          error "should be no, always, unless-stopped, on-failure, or on-failure:N"
+        end
       end
     end
 end

data/lib/kamal/configuration.rb

@@ -12,7 +12,7 @@ class Kamal::Configuration
   delegate :argumentize, :optionize, to: Kamal::Utils
 
   attr_reader :destination, :raw_config, :secrets
-  attr_reader :accessories, :aliases, :boot, :builder, :env, :logging, :proxy, :proxy_boot, :servers, :ssh, :sshkit, :registry
+  attr_reader :accessories, :aliases, :boot, :builder, :env, :logging, :output, :proxy, :proxy_boot, :servers, :ssh, :sshkit, :registry
 
   include Validation
 
@@ -71,6 +71,7 @@ class Kamal::Configuration
     @env = Env.new(config: @raw_config.env || {}, secrets: secrets)
 
     @logging = Logging.new(logging_config: @raw_config.logging)
+    @output = Output.new(config: self)
     @proxy = Proxy.new(config: self, proxy_config: @raw_config.proxy, secrets: secrets)
     @proxy_boot = Proxy::Boot.new(config: self)
     @ssh = Ssh.new(config: self)
@@ -240,6 +241,10 @@ class Kamal::Configuration
     raw_config.drain_timeout || 30
   end
 
+  def stop_timeout
+    raw_config.stop_timeout
+  end
+
   def run_directory
     ".kamal"
   end

data/lib/kamal/git.rb

@@ -6,7 +6,7 @@ module Kamal::Git
   end
 
   def user_name
-    `git config user.name`.strip
+    `git config user.name`.force_encoding(Encoding::UTF_8).strip
   end
 
   def email

data/lib/kamal/otel_shipper.rb

@@ -0,0 +1,176 @@
+require "active_support/core_ext/numeric/time"
+require "net/http"
+require "json"
+require "securerandom"
+require "uri"
+
+class Kamal::OtelShipper
+  BATCH_SIZE = 100
+  FLUSH_INTERVAL = 5.seconds
+
+  OTEL_ATTRIBUTE_KEYS = {
+    service: "service.namespace",
+    version: "kamal.deploy_version",
+    performer: "kamal.performer",
+    destination: "deployment.environment.name"
+  }
+
+  SEVERITIES = {
+    debug: { severityNumber: 5,  severityText: "DEBUG" },
+    info:  { severityNumber: 9,  severityText: "INFO" },
+    warn:  { severityNumber: 13, severityText: "WARN" },
+    error: { severityNumber: 17, severityText: "ERROR" },
+    fatal: { severityNumber: 21, severityText: "FATAL" }
+  }
+
+  LOGGER_SEVERITIES = {
+    Logger::DEBUG => :debug,
+    Logger::INFO  => :info,
+    Logger::WARN  => :warn,
+    Logger::ERROR => :error,
+    Logger::FATAL => :fatal
+  }
+
+  attr_reader :run_id
+
+  def initialize(endpoint:, tags:)
+    @endpoint = URI("#{endpoint.chomp('/')}/v1/logs")
+    @run_id = SecureRandom.uuid
+    @resource_attributes = [
+      { key: "service.name", value: { stringValue: "kamal" } },
+      { key: "service.version", value: { stringValue: Kamal::VERSION } },
+      { key: "kamal.run_id", value: { stringValue: @run_id } },
+      *tags.tags.map do |key, value|
+        otel_key = OTEL_ATTRIBUTE_KEYS.fetch(key, "kamal.#{key}")
+        { key: otel_key, value: { stringValue: value.to_s } }
+      end
+    ]
+    @buffer = Queue.new
+    @flush_mutex = Mutex.new
+    @running = true
+    @signal = Queue.new
+    @thread = start_flush_thread
+  end
+
+  def <<(str)
+    append(str)
+  end
+
+  def append(str, host: nil, iostream: nil, severity: nil)
+    otel_severity = LOGGER_SEVERITIES.fetch(severity, :info)
+    extra = build_context_attributes(host: host, iostream: iostream)
+    str.to_s.each_line do |line|
+      enqueue build_record(line.chomp, severity: otel_severity, attributes: extra)
+    end
+
+    self
+  end
+
+  def event(name, severity: :info, **attributes)
+    attrs = attributes.map { |k, v| { key: k.to_s, value: typed_value(v) } }
+    enqueue build_record(name, severity: severity, event_name: name, attributes: attrs)
+
+    self
+  end
+
+  def flush
+    @flush_mutex.synchronize do
+      lines = drain_buffer
+      ship(lines) if lines.any?
+    end
+  end
+
+  def shutdown
+    @running = false
+    @signal << true
+    @thread&.join(FLUSH_INTERVAL + 1.second)
+    flush
+  end
+
+  private
+    def enqueue(record)
+      @buffer << record
+      @signal << true if @buffer.size >= BATCH_SIZE
+    end
+
+    def start_flush_thread
+      Thread.new do
+        while @running
+          @signal.pop(timeout: FLUSH_INTERVAL)
+          flush
+        end
+      end
+    end
+
+    def drain_buffer
+      records = []
+      records << @buffer.pop(true) until @buffer.empty?
+      records
+    end
+
+    def ship(records)
+      with_connection do |http|
+        records.each_slice(BATCH_SIZE) do |batch|
+          ship_records(http, batch)
+        end
+      end
+    end
+
+    def build_record(body, severity: :info, event_name: nil, attributes: nil)
+      now = time_ns
+      { timeUnixNano: now, observedTimeUnixNano: now, **SEVERITIES.fetch(severity),
+        body: { stringValue: body }, eventName: event_name, attributes: attributes }.compact
+    end
+
+    def build_context_attributes(host:, iostream:)
+      attrs = []
+      attrs << { key: "server.address", value: { stringValue: host } } if host
+      attrs << { key: "log.iostream", value: { stringValue: iostream } } if iostream
+      attrs.presence
+    end
+
+    def typed_value(v)
+      case v
+      when Integer then { intValue: v }
+      when Float   then { doubleValue: v }
+      when Array   then { arrayValue: { values: v.map { |e| typed_value(e) } } }
+      else              { stringValue: v.to_s }
+      end
+    end
+
+    def with_connection
+      http = Net::HTTP.new(@endpoint.host, @endpoint.port)
+      http.use_ssl = @endpoint.scheme == "https"
+      http.open_timeout = 2.seconds
+      http.read_timeout = 5.seconds
+      http.start { |conn| yield conn }
+    rescue StandardError => e
+      unless @ship_error_logged
+        @ship_error_logged = true
+        $stderr.puts "OTel log shipping failed: #{e.class}: #{e.message}"
+        $stderr.puts e.backtrace.join("\n") if ENV["VERBOSE"]
+      end
+    end
+
+    def ship_records(http, records)
+      payload = {
+        resourceLogs: [ {
+          resource: { attributes: @resource_attributes },
+          scopeLogs: [ { scope: { name: "kamal", version: Kamal::VERSION }, logRecords: records } ]
+        } ]
+      }
+
+      req = Net::HTTP::Post.new(@endpoint.request_uri, "Content-Type" => "application/json")
+      req.body = JSON.generate(payload)
+      response = http.request(req)
+
+      unless response.is_a?(Net::HTTPSuccess) || @ship_error_logged
+        @ship_error_logged = true
+        $stderr.puts "OTel log shipping failed: HTTP #{response.code} #{response.message}"
+      end
+    end
+
+    def time_ns
+      Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond).to_s
+    end
+end

data/lib/kamal/output/base_logger.rb

@@ -0,0 +1,29 @@
+require "logger"
+
+class Kamal::Output::BaseLogger < ::Logger
+  def initialize
+    super(nil)
+    @subscription = ActiveSupport::Notifications.subscribe("modify.kamal", self)
+  end
+
+  def start(name, id, payload)
+    @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    on_start(payload)
+  end
+
+  def finish(name, id, payload)
+    runtime = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at).round(1)
+    on_finish(payload, runtime)
+  end
+
+  def add(severity, message = nil, progname = nil, &block)
+    if msg = message || (block ? block.call : progname)
+      self << msg.to_s
+    end
+  end
+
+  def close
+    ActiveSupport::Notifications.unsubscribe(@subscription)
+    on_close
+  end
+end

data/lib/kamal/output/file_logger.rb

@@ -0,0 +1,51 @@
+class Kamal::Output::FileLogger < Kamal::Output::BaseLogger
+  attr_reader :path
+
+  def self.build(settings:, config:)
+    raise ArgumentError, "file path is required" unless settings["path"]
+    new(path: settings["path"])
+  end
+
+  def initialize(path:)
+    @path = Pathname.new(path)
+    super()
+  end
+
+  def <<(message)
+    @file&.print(message)
+  end
+
+  private
+    def on_start(payload)
+      path.mkpath
+      @file_path = path.join(filename_for(payload))
+      @file = File.open(@file_path, "a")
+      @file.sync = true
+    end
+
+    def on_finish(payload, runtime)
+      if @file
+        if payload[:exception]
+          error_class, error_message = payload[:exception]
+          @file.puts "# FAILED: #{error_class}: #{error_message} (#{runtime}s)"
+        else
+          @file.puts "# Completed in #{runtime}s"
+        end
+        @file.close
+        @file = nil
+        puts "Logs written to #{@file_path}"
+      end
+    end
+
+    def on_close
+      if @file
+        @file.close
+        @file = nil
+      end
+    end
+
+    def filename_for(payload)
+      command = [ payload[:command], payload[:subcommand] ].compact.join("_")
+      [ Time.now.strftime("%Y-%m-%dT%H-%M-%S"), payload[:destination], command ].compact.join("_") + ".log"
+    end
+end

data/lib/kamal/output/formatter.rb

@@ -0,0 +1,36 @@
+class Kamal::Output::Formatter < SSHKit::Formatter::Pretty
+  def initialize(output, logger)
+    @logger = logger
+    super(output)
+  end
+
+  def log_command_start(command)
+    with_command_context(command) { super }
+  end
+
+  def log_command_data(command, stream_type, stream_data)
+    with_command_context(command, iostream: stream_type.to_s) { super }
+  end
+
+  def log_command_exit(command)
+    with_command_context(command) { super }
+  end
+
+  private
+    def write_message(verbosity, message, uuid = nil)
+      super
+      Thread.current[:kamal_severity] = verbosity
+      @logger << "#{format_message(verbosity, message, uuid)}\n" rescue nil
+    ensure
+      Thread.current[:kamal_severity] = nil
+    end
+
+    def with_command_context(command, iostream: nil)
+      Thread.current[:kamal_host] = command.host.to_s
+      Thread.current[:kamal_iostream] = iostream
+      yield
+    ensure
+      Thread.current[:kamal_host] = nil
+      Thread.current[:kamal_iostream] = nil
+    end
+end

data/lib/kamal/output/otel_logger.rb

@@ -0,0 +1,70 @@
+class Kamal::Output::OtelLogger < Kamal::Output::BaseLogger
+  def self.build(settings:, config:)
+    raise ArgumentError, "OTel endpoint is required" unless settings["endpoint"]
+    new(
+      endpoint: settings["endpoint"],
+      tags: Kamal::Tags.from_config(config).except(:service_version, :recorded_at),
+      service: config.service
+    )
+  end
+
+  def initialize(endpoint:, tags:, service: nil)
+    @endpoint = endpoint
+    @shipper = Kamal::OtelShipper.new(endpoint: endpoint, tags: tags)
+    @service = service
+    super()
+  end
+
+  def <<(message)
+    host = Thread.current[:kamal_host]
+    iostream = Thread.current[:kamal_iostream]
+    severity = Thread.current[:kamal_severity]
+    @shipper.append(message, host: host, iostream: iostream, severity: severity)
+  end
+
+  DEPLOY_COMMANDS = %w[ deploy redeploy rollback setup ].freeze
+
+  private
+    def on_start(payload)
+      @shipper.event("kamal.start",
+        "kamal.command": full_command(payload),
+        **deployment_attrs(payload))
+    end
+
+    def on_finish(payload, runtime)
+      if payload[:exception]
+        error_class, error_message = payload[:exception]
+        @shipper.event("kamal.failed", severity: :error,
+          "kamal.command": full_command(payload), "kamal.runtime": runtime,
+          "exception.type": error_class, "exception.message": error_message,
+          **deployment_attrs(payload, status: "failed"))
+      else
+        @shipper.event("kamal.complete",
+          "kamal.command": full_command(payload), "kamal.runtime": runtime,
+          **deployment_attrs(payload, status: "succeeded"))
+      end
+      puts "Logs sent to #{@endpoint}"
+    end
+
+    def on_close
+      @shipper.shutdown
+    end
+
+    def full_command(payload)
+      [ payload[:command], payload[:subcommand] ].compact.join(" ")
+    end
+
+    def deploy?(payload)
+      DEPLOY_COMMANDS.include?(payload[:command])
+    end
+
+    def deployment_attrs(payload, status: nil)
+      if deploy?(payload)
+        attrs = { "deployment.id": @shipper.run_id, "deployment.name": "#{full_command(payload)} #{@service}" }
+        attrs[:"deployment.status"] = status if status
+        attrs
+      else
+        {}
+      end
+    end
+end

data/lib/kamal/secrets/adapters/aws_secrets_manager.rb

@@ -14,8 +14,12 @@ class Kamal::Secrets::Adapters::AwsSecretsManager < Kamal::Secrets::Adapters::Ba
           secret_name = secret["Name"]
           secret_string = JSON.parse(secret["SecretString"])
 
-          secret_string.each do |key, value|
-            results["#{secret_name}/#{key}"] = value
+          if secret_string.is_a?(Hash)
+            secret_string.each do |key, value|
+              results["#{secret_name}/#{key}"] = stringify_secret_value(value)
+            end
+          else
+            results["#{secret_name}"] = stringify_secret_value(secret_string)
           end
         rescue JSON::ParserError
           results["#{secret_name}"] = secret["SecretString"]
@@ -40,6 +44,10 @@ class Kamal::Secrets::Adapters::AwsSecretsManager < Kamal::Secrets::Adapters::Ba
       end
     end
 
+    def stringify_secret_value(value)
+      value.is_a?(String) ? value : JSON.dump(value)
+    end
+
     def check_dependencies!
       raise RuntimeError, "AWS CLI is not installed" unless cli_installed?
     end

data/lib/kamal/secrets/adapters/passbolt.rb

@@ -47,7 +47,7 @@ class Kamal::Secrets::Adapters::Passbolt < Kamal::Secrets::Adapters::Base
       end
 
       filter_condition = filter_conditions.any? ? "--filter '#{filter_conditions.join(" || ")}'" : ""
-      items = `passbolt list resources #{filter_condition} #{folders.map { |item| "--folder #{item["id"].to_s.shellescape}" }.join(" ")} --json`
+      items = `passbolt list resources #{filter_condition} #{folders.map { |item| "--folder #{item["id"].to_s.shellescape}" }.join(" ")} --column name --column password --json`
       raise RuntimeError, "Could not read #{secrets} from Passbolt" unless $?.success?
       items = JSON.parse(items)
       found_names = items.map { |item| item["name"] }

data/lib/kamal/secrets.rb

@@ -3,7 +3,7 @@ require "dotenv"
 class Kamal::Secrets
   Kamal::Secrets::Dotenv::InlineCommandSubstitution.install!
 
-  def initialize(destination: nil, secrets_path:)
+  def initialize(destination: nil, secrets_path: ".kamal/secrets")
     @destination = destination
     @secrets_path = secrets_path
     @mutex = Mutex.new

data/lib/kamal/sshkit_with_ext.rb

@@ -19,11 +19,16 @@ class SSHKit::Backend::Abstract
     JSON.pretty_generate(JSON.parse(capture(*args, **kwargs)))
   end
 
-  def puts_by_host(host, output, type: "App", quiet: false)
-    unless quiet
-      puts "#{type} Host: #{host}"
+  def puts_by_host(host, output, type: "App", quiet: false, raw: false)
+    if raw
+      $stdout.binmode
+      $stdout.write(output)
+    else
+      unless quiet
+        puts "#{type} Host: #{host}"
+      end
+      puts "#{output}\n\n"
     end
-    puts "#{output}\n\n"
   end
 
   # Our execution pattern is for the CLI execute args lists returned

data/lib/kamal/version.rb

@@ -1,3 +1,3 @@
 module Kamal
-  VERSION = "2.11.0"
+  VERSION = "2.12.0"
 end