kitchen-openstack 7.0.1 → 8.0.0

data/lib/kitchen/driver/openstack/networking.rb

@@ -28,47 +28,100 @@ module Kitchen
     class Openstack < Kitchen::Driver::Base
       # Floating IP allocation and IP address resolution
       module Networking
+        # Serializes floating IP selection across the driver instances that
+        # Test Kitchen runs in parallel. Without it, two concurrent converges
+        # can pick the same free address out of the pool and one of them fails
+        # to associate it.
+        #
+        # @return [Mutex]
         IP_POOL_LOCK = Mutex.new
 
         private
 
+        # Attaches a floating IP from the named pool to the server, allocating
+        # a fresh one first when `:allocate_floating_ip` is set.
+        #
+        # Held under {IP_POOL_LOCK} for the whole select-then-attach sequence,
+        # so a concurrent converge cannot claim the same address in between.
+        #
+        # @param server [Fog::OpenStack::Compute::Server] the server to attach to
+        # @param pool [String] name of the floating IP pool / external network
+        # @return [void]
+        # @raise [Kitchen::ActionFailed] if the pool does not exist, or holds no
+        #   free addresses
         def attach_ip_from_pool(server, pool)
           IP_POOL_LOCK.synchronize do
             info "Attaching floating IP from <#{pool}> pool"
-            if config[:allocate_floating_ip]
-              network_id = network
-                .list_networks(
-                  name: pool
-                ).body["networks"][0]["id"]
-              resp = network.create_floating_ip(network_id)
-              ip = resp.body["floatingip"]["floating_ip_address"]
-              info "Created floating IP <#{ip}> from <#{pool}> pool"
-              config[:floating_ip] = ip
-            else
-              free_addrs = compute.addresses.map do |i|
-                i.ip if i.fixed_ip.nil? && i.instance_id.nil? && i.pool == pool
-              end.compact
-              if free_addrs.empty?
-                raise ActionFailed, "No available IPs in pool <#{pool}>"
-              end
-
-              config[:floating_ip] = free_addrs[0]
-            end
+            config[:floating_ip] = if config[:allocate_floating_ip]
+                                     allocate_ip_from_pool(pool)
+                                   else
+                                     free_ip_from_pool(pool)
+                                   end
             attach_ip(server, config[:floating_ip])
           end
         end
 
+        # Asks Neutron for a brand new floating IP on the named external
+        # network.
+        #
+        # @param pool [String] name of the external network
+        # @return [String] the newly allocated floating IP
+        # @raise [Kitchen::ActionFailed] if no network matches `pool`
+        def allocate_ip_from_pool(pool)
+          net = network
+          networks = net.list_networks(name: pool).body["networks"]
+          if networks.nil? || networks.empty?
+            raise ActionFailed, "Floating IP pool <#{pool}> not found"
+          end
+
+          resp = net.create_floating_ip(networks[0]["id"])
+          ip = resp.body["floatingip"]["floating_ip_address"]
+          info "Created floating IP <#{ip}> from <#{pool}> pool"
+          ip
+        end
+
+        # Picks an already-allocated but unattached floating IP out of the pool.
+        #
+        # @param pool [String] name of the floating IP pool
+        # @return [String] a free floating IP
+        # @raise [Kitchen::ActionFailed] if every address in the pool is in use
+        def free_ip_from_pool(pool)
+          # `find`, not `map`+`compact`: this runs while holding IP_POOL_LOCK,
+          # which serializes parallel converges, so it should stop at the first
+          # usable address rather than building a throwaway list of all of them.
+          free = compute.addresses.find do |i|
+            i.fixed_ip.nil? && i.instance_id.nil? && i.pool == pool
+          end
+          raise ActionFailed, "No available IPs in pool <#{pool}>" if free.nil?
+
+          free.ip
+        end
+
+        # Associates a floating IP with a server.
+        #
+        # @param server [Fog::OpenStack::Compute::Server] the server
+        # @param ip [String] the floating IP to attach
+        # @return [void]
         def attach_ip(server, ip)
           info "Attaching floating IP <#{ip}>"
           server.associate_address ip
         end
 
+        # Reads the server's public and private addresses.
+        #
+        # Deployments without the floating IP extension answer the dedicated
+        # accessors with 404/403, so fall back to picking the lists out of the
+        # generic addresses hash.
+        #
+        # @see https://github.com/fog/fog/issues/2160
+        # @param server [Fog::OpenStack::Compute::Server] the server
+        # @return [Array(Array<String>, Array<String>)] public and private
+        #   addresses, either of which may be nil
         def get_public_private_ips(server)
           begin
             pub = server.public_ip_addresses
             priv = server.private_ip_addresses
           rescue Fog::OpenStack::Compute::NotFound, Excon::Errors::Forbidden
-            # See Fog issue: https://github.com/fog/fog/issues/2160
             addrs = server.addresses
             addrs["public"] && pub = addrs["public"].map { |i| i["addr"] }
             addrs["private"] && priv = addrs["private"].map { |i| i["addr"] }
@@ -76,6 +129,19 @@ module Kitchen
           [pub, priv]
         end
 
+        # Determines the address Test Kitchen should connect to.
+        #
+        # Resolution order:
+        #
+        # 1. an explicitly configured `:floating_ip`
+        # 2. the first address on `:openstack_network_name`, if configured
+        # 3. `:public_ip_order` into the public addresses
+        # 4. `:private_ip_order` into the private addresses
+        #
+        # @param server [Fog::OpenStack::Compute::Server] the server
+        # @return [String] the address to connect to
+        # @raise [Kitchen::ActionFailed] if network information never arrives,
+        #   or no address of the requested family can be found
         def get_ip(server)
           if config[:floating_ip]
             debug "Using floating ip: #{config[:floating_ip]}"
@@ -91,11 +157,7 @@ module Kitchen
             raise ActionFailed, "Could not get network information (timed out)"
           end
 
-          # should also work for private networks
-          if config[:openstack_network_name]
-            debug "Using configured net: #{config[:openstack_network_name]}"
-            return filter_ips(server.addresses[config[:openstack_network_name]]).first["addr"]
-          end
+          return ip_from_named_network(server) if config[:openstack_network_name]
 
           pub, priv = get_public_private_ips(server)
           priv = server.ip_addresses if Array(pub).empty? && Array(priv).empty?
@@ -105,6 +167,33 @@ module Kitchen
             raise(ActionFailed, "Could not find an IP")
         end
 
+        # Picks the first usable address off the network named by
+        # `:openstack_network_name`.
+        #
+        # @param server [Fog::OpenStack::Compute::Server] the server
+        # @return [String] the address
+        # @raise [Kitchen::ActionFailed] if the server is not on that network,
+        #   or has no address there of the configured IP family
+        def ip_from_named_network(server)
+          name = config[:openstack_network_name]
+          debug "Using configured net: #{name}"
+
+          addresses = server.addresses[name]
+          raise ActionFailed, "Server is not attached to network <#{name}>" if addresses.nil?
+
+          matching = filter_ips(addresses)
+          if matching.empty?
+            raise ActionFailed,
+              "No #{config[:use_ipv6] ? "IPv6" : "IPv4"} address found on network <#{name}>"
+          end
+
+          matching.first["addr"]
+        end
+
+        # Keeps only the addresses matching the configured IP family.
+        #
+        # @param addresses [Array<Hash>] address hashes, each with an `"addr"` key
+        # @return [Array<Hash>] the matching subset
         def filter_ips(addresses)
           if config[:use_ipv6]
             addresses.select { |i| IPAddr.new(i["addr"]).ipv6? }
@@ -113,15 +202,21 @@ module Kitchen
           end
         end
 
+        # Normalizes and filters public/private address lists to the configured
+        # IP family.
+        #
+        # @param pub [Array<String>, String, nil] public addresses
+        # @param priv [Array<String>, String, nil] private addresses
+        # @return [Array(Array<String>, Array<String>)] filtered public and
+        #   private address lists
         def parse_ips(pub, priv)
-          pub = Array(pub)
-          priv = Array(priv)
-          if config[:use_ipv6]
-            [pub, priv].each { |n| n.select! { |i| IPAddr.new(i).ipv6? } }
-          else
-            [pub, priv].each { |n| n.select! { |i| IPAddr.new(i).ipv4? } }
+          # `select`, not `select!`: Array(x) returns x itself when x is already
+          # an Array, so filtering in place would edit the caller's list -- and
+          # the caller's list here is the Fog server model's own address data.
+          wanted = config[:use_ipv6] ? :ipv6? : :ipv4?
+          [Array(pub), Array(priv)].map do |addrs|
+            addrs.select { |i| IPAddr.new(i).public_send(wanted) }
           end
-          [pub, priv]
         end
       end
     end

data/lib/kitchen/driver/openstack/server_helper.rb

@@ -26,8 +26,29 @@ module Kitchen
     class Openstack < Kitchen::Driver::Base
       # Server creation and resource finders (image, flavor, network)
       module ServerHelper
+        # Config keys copied onto the server definition when set, each routed
+        # through {#optional_config}.
+        #
+        # @return [Array<Symbol>]
+        OPTIONAL_SERVER_KEYS = %i{
+          security_groups
+          key_name
+          user_data
+          config_drive
+          metadata
+        }.freeze
+
         private
 
+        # Builds the Nova server definition and submits it.
+        #
+        # Fog's `bootstrap`/`setup` helpers are deliberately not used: they
+        # require a public IP address, which is not guaranteed to exist on
+        # every OpenStack deployment.
+        #
+        # @return [Fog::OpenStack::Compute::Server] the newly created server
+        # @raise [Kitchen::ActionFailed] on mutually exclusive or unresolvable
+        #   configuration
         def create_server
           server_def = init_configuration
           raise(ActionFailed, "Cannot specify both network_ref and network_id") if config[:network_id] && config[:network_ref]
@@ -44,17 +65,7 @@ module Kitchen
             end
           end
 
-          if config[:block_device_mapping]
-            server_def[:block_device_mapping] = get_bdm(config)
-          end
-
-          %i{
-            security_groups
-            key_name
-            user_data
-            config_drive
-            metadata
-          }.each do |c|
+          OPTIONAL_SERVER_KEYS.each do |c|
             server_def[c] = optional_config(c) if config[c]
           end
 
@@ -64,12 +75,25 @@ module Kitchen
             server_def[:user_data] = YAML.dump(Kitchen::Util.stringified_hash(config[:cloud_config])).gsub(/^---\n/, "#cloud-config\n")
           end
 
-          # Can't use the Fog bootstrap and/or setup methods here; they require a
-          # public IP address that can't be guaranteed to exist across all
-          # OpenStack deployments (e.g. TryStack ARM only has private IPs).
+          # Last, because this is the only step that creates a resource. Every
+          # check above is local config validation, and running them first means
+          # a bad security_groups or user_data value cannot strand a Cinder
+          # volume whose id exists only in the server_def about to be discarded.
+          if config[:block_device_mapping]
+            server_def[:block_device_mapping] = get_bdm(config)
+          end
+
           compute.servers.create(server_def)
         end
 
+        # Builds the mandatory part of the server definition.
+        #
+        # `*_id` and `*_ref` are mutually exclusive: an id is used verbatim, a
+        # ref is resolved by name, id or regex through {#find_matching}.
+        #
+        # @return [Hash] name, image, flavor and availability zone
+        # @raise [Kitchen::ActionFailed] if both an id and a ref are given for
+        #   the image or the flavor, or if either cannot be resolved
         def init_configuration
           raise(ActionFailed, "Cannot specify both image_ref and image_id") if config[:image_id] && config[:image_ref]
           raise(ActionFailed, "Cannot specify both flavor_ref and flavor_id") if config[:flavor_id] && config[:flavor_ref]
@@ -82,17 +106,39 @@ module Kitchen
           }
         end
 
+        # Resolves one optional server setting to the value Nova expects.
+        #
+        # @param c [Symbol] the config key
+        # @return [Object] the resolved value
+        # @raise [Kitchen::ActionFailed] if `:security_groups` is not a list, or
+        #   if the `:user_data` file does not exist
         def optional_config(c)
           case c
           when :security_groups
-            config[c] if config[c].is_a?(Array)
+            unless config[c].is_a?(Array)
+              raise ActionFailed, "The security_groups config must be an array, got #{config[c].class}"
+            end
+
+            config[c]
           when :user_data
-            File.read(config[c]) if File.exist?(config[c])
+            # Booting without the user_data the user asked for produces a
+            # server that looks fine and behaves wrongly, so a missing file is
+            # fatal rather than silently ignored.
+            unless File.exist?(config[c])
+              raise ActionFailed, "The user_data file <#{config[c]}> does not exist"
+            end
+
+            File.read(config[c])
           else
             config[c]
           end
         end
 
+        # Finds a Glance image by id, name or regex.
+        #
+        # @param image_ref [String] id, name, or `/regex/`
+        # @return [Object] the matching image
+        # @raise [Kitchen::ActionFailed] if nothing matches
         def find_image(image_ref)
           image = find_matching(compute.images, image_ref)
           raise(ActionFailed, "Image not found") unless image
@@ -101,6 +147,11 @@ module Kitchen
           image
         end
 
+        # Finds a Nova flavor by id, name or regex.
+        #
+        # @param flavor_ref [String] id, name, or `/regex/`
+        # @return [Object] the matching flavor
+        # @raise [Kitchen::ActionFailed] if nothing matches
         def find_flavor(flavor_ref)
           flavor = find_matching(compute.flavors, flavor_ref)
           raise(ActionFailed, "Flavor not found") unless flavor
@@ -109,6 +160,11 @@ module Kitchen
           flavor
         end
 
+        # Finds a Neutron network by id, name or regex.
+        #
+        # @param network_ref [String] id, name, or `/regex/`
+        # @return [Object] the matching network
+        # @raise [Kitchen::ActionFailed] if nothing matches
         def find_network(network_ref)
           net = find_matching(network.networks.all, network_ref)
           raise(ActionFailed, "Network not found") unless net
@@ -117,15 +173,31 @@ module Kitchen
           net
         end
 
+        # Picks a resource out of a Fog collection.
+        #
+        # A ref wrapped in forward slashes is treated as a regular expression
+        # matched against the resource name; anything else is compared against
+        # the id first and then the name, so an exact id always wins.
+        #
+        # @example an exact name
+        #   find_matching(compute.images, "ubuntu-24.04")
+        # @example a regular expression
+        #   find_matching(compute.images, "/^ubuntu-24\\.04/")
+        #
+        # @param collection [Enumerable] the Fog collection to search
+        # @param name [String] id, name, or `/regex/`
+        # @return [Object, nil] the first match, or nil
         def find_matching(collection, name)
           name = name.to_s
           if name.start_with?("/") && name.end_with?("/")
             regex = Regexp.new(name[1...-1])
-            # check for regex name match
-            collection.each { |single| return single if regex&.match?(single.name) }
+            # check for regex name match, skipping unnamed resources; Neutron
+            # networks in particular are allowed to have no name
+            collection.each { |single| return single if single.name && regex.match?(single.name) }
           else
-            # check for exact id match
-            collection.each { |single| return single if single.id == name }
+            # check for exact id match; ids come back as integers on some
+            # deployments, so compare as strings
+            collection.each { |single| return single if single.id.to_s == name }
             # check for exact name match
             collection.each { |single| return single if single.name == name }
           end

data/lib/kitchen/driver/openstack/volume.rb

@@ -26,28 +26,70 @@ module Kitchen
       # A class to allow the Kitchen Openstack driver
       # to use Openstack volumes
       #
+      # Instances of this class translate a `block_device_mapping` config hash
+      # into the shape Nova expects, creating a Cinder volume first when the
+      # mapping asks for one.
+      #
       # @author Liam Haworth <liam.haworth@bluereef.com.au>
       class Volume
+        # Seconds to wait for a newly created volume to become available when
+        # the block device mapping does not specify `creation_timeout`.
+        #
+        # @return [Integer]
         DEFAULT_CREATION_TIMEOUT = 60
 
+        # Block device mapping keys forwarded verbatim to Cinder's create call.
+        #
+        # @return [Array<Symbol>]
+        VANILLA_VOLUME_OPTIONS = %i{
+          snapshot_id
+          imageRef
+          volume_type
+          source_volid
+          availability_zone
+        }.freeze
+
+        # @param logger [Kitchen::Logger] logger to report volume progress to
         def initialize(logger)
           @logger = logger
         end
 
+        # Builds a Cinder connection.
+        #
+        # @param openstack_server [Hash] Fog connection settings
+        # @return [Fog::OpenStack::Volume] a Cinder service object
         def volume(openstack_server)
           Fog::OpenStack::Volume.new(openstack_server)
         end
 
+        # Creates a Cinder volume and blocks until it is available.
+        #
+        # @param config [Hash] the driver config, read for `:server_name` and
+        #   `:block_device_mapping`
+        # @param os [Hash] Fog connection settings
+        # @return [String] the id of the newly created volume
+        # @raise [Kitchen::ActionFailed] if a timeout is not a number, if the
+        #   volume cannot be found after creation, or if it enters an `error`
+        #   state
+        # @raise [Fog::Errors::TimeoutError] if the volume is not available
+        #   before `:creation_timeout` elapses
         def create_volume(config, os)
-          opt = {}
           bdm = config[:block_device_mapping]
-          vanilla_options = %i{snapshot_id imageRef volume_type
-                               source_volid availability_zone}
-          vanilla_options.select { |o| bdm[o] }.each do |key|
-            opt[key] = bdm[key]
-          end
+
+          # Read both timeouts before anything is created. They are pure config
+          # parsing, so a bad value should cost the user an error message, not
+          # an orphaned volume that `kitchen destroy` cannot see.
+          creation_timeout = timeout_value(bdm, :creation_timeout, DEFAULT_CREATION_TIMEOUT)
+          attach_timeout = timeout_value(bdm, :attach_timeout, 0)
+
+          opt = VANILLA_VOLUME_OPTIONS.select { |o| bdm[o] }.to_h { |key| [key, bdm[key]] }
+
+          # Build the Cinder connection once and reuse it for the readiness
+          # lookup, rather than authenticating to Keystone a second time.
+          volume_service = volume(os)
+
           @logger.info "Creating Volume..."
-          resp = volume(os)
+          resp = volume_service
             .create_volume(
               "#{config[:server_name]}-volume",
               "#{config[:server_name]} volume",
@@ -56,41 +98,95 @@ module Kitchen
             )
           vol_id = resp[:body]["volume"]["id"]
 
-          # Get Volume Model to make waiting for ready easy
-          vol_model = volume(os).volumes.first { |x| x.id == vol_id }
+          wait_for_volume(volume_service, vol_id, creation_timeout, attach_timeout)
 
-          # Use default creation timeout or user supplied
-          creation_timeout = DEFAULT_CREATION_TIMEOUT
-          if bdm.key?(:creation_timeout)
-            creation_timeout = bdm[:creation_timeout]
-          end
+          vol_id
+        end
+
+        # Resolves the block device mapping to hand to Nova, creating the
+        # backing volume first if `:make_volume` is set.
+        #
+        # The returned hash is a copy: the driver's own config is never
+        # mutated, so a retried `create` sees the same input it did the first
+        # time.
+        #
+        # @param config [Hash] the driver config
+        # @param os [Hash] Fog connection settings
+        # @return [Hash] a block device mapping suitable for Nova
+        def get_bdm(config, os)
+          bdm = config[:block_device_mapping].dup
+          bdm[:volume_id] = create_volume(config, os) if bdm[:make_volume]
+          bdm.delete(:make_volume)
+          bdm.delete(:snapshot_id)
+          bdm
+        end
+
+        private
+
+        # Blocks until the named volume reports ready, then honours any
+        # additional `:attach_timeout` grace period.
+        #
+        # @param volume_service [Fog::OpenStack::Volume] an established Cinder
+        #   connection
+        # @param vol_id [String] id of the volume to wait on
+        # @param creation_timeout [Integer] seconds to wait for readiness
+        # @param attach_timeout [Integer] extra seconds to sleep once ready
+        # @return [void]
+        # @raise [Kitchen::ActionFailed] if the volume cannot be fetched back
+        #   or enters an `error` state
+        def wait_for_volume(volume_service, vol_id, creation_timeout, attach_timeout)
+          # Fetch the volume by id rather than scanning the collection: a list
+          # call returns a single page (Cinder caps it at osapi_max_limit), so
+          # in a project with more volumes than that the one just created may
+          # not appear on it. `get` is a direct GET and returns nil on 404.
+          vol_model = volume_service.volumes.get(vol_id)
+          raise(ActionFailed, "Volume #{vol_id} disappeared after creation") if vol_model.nil?
 
           @logger.debug "Waiting for volume to be ready for #{creation_timeout} seconds"
           vol_model.wait_for(creation_timeout) do
             sleep(1)
-            raise("Failed to make volume") if status.casecmp("error".downcase) == 0
+            raise(ActionFailed, "Failed to make volume #{vol_id}") if status.casecmp("error") == 0
 
             ready?
           end
 
-          attach_timeout = bdm.key?(:attach_timeout) ? bdm[:attach_timeout] : 0
-
           if attach_timeout > 0
             @logger.debug "Sleeping for an additional #{attach_timeout} seconds before attaching volume to wait for Openstack to finish disk creation process.."
             sleep(attach_timeout)
           end
 
           @logger.debug "Volume Ready"
-
-          vol_id
         end
 
-        def get_bdm(config, os)
-          bdm = config[:block_device_mapping]
-          bdm[:volume_id] = create_volume(config, os) if bdm[:make_volume]
-          bdm.delete_if { |k, _| k == :make_volume }
-          bdm.delete_if { |k, _| k == :snapshot_id }
-          bdm
+        # Reads a timeout out of the block device mapping as an Integer.
+        #
+        # YAML happily parses `attach_timeout: 5` as an Integer but
+        # `attach_timeout: "5"` as a String, and comparing a String to 0 raises.
+        # Coerce so both spellings work.
+        #
+        # Base 10 is explicit: a bare `Integer("010")` would read the leading
+        # zero as octal and quietly wait 8 seconds instead of 10, and
+        # `Integer("08")` would raise outright.
+        #
+        # @param bdm [Hash] the block device mapping
+        # @param key [Symbol] the timeout key to read
+        # @param default [Integer] value to use when the key is absent or empty
+        # @return [Integer] the timeout in seconds
+        # @raise [Kitchen::ActionFailed] if the value is present but not a
+        #   number
+        def timeout_value(bdm, key, default)
+          value = bdm[key]
+          # `attach_timeout:` with nothing after it parses to nil.
+          return default if value.nil? || value.to_s.strip.empty?
+
+          begin
+            # The base argument is only legal for a String; passing one
+            # alongside an Integer raises "base specified for non string value".
+            value.is_a?(String) ? Integer(value, 10) : Integer(value)
+          rescue ArgumentError, TypeError
+            raise(ActionFailed,
+              "The block_device_mapping #{key} must be a number, got #{value.inspect}")
+          end
         end
       end
     end