odysseus-core 0.3.2 → 0.10.0

data/lib/odysseus/builder/client.rb

@@ -118,7 +118,7 @@ module Odysseus
         executor = build_executor
         output = executor.call("docker images -q #{image} 2>/dev/null || echo ''")
         !output.strip.empty?
-      rescue
+      rescue StandardError
         false
       end
 
@@ -145,14 +145,18 @@ module Odysseus
           arch: config[:arch] || config['arch'],
           platforms: config[:platforms] || config['platforms'] || [],
           build_args: config[:build_args] || config['build_args'] || {},
-          cache: config.key?(:cache) ? config[:cache] : (config.key?('cache') ? config['cache'] : true),
+          cache: if config.key?(:cache)
+                   config[:cache]
+                 else
+                   (config.key?('cache') ? config['cache'] : true)
+                 end,
           push: config[:push] || config['push'] || false,
           multiarch: config[:multiarch] || config['multiarch'] || false
         }
       end
 
       def build_local(context_path:, image:)
-        @logger.info("Building locally...")
+        @logger.info('Building locally...')
 
         cmd = build_docker_command(context_path: context_path, image: image)
         @logger.debug(cmd) if @logger.respond_to?(:debug)
@@ -161,7 +165,7 @@ module Odysseus
         output = execute_local(cmd, context_path)
 
         { success: true, image: image, strategy: :local, output: output }
-      rescue => e
+      rescue StandardError => e
         @logger.error("Local build failed: #{e.message}")
         { success: false, strategy: :local, error: e.message }
       end
@@ -169,9 +173,7 @@ module Odysseus
       def build_remote(context_path:, image:)
         @logger.info("Building on remote host: #{@config[:host]}")
 
-        unless @config[:host]
-          raise BuildError, "Remote build strategy requires 'host' to be configured"
-        end
+        raise BuildError, "Remote build strategy requires 'host' to be configured" unless @config[:host]
 
         ssh = connect_to_build_host
 
@@ -181,7 +183,7 @@ module Odysseus
           ssh.execute("mkdir -p #{remote_dir}")
 
           # Upload build context
-          @logger.info("Uploading build context...")
+          @logger.info('Uploading build context...')
           ssh.upload(context_path, remote_dir)
 
           # Determine the actual context directory on remote
@@ -243,9 +245,8 @@ module Odysseus
         # Execute command locally using system
         Dir.chdir(working_dir) do
           output = `#{cmd} 2>&1`
-          unless $?.success?
-            raise BuildError, "Build command failed: #{output}"
-          end
+          raise BuildError, "Build command failed: #{output}" unless $?.success?
+
           output
         end
       end
@@ -264,9 +265,8 @@ module Odysseus
 
       def execute_local_command(cmd)
         output = `#{cmd} 2>&1`
-        unless $?.success?
-          raise BuildError, "Command failed: #{output}"
-        end
+        raise BuildError, "Command failed: #{output}" unless $?.success?
+
         output
       end
 
@@ -284,7 +284,7 @@ module Odysseus
           l.define_singleton_method(:info) { |msg| puts msg }
           l.define_singleton_method(:warn) { |msg| puts "[WARN] #{msg}" }
           l.define_singleton_method(:error) { |msg| puts "[ERROR] #{msg}" }
-          l.define_singleton_method(:debug) { |msg| puts "  > #{msg}" if @verbose }
+          l.define_singleton_method(:debug) { |msg| puts "  > #{Odysseus::CommandRedaction.redact(msg)}" if @verbose }
         end
       end
     end

data/lib/odysseus/caddy/client.rb

@@ -1,13 +1,19 @@
 # lib/odysseus/caddy/client.rb
 
 require 'json'
+require 'shellwords'
 
 module Odysseus
   module Caddy
     class Client
       ADMIN_API_PORT = 2019
-      CONTAINER_NAME = 'odysseus-caddy'
-      CADDY_IMAGE = 'caddy:2-alpine'
+      CONTAINER_NAME = 'odysseus-caddy'.freeze
+      CADDY_IMAGE = 'caddy:2-alpine'.freeze
+
+      # The image's own CMD. Repeated here because --resume has to be appended
+      # to it: passing only --resume would drop the Caddyfile fallback that
+      # creates srv0 on a host with no autosave yet.
+      CADDY_RUN_CMD = 'caddy run --config /etc/caddy/Caddyfile --adapter caddyfile'.freeze
 
       # @param ssh [Odysseus::Deployer::SSH] SSH connection to server
       # @param docker [Odysseus::Docker::Client] Docker client
@@ -17,11 +23,43 @@ module Odysseus
       end
 
       # Ensure Caddy is running
+      #
+      # There are three states, not two: running, absent, and stopped-but-
+      # present. Docker refuses `docker run --name odysseus-caddy` while a
+      # container by that name already exists, so a stopped Caddy would
+      # otherwise fail every deploy after it, forever.
+      #
+      # A stopped container is removed rather than `docker start`ed. It
+      # carries whatever configuration it was *created* with, including its
+      # volume mount — and this branch changed Caddy's data directory from a
+      # fixed system path to one derived from the deploy user (see
+      # Odysseus::HostPaths#caddy_dir). `docker start` would silently
+      # resurrect a container mounting the old path while everything else
+      # believes it moved. Recreating always applies current configuration.
+      # Nothing is lost: certificates live in the mounted volume, and routes
+      # are re-added by the deploy that follows.
+      #
+      # Started with --resume, so the routes added through the admin API by
+      # previous deploys come back with the container rather than having to be
+      # re-added by redeploying every service on the host.
+      #
+      # If that start fails the autosave is the only new thing that could have
+      # caused it -- CADDY_IMAGE is a moving tag, so a newer Caddy can meet an
+      # autosave it will not parse. Since WebDeploy aborts when Caddy does not
+      # come up, leaving that unhandled would fail every deploy on the host
+      # until someone deleted the file by hand. The retry gives up the routes,
+      # which is exactly the behaviour that existed before --resume.
+      #
       # @return [Boolean] true if caddy is running
       def ensure_running
         return true if running?
 
+        @docker.remove(CONTAINER_NAME) if @docker.container_exists?(CONTAINER_NAME)
+
         start_caddy
+        return true if running?
+
+        restart_without_autosave
         running?
       end
 
@@ -32,29 +70,53 @@ module Odysseus
       end
 
       # Start Caddy container
-      def start_caddy
+      # @param resume [Boolean] reload the autosaved config (see #ensure_running)
+      def start_caddy(resume: true)
         # Create network if not exists (with label to protect from prune)
-        @ssh.execute("docker network create --label odysseus.managed=true odysseus 2>/dev/null || true")
+        @ssh.execute('docker network create --label odysseus.managed=true odysseus 2>/dev/null || true')
 
-        # Create data directory for certificates
-        @ssh.execute("mkdir -p /var/lib/odysseus/caddy")
+        # Create data directory for certificates, and the config directory
+        # holding the autosave. Two directories because the image sets
+        # XDG_DATA_HOME=/data and XDG_CONFIG_HOME=/config, and Caddy writes the
+        # autosave under the latter -- mounting only /data persisted the
+        # certificates and threw the routes away with the container.
+        @ssh.execute("mkdir -p #{Shellwords.escape(host_paths.caddy_dir)}")
+        @ssh.execute("mkdir -p #{Shellwords.escape(host_paths.caddy_config_dir)}")
 
         # Run Caddy with admin API enabled and persistent storage for certs
+        #
+        # The mkdir above and this mount must name the same directory, or
+        # Caddy starts against an empty one and silently has no certificates.
+        # Docker::Client interpolates `-v` values into its command line
+        # unescaped, so the directory is escaped here rather than there.
+        #
+        # The admin API is published on loopback only: it can rewrite the
+        # proxy config for every service on the host, and #api_request only
+        # ever reaches it via `curl localhost` over SSH, so nothing needs it
+        # exposed beyond the host itself. CADDY_ADMIN must stay bound to
+        # 0.0.0.0 *inside* the container regardless — that is what the
+        # published port maps to, and binding it to 127.0.0.1 there would put
+        # it behind the container's own loopback, unreachable even from the
+        # host.
         @docker.run(
           name: CONTAINER_NAME,
           image: CADDY_IMAGE,
           options: {
             service: 'odysseus-proxy',
-            ports: ['80:80', '443:443', "#{ADMIN_API_PORT}:#{ADMIN_API_PORT}"],
+            ports: ['80:80', '443:443', "127.0.0.1:#{ADMIN_API_PORT}:#{ADMIN_API_PORT}"],
             network: 'odysseus',
             restart: 'unless-stopped',
-            volumes: ['/var/lib/odysseus/caddy:/data'],
+            volumes: [
+              "#{Shellwords.escape(host_paths.caddy_dir)}:/data",
+              "#{Shellwords.escape(host_paths.caddy_config_dir)}:/config"
+            ],
             env: {
               'CADDY_ADMIN' => "0.0.0.0:#{ADMIN_API_PORT}"
             },
             labels: {
               'odysseus.managed' => 'true'
-            }
+            },
+            cmd: resume ? "#{CADDY_RUN_CMD} --resume" : CADDY_RUN_CMD
           }
         )
 
@@ -74,7 +136,7 @@ module Odysseus
         enable_tls_for_hosts(hosts, email: ssl_email) if ssl
 
         # Check if route already exists for this service
-        routes = api_request('GET', "/config/apps/http/servers/srv0/routes") || []
+        routes = api_request('GET', '/config/apps/http/servers/srv0/routes') || []
         existing_idx = routes.find_index { |r| r['@id'] == "route-#{service}" }
 
         if existing_idx
@@ -88,7 +150,8 @@ module Odysseus
           current_upstreams = routes[existing_idx].dig('handle', 0, 'upstreams') || []
           unless current_upstreams.any? { |u| u['dial'] == upstream }
             current_upstreams << { 'dial' => upstream }
-            api_request('PATCH', "/config/apps/http/servers/srv0/routes/#{existing_idx}/handle/0/upstreams", current_upstreams)
+            api_request('PATCH', "/config/apps/http/servers/srv0/routes/#{existing_idx}/handle/0/upstreams",
+                        current_upstreams)
           end
         else
           # Create new route - prepend at index 0 so it matches before default routes
@@ -98,7 +161,7 @@ module Odysseus
             upstreams: [upstream],
             healthcheck: healthcheck
           )
-          api_request('PUT', "/config/apps/http/servers/srv0/routes/0", config)
+          api_request('PUT', '/config/apps/http/servers/srv0/routes/0', config)
         end
       end
 
@@ -107,12 +170,12 @@ module Odysseus
       # @param upstream [String, nil] upstream to remove, or nil to remove entire route
       def remove_upstream(service:, upstream:)
         # Get current config
-        routes = api_request('GET', "/config/apps/http/servers/srv0/routes")
+        routes = api_request('GET', '/config/apps/http/servers/srv0/routes')
         return unless routes
 
         # Find route for this service and remove the upstream
         routes.each_with_index do |route, idx|
-          next unless route.dig('@id') == "route-#{service}"
+          next unless route['@id'] == "route-#{service}"
 
           # If no specific upstream, remove the entire route
           if upstream.nil?
@@ -195,7 +258,7 @@ module Odysseus
             service: service_name,
             hosts: hosts,
             upstreams: upstreams.map { |u| u['dial'] },
-            has_healthcheck: route.dig('handle', 0, 'health_checks').nil? ? false : true
+            has_healthcheck: !route.dig('handle', 0, 'health_checks').nil?
           }
         end
       end
@@ -240,9 +303,11 @@ module Odysseus
       # @param hosts [Array<String>] domain hosts
       # @param email [String] email for Let's Encrypt
       def enable_tls_for_hosts(hosts, email: nil)
-        # Get existing TLS config to merge with
-        existing_tls = api_request('GET', '/config/apps/tls') || {}
-        existing_policies = existing_tls.dig('automation', 'policies') || []
+        # nil means Caddy has no tls app yet, whether it answered with an error or
+        # a null body for the missing path. That distinction picks the verb below.
+        existing_tls = api_request('GET', '/config/apps/tls')
+        existing_automation = existing_tls&.dig('automation') || {}
+        existing_policies = existing_automation['policies'] || []
 
         # Collect all existing subjects
         all_subjects = existing_policies.flat_map { |p| p['subjects'] || [] }
@@ -256,20 +321,23 @@ module Odysseus
         issuer = { 'module' => 'acme' }
         issuer['email'] = email if email
 
-        # Configure TLS automation with Let's Encrypt (single policy for all domains)
-        tls_config = {
-          'automation' => {
-            'policies' => [
-              {
-                'subjects' => all_subjects,
-                'issuers' => [issuer]
-              }
-            ]
-          }
-        }
+        # One policy covering every domain, merged onto whatever else the tls app
+        # holds: writing only our automation block would drop sibling settings
+        # such as explicit certificate loaders or on_demand limits that other
+        # services on this host may depend on.
+        tls_config = (existing_tls || {}).merge(
+          'automation' => existing_automation.merge(
+            'policies' => [{ 'subjects' => all_subjects, 'issuers' => [issuer] }]
+          )
+        )
 
-        # Use PUT to create/replace TLS config
-        api_request('PUT', '/config/apps/tls', tls_config)
+        # Caddy's PUT creates and answers 409 if the key is already there; PATCH
+        # replaces and fails if it is not. Neither one is an upsert on its own.
+        if existing_tls.nil?
+          api_request('PUT', '/config/apps/tls', tls_config)
+        else
+          api_request('PATCH', '/config/apps/tls', tls_config)
+        end
 
         # Ensure HTTPS server exists and listens on 443
         ensure_https_server
@@ -277,18 +345,45 @@ module Odysseus
 
       private
 
+      def restart_without_autosave
+        @docker.remove(CONTAINER_NAME) if @docker.container_exists?(CONTAINER_NAME)
+        discard_autosave
+        start_caddy(resume: false)
+      end
+
+      # Caddy creates /config/caddy as root with mode 0700, so a non-root deploy
+      # user cannot move the file from the host -- it has to be moved from
+      # inside a container. CADDY_IMAGE is guaranteed to be on the host: it is
+      # the image that just failed to start.
+      #
+      # Renamed rather than deleted, because if --resume was not the reason
+      # Caddy failed then this file is the only copy of the host's routes.
+      # Tolerates its own failure: a Caddy that died for some other reason may
+      # have no autosave at all, and that must not abort the retry.
+      def discard_autosave
+        mount = "#{Shellwords.escape(host_paths.caddy_config_dir)}:/config"
+        @ssh.execute(
+          "docker run --rm -v #{mount} #{CADDY_IMAGE} " \
+          'mv /config/caddy/autosave.json /config/caddy/autosave.json.rejected 2>/dev/null || true'
+        )
+      end
+
+      def host_paths
+        @host_paths ||= Odysseus::HostPaths.new(@ssh)
+      end
+
       def ensure_https_server
         # Check if we have an HTTPS server configured
         servers = api_request('GET', '/config/apps/http/servers') || {}
 
-        unless servers['srv0']&.dig('listen')&.include?(':443')
-          # Add :443 to listen addresses
-          current_listen = servers.dig('srv0', 'listen') || [':80']
-          unless current_listen.include?(':443')
-            current_listen << ':443'
-            api_request('PATCH', '/config/apps/http/servers/srv0/listen', current_listen)
-          end
-        end
+        return if servers['srv0']&.dig('listen')&.include?(':443')
+
+        # Add :443 to listen addresses
+        current_listen = servers.dig('srv0', 'listen') || [':80']
+        return if current_listen.include?(':443')
+
+        current_listen << ':443'
+        api_request('PATCH', '/config/apps/http/servers/srv0/listen', current_listen)
       end
 
       def build_route_config(service:, hosts:, upstreams:, healthcheck: nil)
@@ -325,19 +420,53 @@ module Odysseus
         route
       end
 
+      # Call Caddy's admin API over SSH.
+      #
+      # curl exits 0 for HTTP errors, so the status code is appended to the
+      # response with -w and split back off here. A rejected write leaves the
+      # proxy in a state the caller must know about, so it raises; a failed read
+      # returns nil, because Caddy answers 500 for config paths that simply do
+      # not exist yet (no tls app on a freshly booted proxy, for instance).
+      #
+      # @raise [Odysseus::ProxyApiError] if a mutating request returns HTTP >= 400
       def api_request(method, path, body = nil)
-        # Build curl command to hit Caddy's admin API
-        cmd = "curl -s -X #{method} "
+        cmd = "curl -s -w '\\n%{http_code}' -X #{method} "
         cmd += "-H 'Content-Type: application/json' "
         cmd += "-d '#{body.to_json}' " if body
         cmd += "http://localhost:#{ADMIN_API_PORT}#{path}"
 
-        output = @ssh.execute(cmd)
-        return nil if output.strip.empty?
+        response_body, status = split_status(@ssh.execute(cmd))
 
-        JSON.parse(output)
+        if status && status >= 400
+          return nil if method == 'GET'
+
+          raise Odysseus::ProxyApiError, api_error_message(method, path, status, response_body)
+        end
+
+        return nil if response_body.strip.empty?
+
+        JSON.parse(response_body)
       rescue JSON::ParserError
-        output
+        response_body
+      end
+
+      # Split curl's trailing '%{http_code}' line off the response body.
+      # Returns a nil status when no status line is present.
+      def split_status(output)
+        text = output.to_s.sub(/\s+\z/, '')
+        newline_idx = text.rindex("\n")
+        trailer = newline_idx ? text[(newline_idx + 1)..] : text
+
+        return [output.to_s, nil] unless trailer&.match?(/\A\d{3}\z/)
+
+        [newline_idx ? text[0...newline_idx] : '', trailer.to_i]
+      end
+
+      def api_error_message(method, path, status, response_body)
+        message = "Caddy admin API #{method} #{path} failed with HTTP #{status}"
+        details = response_body.to_s.strip
+        message += ": #{details}" unless details.empty?
+        message
       end
     end
   end

data/lib/odysseus/command_redaction.rb

@@ -0,0 +1,38 @@
+# lib/odysseus/command_redaction.rb
+
+module Odysseus
+  # Hides secrets in a command string before it is printed.
+  #
+  # This runs on the way to the terminal only -- the command executed is always
+  # the real one. It lives in core rather than in the CLI's UI because the layer
+  # that echoes commands under --debug/-v is SSH#execute, and it echoes every
+  # command, not the handful the CLI wraps in its own redacting IO.
+  #
+  # The case that prompted it: registry login builds
+  # `echo '<password>' | docker login <server> -u <user> --password-stdin`
+  # (builder/client.rb). --password-stdin exists to keep a password off the
+  # argv, and interpolating it into `echo '...'` puts it straight back into the
+  # command string -- with no -p and no --password, so every pattern written to
+  # catch those misses it entirely.
+  module CommandRedaction
+    PLACEHOLDER = '[REDACTED]'.freeze
+
+    # Anything piped into a command that reads a secret from stdin. Matched by
+    # what the pipe FEEDS rather than by the flag, since the flag's whole point
+    # is that the secret is not one of its arguments.
+    STDIN_PIPE = /(echo\s+)(['"]).*?\2(\s*\|\s*\S*(?:docker\s+login|--password-stdin))/m
+    SHORT_FLAG = /(\s-p\s+)\S+/
+    LONG_FLAG = /(--password[= ])\S+/
+    ASSIGNMENT = /((?:KEY|TOKEN|SECRET|PASSWORD|MASTER_KEY|API_KEY|CREDENTIALS)\s*=\s*)\S+/i
+
+    # @param command [String] the command as it would be sent
+    # @return [String] the command as it is safe to print
+    def self.redact(command)
+      command.to_s
+             .gsub(STDIN_PIPE) { "#{Regexp.last_match(1)}'#{PLACEHOLDER}'#{Regexp.last_match(3)}" }
+             .gsub(SHORT_FLAG, "\\1#{PLACEHOLDER}")
+             .gsub(LONG_FLAG, "\\1#{PLACEHOLDER}")
+             .gsub(ASSIGNMENT, "\\1#{PLACEHOLDER}")
+    end
+  end
+end

data/lib/odysseus/config/parser.rb

@@ -5,6 +5,11 @@ require 'yaml'
 module Odysseus
   module Config
     class Parser
+      # Distinct versions of a service's image kept on each host. Five is enough
+      # to roll back through a bad week; the images share layers, so the cost of
+      # keeping a few is small.
+      DEFAULT_RETAIN_VERSIONS = 5
+
       # @param config_path [String] Path to deploy.yml
       def initialize(config_path)
         @config_path = config_path
@@ -15,6 +20,7 @@ module Odysseus
       # @raise [Odysseus::ConfigError] if invalid
       def parse
         raw_config = load_yaml
+        Odysseus::Plugins.load!(raw_config)
         validate!(raw_config)
         normalize(raw_config)
       rescue Psych::SyntaxError => e
@@ -46,9 +52,10 @@ module Odysseus
           env: parse_env(config['env']),
           secrets_file: config['secrets_file'],
           ssh: parse_ssh(config['ssh']),
-          accessories: parse_accessories(config['accessories']),
+          dependencies: parse_dependencies(dependencies_config(config)),
           builder: parse_builder(config['builder']),
-          registry: parse_registry(config['registry'])
+          registry: parse_registry(config['registry']),
+          retain_versions: config['retain_versions'] || DEFAULT_RETAIN_VERSIONS
         }
       end
 
@@ -96,14 +103,14 @@ module Odysseus
       end
 
       # Parse deploy-level health check (HTTP polling with threshold)
-      def parse_deploy_health_check(hc)
-        return nil unless hc
+      def parse_deploy_health_check(health_check)
+        return nil unless health_check
 
         {
-          path: hc['path'] || '/up',
-          interval: hc['interval'] || 2,
-          threshold: hc['threshold'] || 3,
-          timeout: hc['timeout'] || 5
+          path: health_check['path'] || '/up',
+          interval: health_check['interval'] || 2,
+          threshold: health_check['threshold'] || 3,
+          timeout: health_check['timeout'] || 5
         }
       end
 
@@ -179,11 +186,29 @@ module Odysseus
         }
       end
 
-      # Parse accessories config
-      def parse_accessories(accessories)
-        return {} unless accessories
+      # `accessories:` is the former name, still accepted. Both present is an
+      # error rather than a silent preference: a config with two contradictory
+      # lists should say so.
+      def dependencies_config(config)
+        if config.key?('dependencies') && config.key?('accessories')
+          raise Odysseus::ConfigError,
+                'deploy.yml has both `dependencies:` and `accessories:` — use one; ' \
+                '`accessories:` is the former name'
+        end
+
+        config['dependencies'] || config['accessories']
+      end
+
+      # Parse dependencies config — the supporting services a deploy needs
+      # (a database, a cache, a search index).
+      #
+      # Accepts the former `accessories:` key as well; the caller resolves
+      # which one was present. Kept because renaming a deploy.yml key should
+      # not be a flag day for every app repository.
+      def parse_dependencies(dependencies)
+        return {} unless dependencies
 
-        accessories.each_with_object({}) do |(name, config), acc|
+        dependencies.each_with_object({}) do |(name, config), acc|
           acc[name.to_sym] = {
             image: config['image'],
             hosts: config['hosts'],
@@ -191,14 +216,14 @@ module Odysseus
             ports: config['ports'],
             volumes: config['volumes'],
             env: parse_env(config['env']),
-            healthcheck: parse_accessory_healthcheck(config['healthcheck']),
-            proxy: parse_accessory_proxy(config['proxy'])
+            healthcheck: parse_dependency_healthcheck(config['healthcheck']),
+            proxy: parse_dependency_proxy(config['proxy'])
           }
         end
       end
 
-      # Parse accessory healthcheck
-      def parse_accessory_healthcheck(healthcheck)
+      # Parse dependency healthcheck
+      def parse_dependency_healthcheck(healthcheck)
         return nil unless healthcheck
 
         {
@@ -209,8 +234,8 @@ module Odysseus
         }
       end
 
-      # Parse accessory proxy config
-      def parse_accessory_proxy(proxy)
+      # Parse dependency proxy config
+      def parse_dependency_proxy(proxy)
         return nil unless proxy
 
         {

data/lib/odysseus/core/deploy_versioning.rb

@@ -0,0 +1,42 @@
+# lib/odysseus/core/deploy_versioning.rb
+
+module Odysseus
+  module Core
+    # The identity a deployed container carries: which version it is, which
+    # commit it came from, and when it was deployed.
+    #
+    # Shared rather than duplicated because `status`, `rollback` and image
+    # retention all read these labels, so an orchestrator that invents its own
+    # scheme becomes invisible to them. odysseus-sail-rolling did exactly that
+    # — it stamped odysseus.version with a timestamp, which meant retention's
+    # in-use guard could never match a version from the deploy log.
+    #
+    # The including class must expose @config.
+    #
+    # Both helpers are private, as they were before the extraction: they are
+    # how an orchestrator labels its own containers, not something to call on
+    # one from outside. VolumeNamespacer keeps its internals private the same
+    # way.
+    module DeployVersioning
+      private
+
+      # The version this deploy identifies. Falls back to the tag in the image
+      # reference so a caller passing --image still gets a self-describing name.
+      def deploy_version_tag(image)
+        resolved = @config[:deploy_version]
+        return resolved.version if resolved
+
+        image.to_s.split(':').last
+      end
+
+      # deployed_at replaces the timestamp odysseus.version used to hold;
+      # git_ref is only known when the version came from a commit.
+      def version_labels
+        labels = { 'odysseus.deployed_at' => Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ') }
+        resolved = @config[:deploy_version]
+        labels['odysseus.git_ref'] = resolved.ref if resolved&.ref
+        labels
+      end
+    end
+  end
+end