kitchen-rackspace 0.21.2 → 0.22.1

data/helpers/dump_image_list.rb

@@ -1,86 +1,117 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Regenerates data/images.json from the images a Rackspace account can see.
+#
+# The driver maps a Test Kitchen platform name (`ubuntu-22.04`) to a Rackspace
+# image ID. That mapping lives in data/images.json and has to be refreshed
+# whenever Rackspace publishes new base images.
+#
+# Usage:
+#
+#   export RACKSPACE_USERNAME=myuser
+#   export RACKSPACE_API_KEY=myapikey
+#   export RACKSPACE_REGION=ord            # optional, defaults to dfw
+#
+#   bundle exec ruby helpers/dump_image_list.rb          # human-readable table
+#   bundle exec ruby helpers/dump_image_list.rb --json   # data/images.json content
+#
+# Run it under Bundler. fog-rackspace only loads against the fog-core version
+# this gem pins; on a newer fog-core, `require "fog/rackspace"` raises NameError
+# on its "CDN v2" service name.
+#
+# Image IDs are per-region, so regenerate from the region most users build in.
+
 require "fog/rackspace"
 require "json" unless defined?(JSON)
 
-def whole?(x) # rubocop:disable Naming/UncommunicativeMethodParamName
-  (x - x.floor) < 1e-6
-end
-
-i_care_about = {
-  "Arch Linux (PVHVM)" => %w{arch arch-2016 arch-2016.8},
-  "CentOS 7 (PVHVM)" => %w{centos centos-7},
-  "CentOS 6 (PVHVM)" => %w{centos-6},
-  "CoreOS (Stable)" => %w{coreos coreos-stable},
-  "CoreOS (Beta)" => %w{coreos-beta},
-  "CoreOS (Alpha)" => %w{coreos-alpha},
-  "Debian 8 (Jessie) (PVHVM)" => %w{debian debian-8},
-  "Debian 7 (Wheezy) (PVHVM)" => %w{debian-7},
-  "Debian Testing (Stretch) (PVHVM)" => %w{debian-testing},
-  "Debian Unstable (Sid) (PVHVM)" => %w{debian-unstable},
-  "Fedora 25 (PVHVM)" => %w{fedora fedora-25},
-  "Fedora 24 (PVHVM)" => %w{fedora-24},
-  "FreeBSD 11 (PVHVM)" => %w{freebsd freebsd-11},
-  "FreeBSD 10 (PVHVM)" => %w{freebsd-10},
-  "Gentoo 15.3 (PVHVM)" => %w{gentoo gentoo-15 gentoo-15.3},
-  "OpenSUSE Leap 42 (PVHVM)" => %w{opensuse opensuse-42},
-  "Scientific Linux 7 (PVHVM)" => %w{scientific scientific-7},
-  "Scientific Linux 6 (PVHVM)" => %w{scientific-6},
-  "Ubuntu 16.04 LTS (Xenial Xerus) (PVHVM)" => %w{ubuntu ubuntu-16 ubuntu-16.04},
-  "Ubuntu 14.04 LTS (Trusty Tahr) (PVHVM)" => %w{ubuntu-14 ubuntu-14.04},
-  "Ubuntu 12.04 LTS (Precise Pangolin) (PVHVM)" => %w{ubuntu-12 ubuntu-12.04},
-  "Vyatta Network OS 6.7R12" => %w{vyatta vyatta-6 vyatta-6.7 vyatta-6.7R12},
-  "Windows Server 2012 R2" => %w{windows windows-2012 windows-2012R2},
-  "Windows Server 2008 R2 SP1" => %w{windows-2008
-                                     windows-2008R2
-                                     windows-2008R2SP1},
-}
-
-names_to_clean = {
+# Rackspace reports the distro in OpenStack metadata using reverse-DNS names.
+# Map the ones that do not reduce to a sensible short name on their own.
+DISTRO_NAMES = {
   "com.microsoft.server" => "windows",
-  "org.fedoraproject" => "fedora",
   "org.archlinux" => "arch",
+  "org.fedoraproject" => "fedora",
   "org.scientificlinux" => "scientific",
-}
+}.freeze
 
-compute = Fog::Compute.new(provider: "Rackspace",
-                           rackspace_username: ENV["RACKSPACE_USERNAME"],
-                           rackspace_api_key: ENV["RACKSPACE_API_KEY"],
-                           rackspace_region: "ORD")
+# Builds the platform aliases for one image.
+#
+# An image advertising Ubuntu 22.04 yields "ubuntu-22.04", plus "ubuntu-22" as
+# a convenience. The bare distro name ("ubuntu") is assigned separately, to the
+# newest version found, so that it does not depend on iteration order.
+#
+# @param image [Fog::Compute::RackspaceV2::Image] the image to describe
+# @return [Array(String, String, Array<String>), nil] distro, version, and
+#   aliases, or nil when the image carries no usable OpenStack metadata
+def describe(image)
+  meta = image.metadata
+  distro_id = meta["org.openstack__1__os_distro"]
+  version = meta["org.openstack__1__os_version"]
+  return nil if distro_id.nil? || version.nil?
 
-aliases = i_care_about.values.flatten
-res = aliases.each_with_object({}) do |a, hsh|
-  raise "Alias '#{a}' was listed twice" if hsh.include?(a)
+  distro = DISTRO_NAMES.fetch(distro_id) { distro_id.split(".").last }
 
-  hsh[a] = nil
-  hsh
+  aliases = ["#{distro}-#{version}"]
+  # "ubuntu-22" alongside "ubuntu-22.04", but not "centos-7" twice.
+  major = version.split(".").first
+  aliases << "#{distro}-#{major}" if major != version
+
+  [distro, version, aliases]
+end
+
+# Sorts version strings numerically, so that 22.04 beats 8 and 9 beats 10 is
+# never asserted. Non-numeric segments (Vyatta's "6.7R12") sort last.
+#
+# @param version [String] an OS version
+# @return [Array<Integer>] a comparable key
+def version_key(version)
+  version.split(".").map(&:to_i)
 end
 
-compute.images.select { |i| i_care_about.key?(i.name) }.each do |img|
-  image_metadata = img.metadata
+compute = Fog::Compute.new(
+  provider: "Rackspace",
+  rackspace_username: ENV.fetch("RACKSPACE_USERNAME"),
+  rackspace_api_key: ENV.fetch("RACKSPACE_API_KEY"),
+  rackspace_region: ENV.fetch("RACKSPACE_REGION", "dfw"),
+  version: :v2
+)
 
-  if image_metadata["org.openstack__1__os_distro"] &&
-      image_metadata["org.openstack__1__os_version"]
+images = compute.images.to_a
+abort "No images visible to this account." if images.empty?
 
-    distro_id = image_metadata["org.openstack__1__os_distro"]
-    version = image_metadata["org.openstack__1__os_version"]
+if ARGV.include?("--json")
+  mapping = {}
+  newest = {}
 
-    distro = if names_to_clean.include?(distro_id)
-               names_to_clean[distro_id]
-             else
-               distro_id.split(".").last
-             end
+  images.each do |image|
+    described = describe(image)
+    next if described.nil?
 
-    res["#{distro}-#{version}"] = img.id
+    distro, version, aliases = described
+    aliases.each { |a| mapping[a] = image.id }
 
-    # if it's a whole number non-zero version, also add
-    # a dot-zero (centos-7 vs centos-7.0)
-    res["#{distro}-#{version}.0"] = img.id if version != "0" && version =~ /^\s*\d+\s*$/
+    current = newest[distro]
+    if current.nil? || (version_key(version) <=> version_key(current[:version])) == 1
+      newest[distro] = { version:, id: image.id }
+    end
   end
 
-  i_care_about[img.name].each { |a| res[a] = img.id }
-  i_care_about.delete(img.name)
-end
+  # The bare distro name points at the newest version of that distro.
+  newest.each { |distro, info| mapping[distro] = info[:id] }
+
+  puts JSON.pretty_generate(mapping.sort.to_h)
+else
+  rows = images.map do |image|
+    described = describe(image)
+    [image.id, image.name, described ? described[2].join(", ") : "-"]
+  end.sort_by { |row| row[1] }
 
-raise "Couldn't find some images we expected: #{i_care_about.keys}" unless i_care_about.empty?
+  widths = [0, 1, 2].map { |i| rows.map { |r| r[i].length }.max }
+  header = ["IMAGE ID", "NAME", "PLATFORM NAMES"]
+  widths = widths.each_with_index.map { |w, i| [w, header[i].length].max }
 
-# sort these to make them pretty
-puts JSON.pretty_generate(res.sort.to_h)
+  puts header.each_with_index.map { |h, i| h.ljust(widths[i]) }.join("  ")
+  puts widths.map { |w| "-" * w }.join("  ")
+  rows.each { |row| puts row.each_with_index.map { |c, i| c.ljust(widths[i]) }.join("  ") }
+  warn "\n#{rows.count} images. Re-run with --json to regenerate data/images.json."
+end

data/kitchen-rackspace.gemspec

@@ -10,16 +10,18 @@ Gem::Specification.new do |spec|
   spec.description   = "A Test Kitchen Rackspace driver"
   spec.summary       = "A Test Kitchen Rackspace driver built on Fog"
   spec.homepage      = "https://github.com/test-kitchen/kitchen-rackspace"
-  spec.license       = "Apache"
+  spec.license       = "Apache-2.0"
 
   spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = %w{lib}
 
   spec.required_ruby_version = ">= 3.1"
 
   spec.add_dependency "fog-rackspace", "~> 0.1.6"
-  spec.add_dependency "fog-core", ">= 1.35", "< 2.6.1"
-  spec.add_dependency "test-kitchen", ">= 1.1", "< 5.0"
+  # fog-rackspace 0.1.6 registers a service literally named "CDN v2"; fog-core
+  # 2.3.0+ passes that through const_defined?, which rejects it as an invalid
+  # constant name, so `require "fog/rackspace"` raises NameError.
+  spec.add_dependency "fog-core", ">= 1.35", "< 2.3"
+  spec.add_dependency "test-kitchen", ">= 3.0", "< 5.0"
 end

data/lib/kitchen/driver/rackspace.rb

@@ -4,12 +4,35 @@ require "kitchen"
 require "etc" unless defined?(Etc)
 require "socket" unless defined?(Socket)
 require "json" unless defined?(JSON)
+require "time" unless defined?(Time.now.iso8601)
+require_relative "rackspace_version"
 
 module Kitchen
+  # Test Kitchen's driver plugins.
   module Driver
-    class Rackspace < Kitchen::Driver::SSHBase
+    # Test Kitchen driver for Rackspace Cloud Servers.
+    #
+    # Creates a Cloud Server for the instance under test, waits for it to
+    # become reachable, and destroys it afterwards. Talking to the server is
+    # the transport's job; this driver only tells Test Kitchen where it is and
+    # who to log in as.
+    #
+    # Rackspace can run post-build automation -- RackConnect and Managed
+    # Service Level -- that keeps modifying a server after it first reports
+    # +ready+, including changing its public address. Set +rackconnect_wait+
+    # or +servicelevel_wait+ so the driver waits for that to finish before
+    # handing the server over, or the transport will connect to an address
+    # that is about to change.
+    class Rackspace < Kitchen::Driver::Base
+      kitchen_driver_api_version 2
+
+      plugin_version Kitchen::Driver::RACKSPACE_VERSION
+
+      # Server states Rackspace reports for a server that is up and reachable.
+      LIVE_STATES = %w{ACTIVE}.freeze
+
       default_config :version, "v2"
-      default_config :flavor_id, "performance1-1"
+      default_config :flavor_id, "general1-2"
       default_config :username, "root"
       default_config :port, "22"
       default_config :wait_for, 600
@@ -51,11 +74,27 @@ module Kitchen
       required_config :image_id
       required_config :public_key_path
 
+      # Sets up the driver and applies +wait_for+ as fog's global timeout.
+      #
+      # +Fog.timeout+ is process-wide, so the last driver constructed wins if
+      # several are in play.
+      #
+      # @param config [Hash] the driver configuration
       def initialize(config)
         super
         Fog.timeout = config[:wait_for].to_i
       end
 
+      # Creates the Cloud Server and waits until it can be logged into.
+      #
+      # Waits for the server to report ready, then optionally for RackConnect
+      # and Managed Service Level automation, then for the transport to accept
+      # a connection.
+      #
+      # @param state [Hash] mutable instance state; gains +server_id+,
+      #   +hostname+, +username+, and +port+
+      # @return [void]
+      # @raise [Kitchen::ActionFailed] if the Rackspace API rejects the build
       def create(state)
         server = create_server
         state[:server_id] = server.id
@@ -65,11 +104,18 @@ module Kitchen
         rackconnect_check(server) if config[:rackconnect_wait]
         servicelevel_check(server) if config[:servicelevel_wait]
         state[:hostname] = hostname(server)
+        state[:username] = config[:username]
+        state[:port] = config[:port] if config[:port]
         tcp_check(state)
       rescue Fog::Errors::Error, Excon::Errors::Error => ex
         raise ActionFailed, ex.message
       end
 
+      # Destroys the Cloud Server, if one was created.
+      #
+      # @param state [Hash] mutable instance state; +server_id+ and +hostname+
+      #   are removed
+      # @return [void]
       def destroy(state)
         return if state[:server_id].nil?
 
@@ -80,18 +126,24 @@ module Kitchen
         state.delete(:hostname)
       end
 
+      # Looks up the base image for the platform under test.
+      #
+      # @return [String, nil] the Rackspace image ID, or nil when the platform
+      #   is not one the bundled image list knows about, in which case
+      #   +image_id+ must be set explicitly
       def default_image
         images[instance.platform.name]
       end
 
-      # Generate what should be a unique server name up to 63 total chars
-      # Base name:    15
-      # Username:     15
-      # Hostname:     23
-      # Random string: 7
-      # Separators:    3
-      # ================
-      # Total:        63
+      # Generates a server name that is unique per run and fits Rackspace's
+      # 63-character limit.
+      #
+      # The budget is spent as base name 15, username 15, hostname 23, random
+      # suffix 7, and three separators, for 63 exactly. Each part is stripped
+      # of non-word characters and truncated to its share, so a long login or
+      # hostname cannot push the result over.
+      #
+      # @return [String] e.g. +default-alice-buildbox01-x7f2p9q+
       def default_name
         [
           instance.name.gsub(/\W/, "")[0..14],
@@ -101,8 +153,85 @@ module Kitchen
         ].join("-")
       end
 
+      # Reports what Rackspace currently thinks of the server.
+      #
+      # @param state [Hash] instance state naming the server
+      # @return [Hash] a Test Kitchen status hash, or the base implementation's
+      #   answer when there is no server or Rackspace does not know it
+      def status(state)
+        return super unless state[:server_id]
+
+        server = lookup_server(state[:server_id])
+        return super unless server
+
+        {
+          live: LIVE_STATES.include?(server.state),
+          state: server.state,
+          source: "driver",
+          resource_id: state[:server_id],
+          message: "Rackspace reports the server as #{server.state}",
+          checked_at: Time.now.utc.iso8601,
+        }
+      end
+
+      # Checks the configuration for the mistakes that only show up as a
+      # confusing failure part way through +create+.
+      #
+      # @param state [Hash] instance state; accepted for the Test Kitchen hook
+      #   signature and not read
+      # @return [Boolean] true when a problem was reported
+      def doctor(state) # rubocop:disable Lint/UnusedMethodArgument
+        problems = []
+
+        if config[:image_id].nil?
+          problems << "No image_id is set and #{instance.platform.name} is not " \
+                      "in the bundled image list. Set image_id explicitly."
+        end
+
+        if config[:public_key_path].nil?
+          problems << "No public key was found in ~/.ssh. Set public_key_path " \
+                      "to the key Rackspace should install on the server."
+        end
+
+        problems.concat(credential_problems)
+
+        problems.each { |problem| warn(problem) }
+        !problems.empty?
+      end
+
       private
 
+      # Confirms the configured credentials can actually talk to Rackspace,
+      # which is cheaper to learn here than half way through a converge.
+      #
+      # Listing servers is the cheapest authenticated call fog-rackspace
+      # offers: +GET /servers+ returns only an ID and a name per server, and
+      # it exercises the compute endpoint for the configured region rather
+      # than just the identity endpoint.
+      #
+      # @return [Array<String>] a problem description, or an empty array
+      def credential_problems
+        compute.servers.all
+        []
+      rescue Fog::Errors::Error, Excon::Errors::Error => e
+        ["Rackspace rejected the configured credentials for region " \
+         "#{config[:rackspace_region]}: #{e.message}"]
+      end
+
+      # Looks a server up without turning a missing one into a failure.
+      #
+      # @param server_id [String] the Rackspace server ID
+      # @return [Fog::Compute::RackspaceV2::Server, nil] the server, or nil
+      #   when Rackspace does not know it or cannot be reached
+      def lookup_server(server_id)
+        compute.servers.get(server_id)
+      rescue Fog::Errors::Error, Excon::Errors::Error
+        nil
+      end
+
+      # Builds the fog compute connection from the configured credentials.
+      #
+      # @return [Fog::Compute] a Rackspace compute connection
       def compute
         server_def = { provider: "Rackspace" }
         opts = %i{version rackspace_username rackspace_api_key
@@ -113,17 +242,33 @@ module Kitchen
         Fog::Compute.new(server_def)
       end
 
+      # Bootstraps the Cloud Server from the configured options.
+      #
+      # RackConnect and Managed Service Level both need the root password left
+      # unlocked to do their work, so +no_passwd_lock+ is forced on whenever
+      # either wait is requested, regardless of how it was configured.
+      #
+      # @note fog's +bootstrap+ calls +Server#setup+, which rescues
+      #   +Errno::ECONNREFUSED+ and retries forever, one second apart. A server
+      #   that never opens port 22 hangs here rather than failing, and
+      #   +wait_for+ does not bound it.
+      #
+      # @return [Fog::Compute::RackspaceV2::Server] the newly built server
       def create_server
         server_def = { name: config[:server_name], networks: }
         %i{image_id flavor_id public_key_path no_passwd_lock user_data config_drive}.each do |opt|
           server_def[opt] = config[opt]
         end
-        # see @note on bootstrap def about rackconnect
+        # RackConnect and Managed Service Level need the root password left
+        # unlocked; see the note above.
         no_passwd_lock = config[:rackconnect_wait] || config[:servicelevel_wait]
         server_def[:no_passwd_lock] = no_passwd_lock if no_passwd_lock
         compute.servers.bootstrap(server_def)
       end
 
+      # The bundled platform-name to image-ID map.
+      #
+      # @return [Hash{String => String}] parsed from +data/images.json+
       def images
         @images ||= begin
           json_file = File.expand_path("../../../data/images.json", __dir__)
@@ -131,14 +276,41 @@ module Kitchen
         end
       end
 
+      # Waits until the server will accept a login.
+      #
+      # The TCP check does not honour +ssh_config+, which some setups need, so
+      # +no_ssh_tcp_check+ swaps the check for a fixed sleep of
+      # +no_ssh_tcp_check_sleep+ seconds instead.
+      #
+      # @param state [Hash] instance state describing how to connect
+      # @return [void]
       def tcp_check(state)
         # allow driver config to bypass SSH tcp check -- because
         # it doesn't respect ssh_config values that might be required
-        wait_for_sshd(state[:hostname]) unless config[:no_ssh_tcp_check]
+        wait_for_sshd(state) unless config[:no_ssh_tcp_check]
         sleep(config[:no_ssh_tcp_check_sleep]) if config[:no_ssh_tcp_check]
         puts "(ssh ready)"
       end
 
+      # Blocks until the configured transport can connect to the instance.
+      #
+      # Kitchen::Driver::SSHBase used to supply this; the configured transport
+      # knows how to wait for the instance to accept connections.
+      #
+      # @param state [Hash] instance state describing how to connect
+      # @return [void]
+      def wait_for_sshd(state)
+        instance.transport.connection(state, &:wait_until_ready)
+      end
+
+      # Waits for RackConnect automation to finish.
+      #
+      # The server is refreshed afterwards, because RackConnect assigns a new
+      # public address as part of its work and the stale one would otherwise
+      # be handed to the transport.
+      #
+      # @param server [Fog::Compute::RackspaceV2::Server] the server to poll
+      # @return [void]
       def rackconnect_check(server)
         server.wait_for \
           { metadata.all["rackconnect_automation_status"] == "DEPLOYED" }
@@ -146,12 +318,21 @@ module Kitchen
         server.update # refresh accessIPv4 with new IP
       end
 
+      # Waits for Managed Service Level automation to finish.
+      #
+      # @param server [Fog::Compute::RackspaceV2::Server] the server to poll
+      # @return [void]
       def servicelevel_check(server)
         server.wait_for \
           { metadata.all["rax_service_level_automation"] == "Complete" }
         puts "(service level automation complete)"
       end
 
+      # Picks the address Test Kitchen should connect to.
+      #
+      # @param server [Fog::Compute::RackspaceV2::Server] the built server
+      # @return [String] the private address when +servicenet+ is set,
+      #   otherwise the public one
       def hostname(server)
         if config[:servicenet] == false
           server.public_ip_address
@@ -160,6 +341,14 @@ module Kitchen
         end
       end
 
+      # Builds the network list for the new server.
+      #
+      # Rackspace's PublicNet and ServiceNet have fixed, well-known IDs. Any
+      # configured networks are added to those two rather than replacing them,
+      # since dropping PublicNet would leave the server unreachable.
+      #
+      # @return [Array<String>, nil] network IDs, or nil to let Rackspace
+      #   apply its own defaults
       def networks
         base_nets = %w{
           00000000-0000-0000-0000-000000000000

data/lib/kitchen/driver/rackspace_version.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
+# Test Kitchen's top-level namespace.
 module Kitchen
+  # Test Kitchen's driver plugins.
   module Driver
-    RACKSPACE_VERSION = "0.21.2"
+    # The version of the kitchen-rackspace gem.
+    RACKSPACE_VERSION = "0.22.1"
   end
 end