kitchen-openstack 7.0.1 → 8.0.0

data/lib/kitchen/driver/openstack.rb

@@ -34,8 +34,17 @@ require_relative "openstack/volume"
 
 module Kitchen
   module Driver
-    # This takes from the Base Class and creates the OpenStack driver.
+    # Test Kitchen driver for OpenStack Nova.
+    #
+    # Creates and destroys Nova instances, optionally attaching floating IPs,
+    # Cinder volumes and specific Neutron networks. Credentials come from
+    # kitchen.yml, `OS_*` environment variables, or a standard
+    # `clouds.yaml` -- see {Clouds} for the precedence rules.
     class Openstack < Kitchen::Driver::Base
+      # Settings Fog requires as Strings. Fog re-coerces anything that looks
+      # numeric back to an Integer, so these are stringified on the way in.
+      #
+      # @return [Array<Symbol>]
       FOG_STRING_SETTINGS = %i{
         openstack_username
         openstack_api_key
@@ -70,13 +79,6 @@ module Kitchen
       default_config :clouds_yaml_path, nil
       default_config :server_name, nil
 
-      # Merge clouds.yaml values into config so they are visible in
-      # `kitchen diagnose` and available to all driver methods.
-      def finalize_config!(instance)
-        super
-        apply_clouds_config
-        self
-      end
       default_config :server_name_prefix, nil
       default_config :key_name, nil
       default_config :port, "22"
@@ -103,6 +105,28 @@ module Kitchen
       default_config :write_timeout, 60
       default_config :metadata, nil
 
+      # Merges clouds.yaml and `OS_*` values into the config hash.
+      #
+      # Done at finalize time rather than lazily so the resolved values show up
+      # in `kitchen diagnose` and are available to every driver method.
+      #
+      # @param instance [Kitchen::Instance] the instance this driver serves
+      # @return [self]
+      def finalize_config!(instance)
+        super
+        apply_clouds_config
+        self
+      end
+
+      # Creates a Nova instance and waits until it is reachable.
+      #
+      # Idempotent: returns immediately if `state` already names a server.
+      #
+      # @param state [Hash] mutable instance state; gains `:server_id` and
+      #   `:hostname`
+      # @return [void]
+      # @raise [Kitchen::ActionFailed] on any Fog or Excon failure
+      # @raise [Kitchen::InstanceFailure] if the server builds to ERROR state
       def create(state)
         config_server_name
         if state[:server_id]
@@ -138,6 +162,14 @@ module Kitchen
         raise ActionFailed, e.message
       end
 
+      # Destroys the Nova instance named by `state`, releasing its floating IP
+      # first when this driver allocated one.
+      #
+      # Safe to call when the server is already gone.
+      #
+      # @param state [Hash] mutable instance state; loses `:server_id` and
+      #   `:hostname`
+      # @return [void]
       def destroy(state)
         return if state[:server_id].nil?
 
@@ -150,12 +182,7 @@ module Kitchen
             pub, priv = get_public_private_ips(server)
             pub, = parse_ips(pub, priv)
             pub_ip = pub[config[:public_ip_order].to_i] || nil
-            if pub_ip
-              info "Retrieve the ID of floating IP <#{pub_ip}>"
-              floating_ip_id = network.list_floating_ips(floating_ip_address: pub_ip).body["floatingips"][0]["id"]
-              network.delete_floating_ip(floating_ip_id)
-              info "OpenStack Floating IP <#{pub_ip}> released."
-            end
+            release_floating_ip(pub_ip) if pub_ip
           end
           server.destroy
         end
@@ -166,6 +193,29 @@ module Kitchen
 
       private
 
+      # Releases a floating IP back to its pool.
+      #
+      # A floating IP that Neutron no longer knows about is not an error worth
+      # failing a destroy over, so an unknown address is logged and skipped.
+      #
+      # @param pub_ip [String] the floating IP to release
+      # @return [void]
+      def release_floating_ip(pub_ip)
+        info "Retrieve the ID of floating IP <#{pub_ip}>"
+        net = network
+        floating_ips = net.list_floating_ips(floating_ip_address: pub_ip).body["floatingips"]
+        if floating_ips.nil? || floating_ips.empty?
+          warn "No floating IP found matching <#{pub_ip}>; nothing to release."
+          return
+        end
+
+        net.delete_floating_ip(floating_ips[0]["id"])
+        info "OpenStack Floating IP <#{pub_ip}> released."
+      end
+
+      # Builds the settings hash handed to every Fog service constructor.
+      #
+      # @return [Hash] Fog connection settings
       def openstack_server
         server_def = {
           connection_options: {},
@@ -176,36 +226,61 @@ module Kitchen
         server_def
       end
 
+      # Settings always sent to Fog, even when nil.
+      #
+      # @return [Array<Symbol>]
       def required_server_settings
         %i{openstack_username openstack_api_key openstack_auth_url openstack_domain_id}
       end
 
+      # Every other `openstack_*` setting Fog recognizes, sent only when set.
+      #
+      # @return [Array<Symbol>]
       def optional_server_settings
         Fog::OpenStack::Compute.recognized.select do |k|
           k.to_s.start_with?("openstack")
         end - required_server_settings
       end
 
+      # Settings passed through to Excon rather than to Fog itself.
+      #
+      # `ssl_ca_file` belongs here, not in the Fog settings: Fog does not
+      # recognize it, so a CA bundle from `OS_CACERT` or a clouds.yaml
+      # `cacert` entry would otherwise be parsed and then silently dropped.
+      #
+      # @return [Array<Symbol>]
       def connection_options
-        %i{read_timeout write_timeout connect_timeout}
+        %i{read_timeout write_timeout connect_timeout ssl_ca_file}
       end
 
+      # @return [Fog::OpenStack::Network] a Neutron connection
       def network
         Fog::OpenStack::Network.new(openstack_server)
       end
 
+      # @return [Fog::OpenStack::Compute] a Nova connection
       def compute
         Fog::OpenStack::Compute.new(openstack_server)
       end
 
+      # @return [Kitchen::Driver::Openstack::Volume] a Cinder helper
       def volume
         Volume.new(logger)
       end
 
+      # Resolves the block device mapping to send to Nova.
+      #
+      # @param config [Hash] the driver config
+      # @return [Hash] a Nova block device mapping
       def get_bdm(config)
         volume.get_bdm(config, openstack_server)
       end
 
+      # Coerces one setting to the type Fog expects.
+      #
+      # @param setting [Symbol] the Fog config key
+      # @param value [Object] the configured value
+      # @return [Object] the coerced value
       def normalize_fog_setting(setting, value)
         return value if value.nil?
         return normalize_identity_api_version(value) if setting == :openstack_identity_api_version
@@ -214,11 +289,20 @@ module Kitchen
         value.to_s
       end
 
+      # Normalizes the identity API version into a form Fog will not mangle.
+      #
       # Fog::Service#coerce_options re-coerces any value where
       # `value.to_s.to_i.to_s == value.to_s` back to an Integer, which
       # then breaks Fog::OpenStack::Auth::Token.build (it calls `=~`
       # on the value). Prefixing with "v" keeps Fog from coercing and
       # still satisfies Token.build's `/(v)*2(\.0)*/i` regex check.
+      #
+      # @example
+      #   normalize_identity_api_version(3)     #=> "v3"
+      #   normalize_identity_api_version("2.0") #=> "v2.0"
+      #
+      # @param value [String, Integer] the configured identity API version
+      # @return [String] a version string prefixed with "v"
       def normalize_identity_api_version(value)
         str = value.to_s.strip
         return str if str.empty?

data/lib/kitchen/driver/openstack_version.rb

@@ -23,6 +23,12 @@ module Kitchen
   #
   # @author Jonathan Hartman <j@p4nt5.com>
   module Driver
-    OPENSTACK_VERSION = "7.0.1"
+    # The kitchen-openstack gem version.
+    #
+    # Read by the gemspec and bumped by Release Please, so it must stay a
+    # plain string literal on a single line.
+    #
+    # @return [String]
+    OPENSTACK_VERSION = "8.0.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kitchen-openstack
 version: !ruby/object:Gem::Version
-  version: 7.0.1
+  version: 8.0.0
 platform: ruby
 authors:
 - Jonathan Hartman
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-24 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: test-kitchen