kitchen-openstack 7.0.1 → 8.0.0

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

@@ -76,9 +76,12 @@ module Kitchen
         private
 
         # Merges external config sources into the driver config hash.
-        # Precedence: kitchen.yml > OS_* env vars > clouds.yaml
-        # Only sets keys that are currently nil so that kitchen.yml
-        # values always take precedence.
+        #
+        # Precedence, highest first: kitchen.yml, `OS_*` environment
+        # variables, then clouds.yaml. Only keys that are currently nil are
+        # written, so anything set explicitly in kitchen.yml always wins.
+        #
+        # @return [void]
         def apply_clouds_config
           cc = load_clouds_config
           env = load_env_vars
@@ -91,15 +94,23 @@ module Kitchen
             config[key] = value if config[key].nil?
           end
 
-          # Apply SSL settings: env vars or clouds.yaml disabling verification
-          ssl_verify = env.key?(:ssl_verify_peer) ? env[:ssl_verify_peer] : cc[:ssl_verify_peer]
-          return unless ssl_verify == false && !config[:disable_ssl_validation]
+          # `verify: false` in clouds.yaml is how operators opt out of TLS
+          # verification. openstacksdk documents no environment variable for it
+          # (though its env loader does sweep up any OS_* name into an implicit
+          # cloud), and ENV_VAR_MAP deliberately mirrors the documented set --
+          # so for this driver clouds.yaml is the only source.
+          return unless cc[:ssl_verify_peer] == false && !config[:disable_ssl_validation]
 
           config[:disable_ssl_validation] = true
         end
 
-        # Reads OS_* environment variables and maps them to Fog config keys.
-        # Returns a hash of fog config symbols for any set env vars.
+        # Reads `OS_*` environment variables and maps them to Fog config keys.
+        #
+        # Empty variables are ignored, so `OS_REGION_NAME=""` does not shadow
+        # a region set in clouds.yaml.
+        #
+        # @return [Hash{Symbol => Object}] Fog config keys for the variables
+        #   that are set
         def load_env_vars
           result = {}
           ENV_VAR_MAP.each do |env_var, fog_key|
@@ -109,57 +120,136 @@ module Kitchen
           result
         end
 
-        # Resolves the cloud name from config or the OS_CLOUD environment variable
+        # Resolves which named cloud to read out of clouds.yaml.
+        #
+        # @return [String, nil] the cloud name, or nil if none is configured
         def cloud_name
           config[:openstack_cloud] || ENV["OS_CLOUD"]
         end
 
         # Loads and merges clouds.yaml with secure.yaml, then translates the
         # named cloud entry into Fog-compatible config keys.
-        # Returns a hash of fog config symbols, or empty hash if no cloud configured.
+        #
+        # secure.yaml wins over clouds.yaml, matching openstacksdk.
+        #
+        # @return [Hash{Symbol => Object}] Fog config keys, or an empty hash
+        #   when no cloud is configured or the named cloud is absent
         def load_clouds_config
           name = cloud_name
           return {} unless name
 
-          clouds_data = load_yaml_file("clouds.yaml", "OS_CLIENT_CONFIG_FILE")
-          secure_data = load_yaml_file("secure.yaml", "OS_CLIENT_SECURE_FILE")
+          clouds_data, clouds_path = load_yaml_file("clouds.yaml", "OS_CLIENT_CONFIG_FILE")
+          secure_data, secure_path = load_yaml_file("secure.yaml", "OS_CLIENT_SECURE_FILE")
 
-          cloud = extract_cloud(clouds_data, name)
-          secure = extract_cloud(secure_data, name)
+          cloud = extract_cloud(clouds_data, name, clouds_path)
+          secure = extract_cloud(secure_data, name, secure_path)
 
           cloud = deep_merge(cloud, secure)
           translate_cloud_config(cloud)
         end
 
-        # Search standard OpenStack config file locations for the given filename
+        # Loads the first of the standard OpenStack config locations that
+        # exists.
+        #
+        # @param filename [String] `"clouds.yaml"` or `"secure.yaml"`
+        # @param env_var [String] the environment variable that overrides the
+        #   search path for this file
+        # @return [Array(Hash, String), Array(Hash, nil)] the parsed document
+        #   and the path it came from; an empty hash and nil if no file was
+        #   found
+        # @raise [Kitchen::ActionFailed] if the file exists but is not valid
+        #   YAML, or does not parse to a mapping
         def load_yaml_file(filename, env_var)
           paths = clouds_yaml_search_paths(filename, env_var)
           path = paths.find { |p| File.exist?(p) }
-          return {} unless path
+          return [{}, nil] unless path
 
           debug "Loading #{filename} from #{path}"
-          YAML.safe_load(File.read(path), permitted_classes: [Date]) || {} # rubocop: disable Style/YAMLFileRead
+          data = parse_yaml(path)
+
+          # A clouds.yaml that parses to a list or a scalar is a mistake worth
+          # naming, rather than a NoMethodError three frames later.
+          raise ActionFailed, "#{path} must contain a YAML mapping" unless data.is_a?(Hash)
+
+          [data, path]
+        end
+
+        # Parses one YAML document, turning a syntax error into a message that
+        # names the offending file.
+        #
+        # @param path [String] the file to parse
+        # @return [Object] the parsed document
+        # @raise [Kitchen::ActionFailed] if the file is not valid YAML
+        def parse_yaml(path)
+          YAML.safe_load_file(path, permitted_classes: [Date]) || {}
+        rescue Psych::Exception => e
+          raise ActionFailed, "Could not parse #{path}: #{e.message}"
         end
 
+        # Standard OpenStack client config search locations, highest priority
+        # first.
+        #
+        # @param filename [String] the file being looked for
+        # @param env_var [String] the environment variable that overrides it
+        # @return [Array<String>] candidate paths
         def clouds_yaml_search_paths(filename, env_var)
           paths = []
           paths << ENV[env_var] if ENV[env_var]
           paths << config[:clouds_yaml_path] if config[:clouds_yaml_path] && filename == "clouds.yaml"
           paths << File.join(Dir.pwd, filename)
-          paths << File.join(Dir.home, ".config", "openstack", filename)
+          home = user_home
+          paths << File.join(home, ".config", "openstack", filename) if home
           paths << File.join("/etc/openstack", filename)
           paths
         end
 
-        def extract_cloud(data, name)
-          clouds = data["clouds"] || {}
+        # The user's home directory, or nil if there isn't one.
+        #
+        # `Dir.home` raises when HOME is unset and the uid has no passwd entry,
+        # which is the ordinary state inside a container running as an arbitrary
+        # uid. That must not take out the whole search -- /etc/openstack is
+        # still worth trying.
+        #
+        # @return [String, nil] the home directory, or nil if it cannot be
+        #   determined
+        def user_home
+          Dir.home
+        rescue ArgumentError
+          nil
+        end
+
+        # Pulls one named cloud entry out of a parsed clouds/secure document.
+        #
+        # An absent entry is an empty hash: clouds.yaml and secure.yaml are
+        # merged, and it is normal for a cloud to appear in only one of them.
+        # An entry that is *present but not a mapping* is always a mistake, and
+        # is reported rather than silently discarded -- otherwise the driver
+        # carries on with nil credentials and the user sees an opaque Keystone
+        # auth failure that never mentions their config file.
+        #
+        # @param data [Hash] the parsed document
+        # @param name [String] the cloud name to extract
+        # @param source [String] the file the document came from, for errors
+        # @return [Hash] the cloud entry, or an empty hash if it is absent
+        # @raise [Kitchen::ActionFailed] if `clouds` or the named entry is
+        #   present but is not a mapping
+        def extract_cloud(data, name, source)
+          clouds = data["clouds"]
+          return {} if clouds.nil?
+          raise ActionFailed, "The clouds section of #{source} must be a YAML mapping" unless clouds.is_a?(Hash)
+
           cloud = clouds[name]
-          return {} unless cloud
+          return {} if cloud.nil?
+          raise ActionFailed, "Cloud <#{name}> in #{source} must be a YAML mapping" unless cloud.is_a?(Hash)
 
           cloud
         end
 
-        # Deep merge two hashes (secure overrides clouds)
+        # Recursively merges `override` onto `base` without mutating either.
+        #
+        # @param base [Hash] the lower-priority hash
+        # @param override [Hash] the higher-priority hash
+        # @return [Hash] a new merged hash
         def deep_merge(base, override)
           result = base.dup
           override.each do |key, value|
@@ -172,7 +262,10 @@ module Kitchen
           result
         end
 
-        # Convert a clouds.yaml cloud entry into Fog-compatible config keys
+        # Converts a clouds.yaml cloud entry into Fog-compatible config keys.
+        #
+        # @param cloud [Hash] a single cloud entry
+        # @return [Hash{Symbol => Object}] Fog config keys
         def translate_cloud_config(cloud)
           result = {}
 
@@ -196,6 +289,14 @@ module Kitchen
           result
         end
 
+        # Coerces values Fog insists on receiving as strings.
+        #
+        # YAML parses `identity_api_version: 3` and `project_id: 12345` as
+        # Integers, which Fog then fails on.
+        #
+        # @param fog_key [Symbol] the Fog config key
+        # @param value [Object] the raw value from YAML or the environment
+        # @return [Object] the value, stringified when the key requires it
         def normalize_config_value(fog_key, value)
           return value unless STRING_CONFIG_KEYS.include?(fog_key)
 

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

@@ -21,14 +21,66 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "etc" unless defined?(Etc)
+require "socket" unless defined?(Socket)
+
 module Kitchen
   module Driver
     class Openstack < Kitchen::Driver::Base
       # Server naming and configuration helpers
       module Config
-        # Set the proper server name in the config
+        # Longest server name OpenStack will accept without truncating.
+        #
+        # Every other length in this file is derived from it, so the limit is
+        # actually maintained by the code rather than merely documented here.
+        #
+        # @return [Integer]
+        MAX_SERVER_NAME_LENGTH = 63
+
+        # Number of random characters appended to a user-supplied prefix.
+        #
+        # @return [Integer]
+        PREFIX_SUFFIX_LENGTH = 8
+
+        # Longest user-supplied prefix that still leaves room for the
+        # separator and the random suffix.
+        #
+        # @return [Integer]
+        MAX_PREFIX_LENGTH = MAX_SERVER_NAME_LENGTH - PREFIX_SUFFIX_LENGTH - 1
+
+        # Character budget for the instance name in a fully generated name.
+        #
+        # @return [Integer]
+        NAME_INSTANCE_LENGTH = 15
+
+        # Character budget for the username in a fully generated name.
+        #
+        # @return [Integer]
+        NAME_USERNAME_LENGTH = 15
+
+        # Number of random characters in a fully generated name.
+        #
+        # @return [Integer]
+        NAME_RANDOM_LENGTH = 7
+
+        # Character budget for the hostname in a fully generated name.
+        #
+        # Whatever is left once the other three components and the three
+        # separators are accounted for.
+        #
+        # @return [Integer]
+        NAME_HOSTNAME_LENGTH =
+          MAX_SERVER_NAME_LENGTH - NAME_INSTANCE_LENGTH - NAME_USERNAME_LENGTH - NAME_RANDOM_LENGTH - 3
+
+        # Sets `config[:server_name]` unless the user already supplied one.
+        #
+        # Called at the top of {Kitchen::Driver::Openstack#create} rather than
+        # at config-finalize time so that the random suffix is generated once
+        # per converge instead of once per `kitchen` invocation.
+        #
+        # @return [String] the resolved server name
         def config_server_name
-          return if config[:server_name]
+          return config[:server_name] if config[:server_name]
 
           config[:server_name] = if config[:server_name_prefix]
                                    server_name_prefix(config[:server_name_prefix])
@@ -39,46 +91,61 @@ module Kitchen
 
         private
 
-        # 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 unique server name of at most 63 characters.
+        #
+        #     <instance>-<user>-<host>-<random>
+        #          15       15      23      7    + 3 separators = 63
+        #
+        # @return [String] the generated server name
         def default_name
           [
-            instance.name.gsub(/\W/, "")[0..14],
-            ((Etc.getpwuid ? Etc.getpwuid.name : Etc.getlogin) || "nologin").gsub(/\W/, "")[0..14],
-            Socket.gethostname.gsub(/\W/, "")[0..22],
-            Array.new(7) { rand(36).to_s(36) }.join,
+            instance.name.gsub(/\W/, "")[0, NAME_INSTANCE_LENGTH],
+            current_username.gsub(/\W/, "")[0, NAME_USERNAME_LENGTH],
+            Socket.gethostname.gsub(/\W/, "")[0, NAME_HOSTNAME_LENGTH],
+            Array.new(NAME_RANDOM_LENGTH) { rand(36).to_s(36) }.join,
           ].join("-")
         end
 
+        # Best-effort lookup of the name of the user running Test Kitchen.
+        #
+        # `Etc.getpwuid` raises `ArgumentError` rather than returning nil when
+        # the effective uid has no passwd entry, which is routine inside
+        # containers, so both failure modes fall through to `Etc.getlogin` and
+        # finally to a placeholder.
+        #
+        # @return [String] a username, or `"nologin"` if none can be determined
+        def current_username
+          (Etc.getpwuid&.name || Etc.getlogin || "nologin")
+        rescue ArgumentError
+          Etc.getlogin || "nologin"
+        end
+
+        # Generates a unique server name from a user-supplied prefix.
+        #
+        #     <prefix>-<random>
+        #      max 54      8     + 1 separator = 63
+        #
+        # Falls back to {#default_name} when the prefix contains nothing usable
+        # once non-word characters are stripped.
+        #
+        # @param server_name_prefix [String] the configured prefix; never
+        #   mutated, so the caller's config survives intact
+        # @return [String] the generated server name
         def server_name_prefix(server_name_prefix)
-          # Generate what should be a unique server name with given prefix
-          # of up to 63 total chars
-          #
-          # Provided prefix:  variable, max 54
-          # Separator:        1
-          # Random string:    8
-          # ===================
-          # Max:              63
-          #
-          if server_name_prefix.length > 54
-            warn "Server name prefix too long, truncated to 54 characters"
-            server_name_prefix = server_name_prefix[0..53]
+          prefix = server_name_prefix.to_s
+          if prefix.length > MAX_PREFIX_LENGTH
+            warn "Server name prefix too long, truncated to #{MAX_PREFIX_LENGTH} characters"
+            prefix = prefix[0, MAX_PREFIX_LENGTH]
           end
 
-          server_name_prefix.gsub!(/\W/, "")
+          prefix = prefix.gsub(/\W/, "")
 
-          if server_name_prefix.empty?
+          if prefix.empty?
             warn "Server name prefix empty or invalid; using fully generated name"
             default_name
           else
-            random_suffix = ("a".."z").to_a.sample(8).join
-            server_name_prefix + "-" + random_suffix
+            random_suffix = ("a".."z").to_a.sample(PREFIX_SUFFIX_LENGTH).join
+            "#{prefix}-#{random_suffix}"
           end
         end
       end

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

@@ -28,8 +28,20 @@ module Kitchen
     class Openstack < Kitchen::Driver::Base
       # Ohai hints, SSL handling, and server wait helpers
       module Helpers
+        # Seconds between progress dots while counting down.
+        #
+        # @return [Integer]
+        COUNTDOWN_TICK = 10
+
         private
 
+        # Drops an empty `openstack.json` ohai hint on the new instance so
+        # that Chef Infra's ohai run picks up OpenStack metadata.
+        #
+        # Does nothing on platforms that are neither Bourne-shell nor Windows.
+        #
+        # @param state [Hash] instance state, used to open a transport session
+        # @return [void]
         def add_ohai_hint(state)
           if bourne_shell?
             info "Adding OpenStack hint for ohai"
@@ -45,18 +57,40 @@ module Kitchen
             instance.transport.connection(state).execute(
               "#{touch_cmd} #{touch_cmd_args}"
             )
+          else
+            debug "Unknown platform shell; skipping the OpenStack ohai hint"
           end
         end
 
+        # The directory ohai reads hint files from.
+        #
+        # @return [String] the first configured ohai hints path
         def hints_path
           Ohai.config[:hints_path][0]
         end
 
+        # Turns off TLS peer verification for every subsequent Excon request in
+        # this process.
+        #
+        # Called when the `disable_ssl_validation` config key is set, which the
+        # user sets directly in kitchen.yml or which is inferred from a
+        # `verify: false` entry in clouds.yaml.
+        #
+        # @return [void]
         def disable_ssl_validation
           require "excon" unless defined?(Excon)
           Excon.defaults[:ssl_verify_peer] = false
         end
 
+        # Blocks until the transport reports the instance is reachable,
+        # destroying the instance if it never comes up.
+        #
+        # A server we cannot reach is a server we cannot clean up later, so the
+        # failure path tears it down before re-raising rather than leaking it.
+        #
+        # @param state [Hash] instance state, containing `:hostname`
+        # @return [void]
+        # @raise [StandardError] whatever the transport raised, after cleanup
         def wait_for_server(state)
           if config[:server_wait]
             info "Sleeping for #{config[:server_wait]} seconds to let your server start up..."
@@ -64,17 +98,22 @@ module Kitchen
           end
           info "Waiting for server to be ready..."
           instance.transport.connection(state).wait_until_ready
-        rescue
-          error "Server #{state[:hostname]} (#{state[:server_id]}) not reachable. Destroying server..."
+        rescue => e
+          error "Server #{state[:hostname]} (#{state[:server_id]}) not reachable: #{e.message}. Destroying server..."
           destroy(state)
           raise
         end
 
+        # Prints a progress dot every {COUNTDOWN_TICK} seconds for the given
+        # duration.
+        #
+        # @param seconds [Integer] how long to wait
+        # @return [void]
         def countdown(seconds)
-          date1 = Time.now + seconds
-          while Time.now < date1
+          finish_at = Time.now + seconds
+          while Time.now < finish_at
             Kernel.print "."
-            sleep 10
+            sleep COUNTDOWN_TICK
           end
         end
       end