odysseus-cli 0.3.0 → 0.9.0

data/lib/odysseus/cli/doctor_commands.rb

@@ -0,0 +1,93 @@
+# odysseus-cli/lib/odysseus/cli/doctor_commands.rb
+#
+# `odysseus doctor`.
+# Split out of CLI so the command surface for it lives together and CLI
+# itself stays under the project's class-length budget.
+
+module Odysseus
+  module CLI
+    module DoctorCommands
+      # Read-only diagnosis of every host in the config, as the user the config
+      # names. Its own command rather than a mode of `setup`, because it lasts:
+      # "is this host usable by odysseus as my deploy user" is worth asking on
+      # any host, including one a provisioning tool built.
+      def doctor(options = {})
+        config_file = options[:config] || 'deploy.yml'
+        config = load_config(config_file)
+
+        @ui.header 'Odysseus Doctor'
+        @ui.info 'Service', config[:service]
+        @ui.info 'Deploy user', config[:ssh][:user]
+        @ui.blank
+
+        worst = :ok
+
+        executor = Odysseus::Deployer::Executor.new(config_file)
+
+        executor.host_roles.each_key do |host|
+          @ui.section host
+          ssh = connect_to_server(host, config)
+
+          begin
+            Odysseus::HostVerifier.new(ssh: ssh, config: config).verify.each do |result|
+              worst = escalate(worst, result.status)
+              render_check(result)
+            end
+          rescue StandardError => e
+            # A check failing is a Result with status: :fail, produced by
+            # HostVerifier without raising. This rescues something else: the
+            # connection itself dying mid-survey. A drop there can surface as
+            # IOError, Net::SSH::Disconnect (a RuntimeError) or
+            # Errno::EPIPE/ECONNRESET (a SystemCallError) — three branches of
+            # StandardError with no narrower ancestor in common, so nothing
+            # tighter than StandardError could catch all of them in one
+            # rescue. A narrower rescue would also reintroduce the defect
+            # this exists to fix: one host's failure aborting the survey for
+            # everyone after it. The risk of that width is masking a genuine
+            # HostVerifier bug as "host unreachable"; naming the exception's
+            # own class and message in the detail is what keeps a
+            # NoMethodError legible as a bug rather than indistinguishable
+            # from a dropped connection.
+            worst = escalate(worst, :fail)
+            render_check(
+              Odysseus::HostVerifier::Result.new(
+                check: :reachable, status: :fail, detail: "#{host}: #{e.class}: #{e.message}"
+              )
+            )
+          ensure
+            ssh.close
+          end
+        end
+
+        @ui.blank
+        case worst
+        when :fail then exit 1
+        when :warn then @ui.warn 'Deploys will work, but read the warnings above.'
+        else @ui.success 'This host is ready.'
+        end
+      rescue Odysseus::Error => e
+        @ui.error e.message
+        exit 1
+      end
+
+      private
+
+      def render_check(result)
+        line = "#{result.check}: #{result.detail}"
+
+        case result.status
+        when :ok then @ui.step_ok line
+        when :warn then @ui.warn line
+        else @ui.step_fail line
+        end
+      end
+
+      # :fail beats :warn beats :ok, so one bad check decides the exit code
+      # however many good ones surround it.
+      def escalate(current, status)
+        order = { ok: 0, warn: 1, fail: 2 }
+        order[status] > order[current] ? status : current
+      end
+    end
+  end
+end

data/lib/odysseus/cli/interactive_commands.rb

@@ -0,0 +1,198 @@
+# odysseus-cli/lib/odysseus/cli/interactive_commands.rb
+#
+# `odysseus app shell`, `odysseus app console` and `odysseus dependency shell`.
+# These three are the commands that hand a terminal over: they build an ssh
+# command line and run it locally rather than going through the Docker client,
+# because the session needs the caller's own tty. Split out of CLI so they live
+# together and CLI itself stays under the project's class-length budget.
+#
+# Two shells stand between this file and the container, and each needs its own
+# quoting. Escaping for one and not the other is how these commands came to
+# break on an env value with a space in it.
+#
+# Those env values are no longer in the string at all — they go in an env file
+# on the host, and only its path is named here — but the console command, the
+# image and the SSH key paths still are, so both layers still matter.
+
+require 'shellwords'
+
+module Odysseus
+  module CLI
+    module InteractiveCommands
+      # App shell
+      def app_shell(server, options = {})
+        config_file = options[:config] || 'deploy.yml'
+        role = (options[:role] || 'web').to_sym
+        config = load_config(config_file)
+        image = running_image(server, config, role)
+        session_header('App Shell', server: server, role: role, image: image, command: '/bin/sh')
+
+        with_container_env(server, config, config_file) do |env_file|
+          remote = remote_command(['docker', 'run', '-it', '--rm', '--network', 'odysseus',
+                                   *env_file_args(env_file), image, '/bin/sh'])
+          run_interactive!(ssh_command(config, server, remote))
+        end
+      rescue Odysseus::Error => e
+        @ui.error e.message
+        exit 1
+      end
+
+      # App console
+      def app_console(server, options = {})
+        config_file = options[:config] || 'deploy.yml'
+        role = (options[:role] || 'web').to_sym
+        console_cmd = options[:cmd] || '/bin/sh'
+        config = load_config(config_file)
+        image = running_image(server, config, role)
+        # Read before the env file is written: a --cmd that cannot be parsed is
+        # not worth putting a file of secrets on the host for.
+        words = console_words(console_cmd)
+        session_header('App Console', server: server, role: role, image: image, command: console_cmd)
+
+        with_container_env(server, config, config_file) do |env_file|
+          remote = remote_command(['docker', 'run', '-it', '--rm', '--network', 'odysseus',
+                                   *env_file_args(env_file), image, *words])
+          run_interactive!(ssh_command(config, server, remote))
+        end
+      rescue Odysseus::Error => e
+        @ui.error e.message
+        exit 1
+      end
+
+      # Dependency shell
+      def dependency_shell(server, options = {})
+        config_file = options[:config] || 'deploy.yml'
+        name = require_name!(options)
+
+        config = load_config(config_file)
+        service_name = "#{config[:service]}-#{name}"
+
+        ssh = connect_to_server(server, config)
+        begin
+          docker = Odysseus::Docker::Client.new(ssh)
+          containers = docker.list(service: service_name)
+
+          if containers.empty?
+            @ui.error "No running containers found for #{service_name}"
+            exit 1
+          end
+
+          container_id = containers.first['ID']
+        ensure
+          ssh.close
+        end
+
+        remote = remote_command(['docker', 'exec', '-it', container_id, '/bin/sh'])
+        run_interactive!(ssh_command(config, server, remote))
+      rescue Odysseus::Error => e
+        @ui.error e.message
+        exit 1
+      end
+
+      private
+
+      # What these two print before the terminal goes away. `app shell web1`
+      # used to print nothing at all: the first thing you saw was `/app $`, from
+      # which the host, the role and the build serving it are all unreadable.
+      #
+      # The last line is the one worth the space. These commands `docker run` a
+      # new container from the image that is serving, not `docker exec` into the
+      # container taking traffic, and a shell prompt inside a container invites
+      # exactly the opposite assumption — that a file written or a process
+      # killed here lands on the running app. It does neither, and the container
+      # goes when the session does.
+      #
+      # It all goes to stderr. The session's own stdout is the caller's:
+      # `app console --cmd "rails runner 'puts Thing.count'" > count` is a
+      # reasonable way to read a value out of a deployment, and a header in that
+      # file would be a bug. Diagnostics go where diagnostics go.
+      def session_header(title, server:, role:, image:, command:)
+        @ui.header title, io: $stderr
+        @ui.info 'Server', server, io: $stderr
+        @ui.info 'Role', role, io: $stderr
+        @ui.info 'Image', image, io: $stderr
+        @ui.info 'Command', command, io: $stderr
+        @ui.step 'New container from that image: the running app is untouched, and this one is discarded on exit.',
+                 io: $stderr
+        @ui.blank io: $stderr
+      end
+
+      # Layer 2, the REMOTE shell: ssh hands this string to the login shell on
+      # the host, which splits it into words. Escaping here is what keeps an
+      # argument containing a space — `--cmd "rails runner 'puts 1'"`, say —
+      # one argument, instead of docker reading part of it as the image name.
+      def remote_command(words)
+        Shellwords.join(words)
+      end
+
+      # Layer 1, the LOCAL shell: `system` with a single string runs it through
+      # /bin/sh here. Every word is escaped for that shell, `remote` included —
+      # it has to survive as one word, or the local shell takes what is inside
+      # it as commands of its own.
+      def ssh_command(config, server, remote)
+        keys = config[:ssh][:keys].flat_map { |k| ['-i', File.expand_path(k)] }
+        Shellwords.join(['ssh', *keys, '-t', "#{config[:ssh][:user]}@#{server}", remote])
+      end
+
+      # Holds the container's environment — env.clear and env.secret both, the
+      # same as a deploy injects — in a 0600 file on the host for as long as the
+      # session lasts, and yields its path. Docker::Client owns the file: where
+      # it lives, how it is permissioned and when it goes away.
+      #
+      # These values used to be `-e KEY=VALUE` in the command string, which is
+      # where `ps` on the deploy target reads them from. Nothing but a path goes
+      # there now, so a DATABASE_URL is no longer legible to every user on the
+      # box for the length of the session.
+      #
+      # The file is removed when the block ends, however it ends: a session that
+      # exits non-zero, an ssh that never connected, and Ctrl-C all pass back
+      # through with_env_file's ensure. What that cannot cover is this process
+      # being killed outright (SIGKILL, or the machine going down): no ensure
+      # runs, so the file stays until something else removes it. It is mode 0600
+      # inside that connection's env directory (HostPaths#env_dir —
+      # /var/lib/odysseus/env for root, $HOME/.odysseus/env otherwise), which
+      # write_env_file chmods to 0700 for every connection, so no other user on
+      # the host can read it — but it is a file of secrets that nobody is
+      # coming back for: the next deploy or one-off run writes its own rather
+      # than tidying this one.
+      def with_container_env(server, config, config_file, &)
+        ssh = connect_to_server(server, config)
+
+        begin
+          docker = Odysseus::Docker::Client.new(ssh)
+          docker.with_env_file(build_environment(config, config_file, ssh), &)
+        ensure
+          ssh.close
+        end
+      end
+
+      # with_env_file yields nil when there is no environment to write, so a
+      # config with no env at all does not get a flag pointing at nothing.
+      def env_file_args(env_file)
+        env_file ? ['--env-file', env_file] : []
+      end
+
+      # --cmd is a command line ("rails c"), so split it into words the way a
+      # shell would before each is escaped: escaping it whole would ask docker
+      # to exec a program literally named "rails c". Quoting the caller got
+      # wrong is reported rather than passed on as a command that cannot parse.
+      def console_words(console_cmd)
+        Shellwords.split(console_cmd)
+      rescue ArgumentError => e
+        @ui.error "Could not read --cmd #{console_cmd.inspect}: #{e.message}"
+        exit 1
+      end
+
+      # `system` returns false when the command exits non-zero and nil when it
+      # could not be run at all; both were discarded here, so a refused ssh, a
+      # missing image and a failed docker run all reported success. ssh exits
+      # with the remote command's own status, so pass that on when we have it.
+      def run_interactive!(command)
+        return if system(command)
+
+        status = $?&.exitstatus
+        exit(status.nil? || status.zero? ? 1 : status)
+      end
+    end
+  end
+end

data/lib/odysseus/cli/rollback_commands.rb

@@ -0,0 +1,107 @@
+# odysseus-cli/lib/odysseus/cli/rollback_commands.rb
+#
+# `odysseus rollback [VERSION]` and `odysseus rollback --list`.
+# Split out of CLI so the command surface for rollback lives together and
+# CLI itself stays under the project's class-length budget.
+
+module Odysseus
+  module CLI
+    module RollbackCommands
+      # Rollback command
+      def rollback(options = {})
+        config_file = options[:config] || 'deploy.yml'
+        verbose = options[:verbose] || @ui.debug?
+
+        @ui.header 'Odysseus Rollback'
+
+        config = load_config(config_file)
+        executor = Odysseus::Deployer::Executor.new(config_file, verbose: verbose)
+
+        return rollback_list(executor, config) if options[:list]
+
+        plan = @ui.spin_step('Checking what every host can run') do
+          executor.rollback_plan(version: options[:version])
+        end
+
+        @ui.blank
+        @ui.info 'Service', config[:service]
+        @ui.info 'Rolling back to', "#{config[:image]}:#{plan.version}"
+        @ui.info 'Commit', plan.ref if plan.ref
+        @ui.warn rollback_approximate_warning(options[:version]) if plan.approximate
+        @ui.blank
+
+        start_time = Time.now
+
+        @ui.stream_steps(title: 'Rolling back service') do
+          executor.rollback_all(plan)
+        end
+
+        duration = (Time.now - start_time).round(1)
+        @ui.success("Rollback complete in #{duration}s")
+      rescue Odysseus::Error => e
+        @ui.step_fail e.message
+        exit 1
+      end
+
+      private
+
+      # rollback --list: what each host has, without changing anything.
+      # Reads only the hosts, so it works without a git repository.
+      def rollback_list(executor, config)
+        survey = @ui.spin_step('Reading versions from hosts') { executor.version_survey }
+
+        @ui.blank
+        @ui.info 'Service', config[:service]
+        @ui.blank
+
+        survey.each do |host_versions|
+          @ui.section host_versions.host
+          @ui.info 'Serving', host_versions.current || '(nothing running)'
+
+          rows = rollback_rows(host_versions)
+          if rows.empty?
+            @ui.step '(no deploy history on this host)'
+          else
+            @ui.table(headers: %w[Version Deployed Ref Deployer Image], rows: rows)
+          end
+          @ui.blank
+        end
+      end
+
+      # One row per distinct version, most recently deployed first. A version
+      # deployed repeatedly is reported once, at its latest deploy time.
+      #
+      # Ordered the same way RollbackPlanner#logged_versions ranks
+      # candidates — newest entry first, then dedupe keeping the first
+      # (newest) occurrence of each version. That is candidate order, not
+      # the planner's chosen target: RollbackPlanner#previous_version then
+      # skips candidates that are already serving somewhere or missing on
+      # some host, so a plain `odysseus rollback` can pick a version below
+      # the top row shown here. A hash keyed by version and reassigned in
+      # history order looks equivalent but is not: Ruby keeps a reassigned
+      # key at its *first* insertion position, so it orders by each
+      # version's first deploy rather than its latest.
+      def rollback_rows(host_versions)
+        host_versions.history.sort_by(&:at).reverse.uniq(&:version).map do |e|
+          [e.version, e.at, e.ref, e.deployer,
+           host_versions.available?(e.version) ? 'present' : 'missing']
+        end
+      end
+
+      # `approximate` on a RollbackPlan means only "no host had a deploy log" —
+      # not that the requested version itself is uncertain. When the operator
+      # named a version explicitly, no ordering was inferred at all, so it
+      # would be misleading to call the ordering approximate; there is simply
+      # no record of what has run here.
+      def rollback_approximate_warning(requested_version)
+        if requested_version
+          'No host has a deploy log for this service, so there is no record of what has been ' \
+            'deployed here'
+        else
+          'No host has a deploy log, so the previous version came from image creation time ' \
+            'and the ordering is approximate'
+        end
+      end
+    end
+  end
+end

data/lib/odysseus/cli/setup_commands.rb

@@ -0,0 +1,176 @@
+# odysseus-cli/lib/odysseus/cli/setup_commands.rb
+#
+# `odysseus setup`.
+# Split out of CLI for the same reason as DoctorCommands: cli.rb is close to
+# its Metrics/ClassLength budget.
+
+module Odysseus
+  module CLI
+    module SetupCommands
+      # The Ubuntu cloud image's own default user, so a stock image works
+      # untouched by the time --as would otherwise be needed.
+      DEFAULT_IDENTITY = 'ubuntu'.freeze
+
+      # Prepares every host in the config so odysseus can deploy to it as a
+      # non-root user: creates the deploy user, its group, its
+      # authorized_keys and its state dir. Its own command rather than a mode
+      # of `doctor`, because doctor only reads; this one changes the host.
+      #
+      # Connects as the bootstrap identity (--as, default 'ubuntu') rather
+      # than config[:ssh][:user] -- that deploy user existing is the point of
+      # this command, so it cannot be assumed to exist yet, let alone be
+      # reachable, before setup has run.
+      #
+      # The public key to install is resolved once, before any host is
+      # touched -- before even the first connection opens. A created user
+      # with no way to log in is the worst outcome this command has, and
+      # resolving first means that failure can never happen after host 1 of
+      # 3 is already changed: the whole run refuses, or none of it does.
+      def setup(options = {})
+        config_file = options[:config] || 'deploy.yml'
+        config = load_config(config_file)
+        identity = options[:as] || DEFAULT_IDENTITY
+        # Same idiom deploy, build and pussh use: -v or --debug, either one.
+        verbose = options[:verbose] || @ui.debug?
+
+        refuse_root_deploy_user!(config)
+        keys = Odysseus::Setup::PublicKey.resolve(keys: config[:ssh][:keys], explicit: Array(options[:key]))
+
+        @ui.header 'Odysseus Setup'
+        @ui.info 'Service', config[:service]
+        @ui.info 'Bootstrap identity', identity
+        @ui.blank
+
+        worst = :ok
+        executor = Odysseus::Deployer::Executor.new(config_file)
+
+        executor.host_roles.each_key do |host|
+          @ui.section host
+          ssh = connect_as(identity, host, config, verbose: verbose)
+
+          begin
+            escalation = Odysseus::Setup::Escalation.new(ssh: ssh, as: identity)
+            preparer = Odysseus::Setup::Preparer.new(ssh: ssh, config: config, escalation: escalation, keys: keys)
+
+            preparer.prepare.each do |result|
+              worst = escalate(worst, result.status)
+              render_result(result)
+            end
+          rescue Odysseus::SSHAuthenticationError => e
+            # The default identity is a guess -- a good one on a stock cloud
+            # image, wrong on anything else -- and the operator has no way to
+            # know which flag fixes it unless this says so. The spec requires
+            # a host with neither a usable ubuntu nor root SSH to be refused
+            # with an error naming both flags.
+            worst = escalate(worst, :fail)
+            render_result(
+              Odysseus::Setup::Preparer::Result.new(
+                step: :connection, status: :fail,
+                detail: "#{host}: #{e.message} Setup connected as #{identity}; pass --as root " \
+                        'if root SSH is enabled, or --as USER for whichever identity can log in.'
+              )
+            )
+          rescue StandardError => e
+            # Mirrors DoctorCommands#doctor's rescue: a step failing is a
+            # Result with status: :fail, produced by Preparer without
+            # raising. This rescues the connection itself dying mid-run,
+            # which can surface as IOError, Net::SSH::Disconnect (a
+            # RuntimeError) or Errno::EPIPE/ECONNRESET (a SystemCallError) --
+            # three branches of StandardError with no narrower ancestor in
+            # common. Narrower would also reintroduce the defect this fixes:
+            # one host's failure aborting setup for every host after it.
+            worst = escalate(worst, :fail)
+            render_result(
+              Odysseus::Setup::Preparer::Result.new(
+                step: :connection, status: :fail, detail: "#{host}: #{e.class}: #{e.message}"
+              )
+            )
+          ensure
+            ssh.close
+          end
+        end
+
+        @ui.blank
+        case worst
+        when :fail then exit 1
+        when :warn then @ui.warn 'Setup finished, but read the warnings above.'
+        else @ui.success 'Hosts are ready.'
+        end
+      rescue Odysseus::Error => e
+        @ui.error e.message
+        exit 1
+      end
+
+      private
+
+      # `ssh.user: root` is not a case setup half-supports -- it is refused
+      # by name, before the key is even resolved. Deploying as root already
+      # works today with no setup at all (root needs no user, no group, no
+      # authorized_keys of its own), so every step setup would otherwise run
+      # is either a no-op mistaken for progress or, worse, a mutation of
+      # root's own account (`usermod -aG docker root`) that the command's
+      # "it never modifies root's configuration" promise forbids outright.
+      # Refusing here, rather than growing setup a root-flavoured code path,
+      # is the point: this command's job ends at getting one non-root user
+      # ready, not at supporting every identity a deploy could use.
+      #
+      # `ssh.user` (the identity being created) and `--as` (the bootstrap
+      # identity connected as, which defaults to ubuntu and may legitimately
+      # be root) name different things; only the former is refused here.
+      def refuse_root_deploy_user!(config)
+        return unless config[:ssh][:user] == 'root'
+
+        raise Odysseus::SetupError,
+              '`ssh.user` is `root`: setup exists to enable non-root deploys, root needs no ' \
+              'preparation, and deploying as root already works with no setup at all. Change ' \
+              '`ssh.user` in deploy.yml to the non-root user you want to deploy as.'
+      end
+
+      # :changed renders distinctly from :ok (step_info's copper arrow, not
+      # step_ok's mint check) so a re-run visibly reports what it did versus
+      # what was already correct -- the point of running it twice.
+      def render_result(result)
+        line = "#{result.step}: #{result.detail}"
+
+        case result.status
+        when :ok then @ui.step_ok line
+        when :changed then @ui.step_info line
+        when :warn then @ui.warn line
+        else @ui.step_fail line
+        end
+      end
+
+      # :fail beats :warn beats :ok/:changed, so one bad step decides the
+      # exit code however many good ones surround it. :changed ranks with
+      # :ok, not above it: it is still a step that finished cleanly, and only
+      # a :fail may set a non-zero exit.
+      def escalate(current, status)
+        order = { ok: 0, changed: 0, warn: 1, fail: 2 }
+        order[status] > order[current] ? status : current
+      end
+
+      # setup's connections differ from connect_to_server's in two ways at
+      # once: the identity (the bootstrap --as, not config[:ssh][:user] --
+      # see #setup) and use_tailscale. Both are setup's alone among the
+      # eleven callers of connect_to_server, so this stays a private helper
+      # here rather than a second keyword grafted onto a method every other
+      # command already uses correctly.
+      #
+      # use_tailscale: false because connect_to_server's hardcoded true
+      # (cli.rb) makes SSH append Tailscale troubleshooting advice to every
+      # connection timeout (deployer/ssh.rb). setup targets exactly the
+      # fresh hosts that do not have Tailscale yet, so on the one command
+      # where a timeout is most likely, that advice would be actively
+      # misleading.
+      def connect_as(identity, host, config, verbose: false)
+        Odysseus::Deployer::SSH.new(
+          host: host,
+          user: identity,
+          keys: config[:ssh][:keys],
+          use_tailscale: false,
+          verbose: verbose
+        )
+      end
+    end
+  end
+end