kamal 2.11.0 → 2.12.0

data/lib/kamal/cli/main.rb

@@ -4,7 +4,7 @@ class Kamal::Cli::Main < Kamal::Cli::Base
   option :no_cache, type: :boolean, default: false, desc: "Build without using Docker's build cache"
   def setup
     print_runtime do
-      with_lock do
+      modify(lock: true) do
         invoke_options = deploy_options
 
         say "Ensure Docker is installed...", :magenta
@@ -19,88 +19,94 @@ class Kamal::Cli::Main < Kamal::Cli::Base
   option :skip_push, aliases: "-P", type: :boolean, default: false, desc: "Skip image build and push"
   option :no_cache, type: :boolean, default: false, desc: "Build without using Docker's build cache"
   def deploy(boot_accessories: false)
-    runtime = print_runtime do
-      invoke_options = deploy_options
+    modify do
+      runtime = print_runtime do
+        invoke_options = deploy_options
 
-      if options[:skip_push]
-        say "Pull app image...", :magenta
-        invoke "kamal:cli:build:pull", [], invoke_options
-      else
-        say "Build and push app image...", :magenta
-        invoke "kamal:cli:build:deliver", [], invoke_options
-      end
+        if options[:skip_push]
+          say "Pull app image...", :magenta
+          invoke "kamal:cli:build:pull", [], invoke_options
+        else
+          say "Build and push app image...", :magenta
+          invoke "kamal:cli:build:deliver", [], invoke_options
+        end
 
-      with_lock do
-        run_hook "pre-deploy", secrets: true
+        modify(lock: true) do
+          run_hook "pre-deploy", secrets: true
 
-        say "Ensure kamal-proxy is running...", :magenta
-        invoke "kamal:cli:proxy:boot", [], invoke_options
+          say "Ensure kamal-proxy is running...", :magenta
+          invoke "kamal:cli:proxy:boot", [], invoke_options
 
-        invoke "kamal:cli:accessory:boot", [ "all" ], invoke_options if boot_accessories
+          invoke "kamal:cli:accessory:boot", [ "all" ], invoke_options if boot_accessories
 
-        say "Detect stale containers...", :magenta
-        invoke "kamal:cli:app:stale_containers", [], invoke_options.merge(stop: true)
+          say "Detect stale containers...", :magenta
+          invoke "kamal:cli:app:stale_containers", [], invoke_options.merge(stop: true)
 
-        invoke "kamal:cli:app:boot", [], invoke_options
+          invoke "kamal:cli:app:boot", [], invoke_options
 
-        say "Prune old containers and images...", :magenta
-        invoke "kamal:cli:prune:all", [], invoke_options
+          say "Prune old containers and images...", :magenta
+          invoke "kamal:cli:prune:all", [], invoke_options
+        end
       end
-    end
 
-    run_hook "post-deploy", secrets: true, runtime: runtime.round.to_s
+      run_hook "post-deploy", secrets: true, runtime: runtime.round.to_s
+    end
   end
 
   desc "redeploy", "Deploy app to servers without bootstrapping servers, starting kamal-proxy and pruning"
   option :skip_push, aliases: "-P", type: :boolean, default: false, desc: "Skip image build and push"
   option :no_cache, type: :boolean, default: false, desc: "Build without using Docker's build cache"
   def redeploy
-    runtime = print_runtime do
-      invoke_options = deploy_options
+    modify do
+      runtime = print_runtime do
+        invoke_options = deploy_options
 
-      if options[:skip_push]
-        say "Pull app image...", :magenta
-        invoke "kamal:cli:build:pull", [], invoke_options
-      else
-        say "Build and push app image...", :magenta
-        invoke "kamal:cli:build:deliver", [], invoke_options
-      end
+        if options[:skip_push]
+          say "Pull app image...", :magenta
+          invoke "kamal:cli:build:pull", [], invoke_options
+        else
+          say "Build and push app image...", :magenta
+          invoke "kamal:cli:build:deliver", [], invoke_options
+        end
 
-      with_lock do
-        run_hook "pre-deploy", secrets: true
+        modify(lock: true) do
+          run_hook "pre-deploy", secrets: true
 
-        say "Detect stale containers...", :magenta
-        invoke "kamal:cli:app:stale_containers", [], invoke_options.merge(stop: true)
+          say "Detect stale containers...", :magenta
+          invoke "kamal:cli:app:stale_containers", [], invoke_options.merge(stop: true)
 
-        invoke "kamal:cli:app:boot", [], invoke_options
+          invoke "kamal:cli:app:boot", [], invoke_options
+        end
       end
-    end
 
-    run_hook "post-deploy", secrets: true, runtime: runtime.round.to_s
+      run_hook "post-deploy", secrets: true, runtime: runtime.round.to_s
+    end
   end
 
   desc "rollback [VERSION]", "Rollback app to VERSION"
   def rollback(version)
     rolled_back = false
-    runtime = print_runtime do
-      with_lock do
-        invoke_options = deploy_options
 
-        KAMAL.config.version = version
-        old_version = nil
+    modify do
+      runtime = print_runtime do
+        modify(lock: true) do
+          invoke_options = deploy_options
 
-        if container_available?(version)
-          run_hook "pre-deploy", secrets: true
+          KAMAL.config.version = version
 
-          invoke "kamal:cli:app:boot", [], invoke_options.merge(version: version)
-          rolled_back = true
-        else
-          say "The app version '#{version}' is not available as a container (use 'kamal app containers' for available versions)", :red
+          if container_available?(version)
+            run_hook "pre-deploy", secrets: true
+
+            invoke "kamal:cli:app:boot", [], invoke_options.merge(version: version)
+            rolled_back = true
+          else
+            say "The app version '#{version}' is not available as a container (use 'kamal app containers' for available versions)", :red
+          end
         end
       end
-    end
 
-    run_hook "post-deploy", secrets: true, runtime: runtime.round.to_s if rolled_back
+      run_hook "post-deploy", secrets: true, runtime: runtime.round.to_s if rolled_back
+    end
   end
 
   desc "details", "Show details about all containers"
@@ -182,7 +188,7 @@ class Kamal::Cli::Main < Kamal::Cli::Base
   option :confirmed, aliases: "-y", type: :boolean, default: false, desc: "Proceed without confirmation question"
   def remove
     confirming "This will remove all containers and images. Are you sure?" do
-      with_lock do
+      modify(lock: true) do
         invoke "kamal:cli:app:remove", [], options.without(:confirmed)
         invoke "kamal:cli:proxy:remove", [], options.without(:confirmed)
         invoke "kamal:cli:accessory:remove", [ "all" ], options
@@ -196,7 +202,7 @@ class Kamal::Cli::Main < Kamal::Cli::Base
   option :rolling, type: :boolean, default: false, desc: "Upgrade one host at a time"
   def upgrade
     confirming "This will replace Traefik with kamal-proxy and restart all accessories" do
-      with_lock do
+      modify(lock: true) do
         if options[:rolling]
           KAMAL.hosts.each do |host|
             KAMAL.with_specific_hosts(host) do

data/lib/kamal/cli/proxy.rb

@@ -1,7 +1,7 @@
 class Kamal::Cli::Proxy < Kamal::Cli::Base
   desc "boot", "Boot proxy on servers"
   def boot
-    with_lock do
+    modify(lock: true) do
       on(KAMAL.hosts) do |host|
         execute *KAMAL.docker.create_network
       rescue SSHKit::Command::Failed => e
@@ -108,7 +108,7 @@ class Kamal::Cli::Proxy < Kamal::Cli::Base
   option :confirmed, aliases: "-y", type: :boolean, default: false, desc: "Proceed without confirmation question"
   def reboot
     confirming "This will cause a brief outage on each host. Are you sure?" do
-      with_lock do
+      modify(lock: true) do
         host_groups = options[:rolling] ? KAMAL.proxy_hosts : [ KAMAL.proxy_hosts ]
         host_groups.each do |hosts|
           host_list = Array(hosts).join(",")
@@ -174,7 +174,7 @@ class Kamal::Cli::Proxy < Kamal::Cli::Base
 
   desc "start", "Start existing proxy container on servers"
   def start
-    with_lock do
+    modify(lock: true) do
       on(KAMAL.proxy_hosts) do |host|
         execute *KAMAL.auditor.record("Started proxy"), verbosity: :debug
         execute *KAMAL.proxy(host).start
@@ -184,7 +184,7 @@ class Kamal::Cli::Proxy < Kamal::Cli::Base
 
   desc "stop", "Stop existing proxy container on servers"
   def stop
-    with_lock do
+    modify(lock: true) do
       on(KAMAL.proxy_hosts) do |host|
         execute *KAMAL.auditor.record("Stopped proxy"), verbosity: :debug
         execute *KAMAL.proxy(host).stop, raise_on_non_zero_exit: false
@@ -194,7 +194,7 @@ class Kamal::Cli::Proxy < Kamal::Cli::Base
 
   desc "restart", "Restart existing proxy container on servers"
   def restart
-    with_lock do
+    modify(lock: true) do
       stop
       start
     end
@@ -236,7 +236,7 @@ class Kamal::Cli::Proxy < Kamal::Cli::Base
   desc "remove", "Remove proxy container and image from servers"
   option :force, type: :boolean, default: false, desc: "Force removing proxy when apps are still installed"
   def remove
-    with_lock do
+    modify(lock: true) do
       if removal_allowed?(options[:force])
         stop
         remove_container
@@ -248,7 +248,7 @@ class Kamal::Cli::Proxy < Kamal::Cli::Base
 
   desc "remove_container", "Remove proxy container from servers", hide: true
   def remove_container
-    with_lock do
+    modify(lock: true) do
       on(KAMAL.proxy_hosts) do
         execute *KAMAL.auditor.record("Removed proxy container"), verbosity: :debug
         execute *KAMAL.proxy(host).remove_container
@@ -258,7 +258,7 @@ class Kamal::Cli::Proxy < Kamal::Cli::Base
 
   desc "remove_image", "Remove proxy image from servers", hide: true
   def remove_image
-    with_lock do
+    modify(lock: true) do
       on(KAMAL.proxy_hosts) do
         execute *KAMAL.auditor.record("Removed proxy image"), verbosity: :debug
         execute *KAMAL.proxy(host).remove_image
@@ -268,7 +268,7 @@ class Kamal::Cli::Proxy < Kamal::Cli::Base
 
   desc "remove_proxy_directory", "Remove the proxy directory from servers", hide: true
   def remove_proxy_directory
-    with_lock do
+    modify(lock: true) do
       on(KAMAL.proxy_hosts) do
         execute *KAMAL.proxy(host).remove_proxy_directory, raise_on_non_zero_exit: false
       end

data/lib/kamal/cli/prune.rb

@@ -1,7 +1,7 @@
 class Kamal::Cli::Prune < Kamal::Cli::Base
   desc "all", "Prune unused images and stopped containers"
   def all
-    with_lock do
+    modify(lock: true) do
       containers
       images
     end
@@ -9,7 +9,7 @@ class Kamal::Cli::Prune < Kamal::Cli::Base
 
   desc "images", "Prune unused images"
   def images
-    with_lock do
+    modify(lock: true) do
       on(KAMAL.hosts) do
         execute *KAMAL.auditor.record("Pruned images"), verbosity: :debug
         execute *KAMAL.prune.dangling_images
@@ -24,7 +24,7 @@ class Kamal::Cli::Prune < Kamal::Cli::Base
     retain = options.fetch(:retain, KAMAL.config.retain_containers)
     raise "retain must be at least 1" if retain < 1
 
-    with_lock do
+    modify(lock: true) do
       on(KAMAL.hosts) do
         execute *KAMAL.auditor.record("Pruned containers"), verbosity: :debug
         execute *KAMAL.prune.app_containers(retain: retain)

data/lib/kamal/cli/server.rb

@@ -1,33 +1,42 @@
 class Kamal::Cli::Server < Kamal::Cli::Base
   desc "exec", "Run a custom command on the server (use --help to show options)"
   option :interactive, type: :boolean, aliases: "-i", default: false, desc: "Run the command interactively (use for console/bash)"
+  option :raw, type: :boolean, default: false, desc: "Output raw, unmodified stdout"
   def exec(*cmd)
-    pre_connect_if_required
+    raw = options[:raw]
 
-    cmd = Kamal::Utils.join_commands(cmd)
-    hosts = KAMAL.hosts
-    quiet = options[:quiet]
+    if raw && options[:interactive]
+      raise ArgumentError, "Raw is not compatible with interactive"
+    end
+
+    with_raw_output(raw) do
+      pre_connect_if_required
 
-    case
-    when options[:interactive]
-      host = KAMAL.primary_host
+      cmd = Kamal::Utils.join_commands(cmd)
+      hosts = KAMAL.hosts
+      quiet = options[:quiet]
 
-      say "Running '#{cmd}' on #{host} interactively...", :magenta
+      case
+      when options[:interactive]
+        host = KAMAL.primary_host
 
-      run_locally { exec KAMAL.server.run_over_ssh(cmd, host: host) }
-    else
-      say "Running '#{cmd}' on #{hosts.join(', ')}...", :magenta
+        say "Running '#{cmd}' on #{host} interactively...", :magenta
 
-      on(hosts) do |host|
-        execute *KAMAL.auditor.record("Executed cmd '#{cmd}' on #{host}"), verbosity: :debug
-        puts_by_host host, capture_with_info(cmd), quiet: quiet
+        run_locally { exec KAMAL.server.run_over_ssh(cmd, host: host) }
+      else
+        say "Running '#{cmd}' on #{hosts.join(', ')}...", :magenta
+
+        on(hosts) do |host|
+          execute *KAMAL.auditor.record("Executed cmd '#{cmd}' on #{host}"), verbosity: :debug
+          puts_by_host host, capture_with_info(cmd, strip: !raw), quiet: quiet, raw: raw
+        end
       end
     end
   end
 
   desc "bootstrap", "Set up Docker to run Kamal apps"
   def bootstrap
-    with_lock do
+    modify(lock: true) do
       missing = []
 
       on(KAMAL.hosts) do |host|

data/lib/kamal/cli/templates/sample_hooks/docker-setup.sample

@@ -1,3 +1,3 @@
-#!/bin/sh
+#!/usr/bin/env sh
 
 echo "Docker set up on $KAMAL_HOSTS..."

data/lib/kamal/cli/templates/sample_hooks/post-app-boot.sample

@@ -1,3 +1,3 @@
-#!/bin/sh
+#!/usr/bin/env sh
 
 echo "Booted app version $KAMAL_VERSION on $KAMAL_HOSTS..."

data/lib/kamal/cli/templates/sample_hooks/post-deploy.sample

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/usr/bin/env sh
 
 # A sample post-deploy hook
 #

data/lib/kamal/cli/templates/sample_hooks/post-proxy-reboot.sample

@@ -1,3 +1,3 @@
-#!/bin/sh
+#!/usr/bin/env sh
 
 echo "Rebooted kamal-proxy on $KAMAL_HOSTS"

data/lib/kamal/cli/templates/sample_hooks/pre-app-boot.sample

@@ -1,3 +1,3 @@
-#!/bin/sh
+#!/usr/bin/env sh
 
 echo "Booting app version $KAMAL_VERSION on $KAMAL_HOSTS..."

data/lib/kamal/cli/templates/sample_hooks/pre-build.sample

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/usr/bin/env sh
 
 # A sample pre-build hook
 #

data/lib/kamal/cli/templates/sample_hooks/pre-proxy-reboot.sample

@@ -1,3 +1,3 @@
-#!/bin/sh
+#!/usr/bin/env sh
 
 echo "Rebooting kamal-proxy on $KAMAL_HOSTS..."

data/lib/kamal/cli/templates/secrets

@@ -1,6 +1,10 @@
 # Secrets defined here are available for reference under registry/password, env/secret, builder/secrets,
 # and accessories/*/env/secret in config/deploy.yml. All secrets should be pulled from either
 # password manager, ENV, or a file. DO NOT ENTER RAW CREDENTIALS HERE! This file needs to be safe for git.
+#
+# When deploying with destinations, shared secrets can go in .kamal/secrets-common and
+# destination-specific secrets in .kamal/secrets.<destination>. This .kamal/secrets file is used
+# only when no destination is selected.
 
 # Option 1: Read secrets from the environment
 # KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

data/lib/kamal/commander.rb

@@ -1,9 +1,11 @@
 require "active_support/core_ext/enumerable"
 require "active_support/core_ext/module/delegation"
 require "active_support/core_ext/object/blank"
+require "active_support/broadcast_logger"
+require "active_support/notifications"
 
 class Kamal::Commander
-  attr_accessor :verbosity, :holding_lock, :connected
+  attr_accessor :verbosity, :holding_lock, :connected, :logging, :lock_wait, :lock_wait_timeout, :lock_wait_interval
   attr_reader :specific_roles, :specific_hosts
   delegate :hosts, :roles, :primary_host, :primary_role, :roles_on, :app_hosts, :proxy_hosts, :accessory_hosts, to: :specifics
 
@@ -15,8 +17,14 @@ class Kamal::Commander
     self.verbosity = :info
     self.holding_lock = ENV["KAMAL_LOCK"] == "true"
     self.connected = false
+    self.logging = false
+    self.lock_wait = false
+    self.lock_wait_timeout = 900
+    self.lock_wait_interval = 15
+    @modify_depth = 0
     @specifics = @specific_roles = @specific_hosts = nil
     @config = @config_kwargs = nil
+    @output_logger = nil
     @commands = {}
   end
 
@@ -142,6 +150,22 @@ class Kamal::Commander
     SSHKit.config.output_verbosity = old_level
   end
 
+  def modify(command:, subcommand:)
+    @logging = true
+    if modify_started
+      ActiveSupport::Notifications.instrument("modify.kamal",
+        command: command, subcommand: subcommand, destination: config.destination, hosts: hosts) { yield }
+    else
+      yield
+    end
+  ensure
+    output_logger.close if modify_finished
+  end
+
+  def log(line)
+    output_logger << "#{line}\n" if logging
+  end
+
   def holding_lock?
     self.holding_lock
   end
@@ -151,6 +175,20 @@ class Kamal::Commander
   end
 
   private
+    def output_logger
+      @output_logger ||= ActiveSupport::BroadcastLogger.new
+    end
+
+    def modify_started
+      @modify_depth += 1
+      @modify_depth == 1
+    end
+
+    def modify_finished
+      @modify_depth -= 1
+      @modify_depth == 0
+    end
+
     # Lazy setup of SSHKit
     def configure_sshkit_with(config)
       SSHKit::Backend::Netssh.pool.idle_timeout = config.sshkit.pool_idle_timeout
@@ -161,6 +199,21 @@ class Kamal::Commander
       end
       SSHKit.config.command_map[:docker] = "docker" # No need to use /usr/bin/env, just clogs up the logs
       SSHKit.config.output_verbosity = verbosity
+
+      configure_output_with(config)
+    end
+
+    def configure_output_with(config)
+      return unless config.output.enabled?
+
+      config.output.loggers.each { |logger| output_logger.broadcast_to(logger) }
+
+      SSHKit.config.output = Kamal::Output::Formatter.new($stdout, output_logger)
+
+      at_exit { @output_logger&.close }
+    rescue => e
+      $stderr.puts "Output logger setup failed: #{e.class}: #{e.message}"
+      $stderr.puts e.backtrace.join("\n") if ENV["VERBOSE"]
     end
 
     def specifics

data/lib/kamal/commands/accessory.rb

@@ -4,7 +4,7 @@ class Kamal::Commands::Accessory < Kamal::Commands::Base
   attr_reader :accessory_config
   delegate :service_name, :image, :hosts, :port, :files, :directories, :cmd,
            :network_args, :publish_args, :env_args, :volume_args, :label_args, :option_args,
-           :secrets_io, :secrets_path, :env_directory, :proxy, :running_proxy?, :registry,
+           :restart_policy, :secrets_io, :secrets_path, :env_directory, :proxy, :running_proxy?, :registry,
            to: :accessory_config
 
   def initialize(config, name:)
@@ -16,7 +16,7 @@ class Kamal::Commands::Accessory < Kamal::Commands::Base
     docker :run,
       "--name", service_name,
       "--detach",
-      "--restart", "unless-stopped",
+      "--restart", restart_policy,
       *network_args,
       *config.logging_args,
       *publish_args,

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

@@ -21,7 +21,7 @@ module Kamal::Commands::App::Logging
   def container_id_command(container_id)
     case container_id
     when Array then container_id
-    when String, Symbol then "echo #{container_id}"
+    when String, Symbol then shell([ "echo #{container_id}" ])
     else current_running_container_id
     end
   end

data/lib/kamal/commands/app.rb

@@ -16,7 +16,7 @@ class Kamal::Commands::App < Kamal::Commands::Base
   def run(hostname: nil)
     docker :run,
       "--detach",
-      "--restart unless-stopped",
+      "--restart", role.restart_policy,
       "--name", container_name,
       "--network", "kamal",
       *([ "--hostname", hostname ] if hostname),

data/lib/kamal/commands/builder/clone.rb

@@ -9,7 +9,8 @@ module Kamal::Commands::Builder::Clone
       git(:fetch, :origin, path: escaped_build_directory),
       git(:reset, "--hard", Kamal::Git.revision, path: escaped_build_directory),
       git(:clean, "-fdx", path: escaped_build_directory),
-      git(:submodule, :update, "--init", path: escaped_build_directory)
+      git(:submodule, :update, "--init", path: escaped_build_directory),
+      git(:gc, "--auto", "--quiet", path: escaped_build_directory)
     ]
   end
 

data/lib/kamal/configuration/accessory.rb

@@ -102,11 +102,11 @@ class Kamal::Configuration::Accessory
   end
 
   def option_args
-    if args = accessory_config["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 cmd
@@ -173,6 +173,14 @@ class Kamal::Configuration::Accessory
       accessory_config["volumes"] || []
     end
 
+    def docker_options
+      accessory_config["options"] || {}
+    end
+
+    def restart_policy_option
+      docker_options.find { |key, _| key.to_s == "restart" }&.last
+    end
+
     def path_volumes(paths)
       paths.map do |local, config|
         Kamal::Configuration::Volume.new \

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

@@ -99,7 +99,6 @@ hooks_path: /user_home/kamal/hooks
 #
 # Global setting for all hooks:
 hooks_output: :verbose
-
 # Or per-hook settings:
 hooks_output:
   pre-deploy: :verbose
@@ -108,13 +107,16 @@ hooks_output:
 # 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):
+# Kamal looks for `<secrets_path>-common` first and then `<secrets_path>`.
+# When using destinations, it instead looks for `<secrets_path>-common` first and then
+# `<secrets_path>.<destination>`. Later files override earlier ones.
 secrets_path: /user_home/kamal/secrets
 
 # Error pages
 #
 # A directory relative to the app root to find error pages for the proxy to serve.
-# Any files in the format 4xx.html or 5xx.html will be copied to the hosts.
+# Name each page after the HTTP status code it serves, e.g. 404.html, 500.html,
+# 502.html, 503.html, and 504.html.
 error_pages_path: public
 
 # Require destinations
@@ -159,6 +161,13 @@ deploy_timeout: 10
 # How long to wait for a container to drain, default 30:
 drain_timeout: 10
 
+# Stop timeout
+#
+# How long to wait for a container to stop after SIGTERM, default is
+# the drain_timeout for non-proxied roles and 10s (Docker default) for proxied roles.
+# Can be overridden per role:
+stop_timeout: 30
+
 # Run directory
 #
 # Directory to store kamal runtime files in on the host, default `.kamal`:
@@ -206,6 +215,12 @@ boot:
 logging:
   ...
 
+# Output
+#
+# Configure output loggers (OTel, file), see kamal docs output:
+output:
+  ...
+
 # Aliases
 #
 # Alias configuration, see kamal docs alias:

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

@@ -14,12 +14,14 @@ env:
 
 # Secrets
 #
-# Kamal uses dotenv to automatically load environment variables set in the `.kamal/secrets` file.
+# Kamal uses dotenv to automatically load environment variables from the configured secrets files.
 #
-# If you are using destinations, secrets will instead be read from `.kamal/secrets.<DESTINATION>` if
-# it exists.
+# Common secrets across all destinations can be set in `.kamal/secrets-common`. Kamal looks for
+# `.kamal/secrets-common` first, then `.kamal/secrets`, with later values overriding earlier ones.
 #
-# Common secrets across all destinations can be set in `.kamal/secrets-common`.
+# If you are using destinations, Kamal looks for `.kamal/secrets-common` first, then
+# `.kamal/secrets.<destination>`. The non-destination `.kamal/secrets` file is not read when a
+# destination is selected.
 #
 # This file can be used to set variables like `KAMAL_REGISTRY_PASSWORD` or database passwords.
 # You can use variable or command substitution in the secrets file.