kitchen-rackspace 0.21.2 → 0.22.0

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,22 @@ module Kitchen
       required_config :image_id
       required_config :public_key_path
 
+      # @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 +99,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 +121,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 +148,79 @@ 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] mutable instance and driver state
+      # @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.
+      #
+      # @return [Array<String>] a problem description, or an empty array
+      def credential_problems
+        compute.servers.summary
+        []
+      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,6 +231,13 @@ 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.
+      #
+      # @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|
@@ -124,6 +249,9 @@ module Kitchen
         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 +259,36 @@ 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
 
+      # Kitchen::Driver::SSHBase used to supply this; the configured transport
+      # knows how to wait for the instance to accept connections.
+      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 +296,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 +319,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.0"
   end
 end

data/spec/kitchen/driver/rackspace_spec.rb

@@ -27,6 +27,121 @@ describe Kitchen::Driver::Rackspace do
     ENV["RACKSPACE_API_KEY"] = "key"
   end
 
+  describe "plugin metadata" do
+    it "declares the driver API version" do
+      expect(described_class.instance_variable_get(:@api_version)).to eq(2)
+    end
+
+    it "reports its own gem version to kitchen diagnose" do
+      expect(driver.diagnose_plugin[:version])
+        .to eq(Kitchen::Driver::RACKSPACE_VERSION)
+    end
+  end
+
+  describe "#status" do
+    let(:server) { double(state: "ACTIVE") }
+    let(:servers) { double }
+
+    before(:each) do
+      allow(driver).to receive(:compute).and_return(double(servers:))
+    end
+
+    context "with no server in state" do
+      it "reports an unknown status" do
+        expect(driver.status({})).to include(live: nil, state: "unknown")
+      end
+    end
+
+    context "with a server Rackspace does not know" do
+      it "reports an unknown status" do
+        expect(servers).to receive(:get).with("gone").and_return(nil)
+
+        expect(driver.status(server_id: "gone")).to include(state: "unknown")
+      end
+    end
+
+    context "with a live server" do
+      before(:each) do
+        allow(servers).to receive(:get).with("s-1").and_return(server)
+      end
+
+      it "reports the server as live" do
+        expect(driver.status(server_id: "s-1")).to include(
+          live: true, state: "ACTIVE", source: "driver", resource_id: "s-1"
+        )
+      end
+
+      it "stamps when the check happened" do
+        expect(driver.status(server_id: "s-1")[:checked_at])
+          .to match(/\A\d{4}-\d{2}-\d{2}T/)
+      end
+    end
+
+    context "with a server that is not active" do
+      it "reports the server as not live" do
+        allow(servers).to receive(:get)
+          .with("s-1").and_return(double(state: "ERROR"))
+
+        expect(driver.status(server_id: "s-1"))
+          .to include(live: false, state: "ERROR")
+      end
+    end
+
+    context "when Rackspace cannot be reached" do
+      it "reports an unknown status rather than raising" do
+        allow(servers).to receive(:get)
+          .and_raise(Fog::Errors::Error.new("boom"))
+
+        expect(driver.status(server_id: "s-1")).to include(state: "unknown")
+      end
+    end
+  end
+
+  describe "#doctor" do
+    let(:config) do
+      { image_id: "img-1", public_key_path: "/home/user/.ssh/id_rsa.pub" }
+    end
+
+    before(:each) do
+      allow(driver).to receive(:compute)
+        .and_return(double(servers: double(summary: [])))
+    end
+
+    it "reports no problem when the configuration is complete" do
+      expect(driver.doctor(state)).to eq(false)
+    end
+
+    context "with no resolvable image" do
+      let(:config) { { public_key_path: "/key.pub" } }
+
+      it "reports a problem" do
+        allow(driver).to receive(:default_image).and_return(nil)
+
+        expect(driver.doctor(state)).to eq(true)
+        expect(logged_output.string).to match(/No image_id is set/)
+      end
+    end
+
+    context "with no public key" do
+      let(:config) { { image_id: "img-1", public_key_path: nil } }
+
+      it "reports a problem" do
+        expect(driver.doctor(state)).to eq(true)
+        expect(logged_output.string).to match(/No public key was found/)
+      end
+    end
+
+    context "with credentials Rackspace rejects" do
+      it "reports a problem" do
+        allow(driver).to receive(:compute)
+          .and_raise(Fog::Errors::Error.new("unauthorized"))
+
+        expect(driver.doctor(state)).to eq(true)
+        expect(logged_output.string).to match(/rejected the configured credentials/)
+      end
+    end
+  end
+
   describe "#initialize" do
     before(:each) do
       allow(Fog).to receive(:timeout=)
@@ -37,8 +152,8 @@ describe Kitchen::Driver::Rackspace do
         expect(driver[:version]).to eq("v2")
       end
 
-      it "defaults to the smallest flavor size" do
-        expect(driver[:flavor_id]).to eq("performance1-1")
+      it "defaults to a 2 GB general purpose flavor" do
+        expect(driver[:flavor_id]).to eq("general1-2")
       end
 
       it "defaults to local user's SSH public key" do
@@ -160,6 +275,12 @@ describe Kitchen::Driver::Rackspace do
         ENV["OS_REGION_NAME"] = "os_region"
       end
 
+      after(:each) do
+        ENV.delete("OS_USERNAME")
+        ENV.delete("OS_PASSWORD")
+        ENV.delete("OS_REGION_NAME")
+      end
+
       it "gets to username from $OS_USERNAME" do
         expect(driver[:rackspace_username]).to eq("os_user")
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-rackspace
 version: !ruby/object:Gem::Version
-  version: 0.21.2
+  version: 0.22.0
 platform: ruby
 authors:
 - Jonathan Hartman
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fog-rackspace
@@ -33,7 +33,7 @@ dependencies:
         version: '1.35'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 2.6.1
+        version: '2.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -43,14 +43,14 @@ dependencies:
         version: '1.35'
     - - "<"
       - !ruby/object:Gem::Version
-        version: 2.6.1
+        version: '2.3'
 - !ruby/object:Gem::Dependency
   name: test-kitchen
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'
@@ -60,7 +60,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: '3.0'
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'
@@ -72,19 +72,22 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/CODEOWNERS"
-- ".github/dependabot.yml"
 - ".github/workflows/linters.yml"
 - ".github/workflows/publish.yaml"
 - ".gitignore"
 - ".markdownlint.yaml"
 - ".release-please-manifest.json"
 - ".rubocop.yml"
+- ".yamllint"
+- ".yardopts"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE
 - README.md
 - Rakefile
 - data/images.json
+- helpers/dump_flavor_list.rb
 - helpers/dump_image_list.rb
 - kitchen-rackspace.gemspec
 - lib/kitchen/driver/rackspace.rb
@@ -95,7 +98,7 @@ files:
 - spec/spec_helper.rb
 homepage: https://github.com/test-kitchen/kitchen-rackspace
 licenses:
-- Apache
+- Apache-2.0
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -116,6 +119,4 @@ rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
 summary: A Test Kitchen Rackspace driver built on Fog
-test_files:
-- spec/kitchen/driver/rackspace_spec.rb
-- spec/spec_helper.rb
+test_files: []

data/.github/dependabot.yml

@@ -1,8 +0,0 @@
----
-version: 2
-updates:
-  - package-ecosystem: bundler
-    directory: "/"
-    schedule:
-      interval: daily
-    open-pull-requests-limit: 10