kitchen-docker 3.2.4 → 3.3.1

data/Rakefile

@@ -16,4 +16,22 @@ rescue LoadError
   puts "cookstyle/chefstyle is not available. (sudo) gem install cookstyle to do style checking."
 end
 
+begin
+  require "yard"
+
+  # Options and the file list live in .yardopts so that a bare `yard` from the
+  # command line produces exactly what `rake doc` does.
+  YARD::Rake::YardocTask.new(:doc)
+
+  desc "List anything in lib/ that is still undocumented"
+  task :doc_coverage do
+    sh "yard stats --list-undoc"
+  end
+rescue LoadError
+  desc "Generate YARD documentation (not installed)"
+  task :doc do
+    abort "YARD is not installed. Run: bundle install"
+  end
+end
+
 task default: %i{style test}

data/kitchen-docker.gemspec

@@ -3,14 +3,15 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "kitchen/docker/docker_version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "kitchen-docker"
+  spec.name = "kitchen-docker"
+  spec.required_ruby_version = ">= 3.1"
   spec.version       = Kitchen::Docker::DOCKER_VERSION
   spec.authors       = ["Sean Porter"]
   spec.email         = ["portertech@gmail.com"]
   spec.description   = %q{A Docker Driver for Test Kitchen}
   spec.summary       = spec.description
   spec.homepage      = "https://github.com/test-kitchen/kitchen-docker"
-  spec.license       = "Apache 2.0"
+  spec.license       = "Apache-2.0"
 
   spec.files         = `git ls-files`.split($/)
   spec.require_paths = ["lib"]

data/lib/kitchen/docker/container/linux.rb

@@ -22,15 +22,28 @@ require_relative "../helpers/dockerfile_helper"
 module Kitchen
   module Docker
     class Container
+      # A Linux container, reached over SSH.
+      #
+      # The generated image installs and runs an SSH server, and Test Kitchen
+      # connects to a published port with a generated key. That is why the
+      # Dockerfile here is so much larger than the Windows one.
       class Linux < Kitchen::Docker::Container
         include Kitchen::Docker::Helpers::DockerfileHelper
 
+        # Serializes SSH key generation across concurrently running instances,
+        # which share one key path.
         MUTEX_FOR_SSH_KEYS = Mutex.new
 
+        # @param config [Hash] the driver configuration
         def initialize(config)
           super
         end
 
+        # Builds the image, runs the container, and publishes its SSH port.
+        #
+        # @param state [Hash] mutable instance state; gains +ssh_key+, +image_id+,
+        #   +container_id+, +hostname+, and +port+
+        # @return [void]
         def create(state)
           super
 
@@ -44,6 +57,15 @@ module Kitchen
           state[:port] = container_ssh_port(state)
         end
 
+        # Runs a command in the container by uploading it as a shell script.
+        #
+        # The command is written to a temp file and executed with bash rather than
+        # passed on the command line, which keeps long converge scripts clear of
+        # argument-length and quoting limits.
+        #
+        # @param command [String] the shell code to run
+        # @return [String] the command's combined output
+        # @raise [RuntimeError] if the command fails
         def execute(command)
           # Create temp script file and upload files to container
           debug("Executing command on Linux container (Platform: #{@config[:platform]})")
@@ -72,6 +94,12 @@ module Kitchen
 
         protected
 
+        # Generates the SSH keypair used to log into Linux containers.
+        #
+        # Guarded by {MUTEX_FOR_SSH_KEYS} because concurrent instances share one
+        # key path and would otherwise write the file while another reads it.
+        #
+        # @return [void]
         def generate_keys
           MUTEX_FOR_SSH_KEYS.synchronize do
             if !File.exist?(@config[:public_key]) || !File.exist?(@config[:private_key])
@@ -90,6 +118,11 @@ module Kitchen
           end
         end
 
+        # Pulls the published port out of `docker port` output.
+        #
+        # @param output [String] e.g. +"0.0.0.0:32768"+
+        # @return [Integer] the host-side port
+        # @raise [Kitchen::ActionFailed] if the output cannot be parsed
         def parse_container_ssh_port(output)
           _host, port = output.split(":")
           port.to_i
@@ -97,6 +130,15 @@ module Kitchen
           raise ActionFailed, "Could not parse Docker port output for container SSH port. #{e}"
         end
 
+        # The port Test Kitchen should connect to for SSH.
+        #
+        # On the internal Docker network the container is reached directly, so the
+        # unmapped port 22 is correct; otherwise Docker's published mapping is
+        # looked up.
+        #
+        # @param state [Hash] instance state naming the container
+        # @return [Integer] the port to connect on
+        # @raise [Kitchen::ActionFailed] if no SSH port is mapped
         def container_ssh_port(state)
           return 22 if @config[:use_internal_docker_network]
 
@@ -106,6 +148,14 @@ module Kitchen
           raise ActionFailed, "Docker reports container has no ssh port mapped. #{e}"
         end
 
+        # Builds the Dockerfile for a Linux container.
+        #
+        # A configured +dockerfile+ is used as-is after ERB rendering. Otherwise
+        # one is generated: the base image, proxy settings, the platform's own
+        # package setup, any +provision_command+ entries, and the generated public
+        # key appended to the login user's authorized_keys.
+        #
+        # @return [String] the Dockerfile contents
         def dockerfile
           return dockerfile_template if @config[:dockerfile]
 

data/lib/kitchen/docker/container/windows.rb

@@ -18,11 +18,25 @@ require_relative "../container"
 module Kitchen
   module Docker
     class Container
+      # A Windows container, driven through `docker exec`.
+      #
+      # There is no SSH server and no key to inject: commands are uploaded as
+      # PowerShell scripts and executed in the container directly, so no port
+      # is published.
       class Windows < Kitchen::Docker::Container
+        # @param config [Hash] the driver configuration
         def initialize(config)
           super
         end
 
+        # Builds the image and runs the container.
+        #
+        # No port is published: Windows containers are driven through `docker exec`
+        # rather than SSH, so there is nothing to map.
+        #
+        # @param state [Hash] mutable instance state; gains +username+, +image_id+,
+        #   +container_id+, and +hostname+
+        # @return [void]
         def create(state)
           super
 
@@ -33,6 +47,11 @@ module Kitchen
           state[:hostname] = hostname(state)
         end
 
+        # Runs a command in the container by uploading it as a PowerShell script.
+        #
+        # @param command [String] the PowerShell code to run
+        # @return [String] the command's combined output
+        # @raise [RuntimeError] if the command fails
         def execute(command)
           # Create temp script file and upload files to container
           debug("Executing command on Windows container")
@@ -62,6 +81,14 @@ module Kitchen
 
         protected
 
+        # Builds the Dockerfile for a Windows container.
+        #
+        # Much shorter than the Linux equivalent: there is no SSH server and no
+        # key to inject, so only the base image, proxy settings, and any
+        # +provision_command+ entries are emitted.
+        #
+        # @return [String] the Dockerfile contents
+        # @raise [Kitchen::ActionFailed] if the platform is not +windows+
         def dockerfile
           raise ActionFailed, "Unknown platform '#{@config[:platform]}'" unless @config[:platform] == "windows"
           return dockerfile_template if @config[:dockerfile]

data/lib/kitchen/docker/container.rb

@@ -18,16 +18,33 @@ require_relative "helpers/image_helper"
 
 module Kitchen
   module Docker
+    # Base class for the container the instance under test runs in.
+    #
+    # Holds the behaviour that is the same on every platform -- checking
+    # whether the container exists, removing it, working out its address, and
+    # copying files in. {Linux} and {Windows} add how the image is built and
+    # how commands are run, which share almost nothing.
     class Container
       include Kitchen::Docker::Helpers::CliHelper
       include Kitchen::Docker::Helpers::ContainerHelper
       include Kitchen::Docker::Helpers::FileHelper
       include Kitchen::Docker::Helpers::ImageHelper
 
+      # @param config [Hash] the driver or transport configuration
       def initialize(config)
         @config = config
       end
 
+      # Checks the container named in state and records the login user.
+      #
+      # A state file naming a container that no longer exists is an error rather
+      # than something to build over, because the stale id usually means the
+      # container was removed behind Test Kitchen's back and silently creating a
+      # new one would hide that.
+      #
+      # @param state [Hash] mutable instance state; gains +username+
+      # @return [void]
+      # @raise [Kitchen::ActionFailed] if state names a container that is gone
       def create(state)
         if container_exists?(state)
           info("Container ID #{state[:container_id]} already exists.")
@@ -39,6 +56,10 @@ module Kitchen
         state[:username] = @config[:username]
       end
 
+      # Removes the container, and its image when +remove_images+ is set.
+      #
+      # @param state [Hash] instance state naming the container
+      # @return [void]
       def destroy(state)
         info("[Docker] Destroying Docker container #{state[:container_id]}") if state[:container_id]
         remove_container(state) if container_exists?(state)
@@ -48,6 +69,14 @@ module Kitchen
         end
       end
 
+      # Works out the address Test Kitchen should connect to.
+      #
+      # A remote Docker socket means the container is reachable at the socket's
+      # own host; +use_internal_docker_network+ means its container IP; anything
+      # else is a published port on localhost.
+      #
+      # @param state [Hash] instance state naming the container
+      # @return [String] a hostname or IP address
       def hostname(state)
         hostname = "localhost"
 
@@ -60,6 +89,11 @@ module Kitchen
         hostname
       end
 
+      # Copies local files into the container.
+      #
+      # @param locals [String, Array<String>] one path or several
+      # @param remote [String] destination path inside the container
+      # @return [Array<String>] the files copied
       def upload(locals, remote)
         files = locals
         files = Array(locals) unless locals.is_a?(Array)

data/lib/kitchen/docker/docker_version.rb

@@ -13,9 +13,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+# Test Kitchen's top-level namespace.
 module Kitchen
+  # Everything belonging to the kitchen-docker plugin.
   module Docker
-    # Version string for Docker Kitchen driver
-    DOCKER_VERSION = "3.2.4".freeze
+    # The version of the kitchen-docker gem.
+    DOCKER_VERSION = "3.3.1".freeze
   end
 end

data/lib/kitchen/docker/erb_context.rb

@@ -17,13 +17,22 @@ require "erb" unless defined?(Erb)
 
 module Kitchen
   module Docker
+    # Evaluation context for a user-supplied Dockerfile template.
+    #
+    # Each configuration key becomes an instance variable, so a template can
+    # refer to +@image+, +@username+, and the rest.
     class ERBContext
+      # Exposes each config key to the template as an instance variable, so a
+      # custom Dockerfile can refer to +@image+, +@username+, and the rest.
+      #
+      # @param config [Hash] the configuration to expose
       def initialize(config = {})
         config.each do |key, value|
           instance_variable_set("@" + key.to_s, value)
         end
       end
 
+      # @return [Binding] a binding for ERB to evaluate the template in
       def get_binding
         binding
       end

data/lib/kitchen/docker/helpers/cli_helper.rb

@@ -18,14 +18,22 @@ require "kitchen/shell_out"
 
 module Kitchen
   module Docker
+    # Mixins shared by the driver, transport, and container classes.
     module Helpers
-      # rubocop:disable Metrics/ModuleLength, Style/Documentation
+      # rubocop:disable Metrics/ModuleLength
+      # Builds and runs docker CLI command lines.
       module CliHelper
         include Configurable
         include Logging
         include ShellOut
 
         # rubocop:disable Metrics/AbcSize
+
+        # Runs a docker CLI command with the configured connection flags.
+        #
+        # @param cmd [String] the docker subcommand and its arguments
+        # @param options [Hash] shell-out options
+        # @return [String] the command's combined stdout and stderr
         def docker_command(cmd, options = {})
           docker = config[:binary].dup
           docker << " -H #{config[:socket]}" if config[:socket]
@@ -39,8 +47,17 @@ module Kitchen
         end
         # rubocop:enable Metrics/AbcSize
 
-        # Copied from kitchen because we need stderr
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+
+        # Runs a shell command, returning stderr as well as stdout.
+        #
+        # Test Kitchen's own +run_command+ discards stderr, but docker writes build
+        # progress and image ids there, so this reimplements it to keep both.
+        #
+        # @param cmd [String] the command to run
+        # @param options [Hash] shell-out options
+        # @return [String] combined stdout and stderr
+        # @raise [Kitchen::ShellCommandFailed] if the command exits non-zero
         def run_command(cmd, options = {})
           if options.fetch(:use_sudo, false)
             cmd = "#{options.fetch(:sudo_command, "sudo -E")} #{cmd}"
@@ -62,6 +79,12 @@ module Kitchen
         # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
 
         # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Metrics/AbcSize
+
+        # Builds the `docker run` command line from the configuration.
+        #
+        # @param image_id [String] the image to run
+        # @param transport_port [Integer, nil] container port to publish, if any
+        # @return [String] the docker subcommand and its arguments
         def build_run_command(image_id, transport_port = nil)
           cmd = "run -d"
           cmd << " -i" if config[:interactive]
@@ -100,6 +123,12 @@ module Kitchen
         # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength, Metrics/AbcSize
 
         # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize
+
+        # Builds a `docker exec` command line from the configuration.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param command [String] the command to run inside it
+        # @return [String] the docker subcommand and its arguments
         def build_exec_command(state, command)
           cmd = "exec"
           cmd << " -d" if config[:detach]
@@ -116,6 +145,12 @@ module Kitchen
         end
         # rubocop:enable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/AbcSize
 
+        # Builds a `docker cp` command line.
+        #
+        # @param local_file [String] source path
+        # @param remote_file [String] destination, as +container:path+
+        # @param opts [Hash] +:archive+ to preserve ownership and mode
+        # @return [String] the docker subcommand and its arguments
         def build_copy_command(local_file, remote_file, opts = {})
           cmd = "cp"
           cmd << " -a" if opts[:archive]
@@ -123,6 +158,10 @@ module Kitchen
           cmd
         end
 
+        # Wraps PowerShell code so it can be run through `docker exec`.
+        #
+        # @param args [String] the PowerShell arguments
+        # @return [String] the full powershell invocation
         def build_powershell_command(args)
           cmd = "powershell -ExecutionPolicy Bypass -NoLogo "
           cmd << args
@@ -130,6 +169,11 @@ module Kitchen
           cmd
         end
 
+        # Turns a hash of environment variables into `-e` flags.
+        #
+        # @param vars [Hash] variable names to values
+        # @return [String] the flags, each preceded by a space
+        # @raise [Kitchen::ActionFailed] if given something other than a Hash
         def build_env_variable_args(vars)
           raise ActionFailed, "Environment variables are not of a Hash type" unless vars.is_a?(Hash)
 
@@ -141,6 +185,8 @@ module Kitchen
           args
         end
 
+        # @return [String] the platform's null device, +NUL+ on Windows and
+        #   +/dev/null+ everywhere else
         def dev_null
           case RbConfig::CONFIG["host_os"]
           when /mswin|msys|mingw|cygwin|bccwin|wince|emc/
@@ -150,6 +196,13 @@ module Kitchen
           end
         end
 
+        # Normalizes shell-out options for a docker command.
+        #
+        # Translates +:suppress_output+ into silencing the live stream, and removes
+        # it, since Mixlib::ShellOut would reject the unknown key.
+        #
+        # @param options [Hash] the options to normalize
+        # @return [Hash] options Mixlib::ShellOut accepts
         def docker_shell_opts(options = {})
           options[:live_stream] = nil if options[:suppress_output]
           options.delete(:suppress_output)
@@ -178,7 +231,7 @@ module Kitchen
         end
         # rubocop:enable Metrics/CyclomaticComplexity
       end
-      # rubocop:enable Metrics/ModuleLength, Style/Documentation
+      # rubocop:enable Metrics/ModuleLength
     end
   end
 end

data/lib/kitchen/docker/helpers/container_helper.rb

@@ -24,12 +24,22 @@ require_relative "cli_helper"
 
 module Kitchen
   module Docker
+    # Mixins shared by the driver, transport, and container classes.
     module Helpers
-      # rubocop:disable Metrics/ModuleLength, Style/Documentation
+      # rubocop:disable Metrics/ModuleLength
+      # Operations against a running container: exec, copy, inspect, remove.
       module ContainerHelper
         include Configurable
         include Kitchen::Docker::Helpers::CliHelper
 
+        # Pulls the container id out of `docker run` output.
+        #
+        # Docker prints ids in short (12) or full (64) hex form; anything else
+        # means the output was not an id at all.
+        #
+        # @param output [String] the command output
+        # @return [String] the container id
+        # @raise [Kitchen::ActionFailed] if no id could be parsed
         def parse_container_id(output)
           container_id = output.chomp
 
@@ -40,28 +50,49 @@ module Kitchen
           container_id
         end
 
+        # Renders the configured Dockerfile through ERB.
+        #
+        # @return [String] the rendered Dockerfile
         def dockerfile_template
           template = IO.read(File.expand_path(config[:dockerfile]))
           context = Kitchen::Docker::ERBContext.new(config.to_hash)
           ERB.new(template).result(context.get_binding)
         end
 
+        # @return [Boolean] whether the configured socket is a TCP one, meaning
+        #   the daemon is not on this machine
         def remote_socket?
           config[:socket] ? socket_uri.scheme == "tcp" : false
         end
 
+        # @return [URI] the configured Docker socket
         def socket_uri
           URI.parse(config[:socket])
         end
 
+        # The path to pass to `docker build -f`.
+        #
+        # With a build context the path has to be relative to it; without one
+        # docker reads the Dockerfile from stdin and the absolute path is fine.
+        #
+        # @param file [File] the temp Dockerfile
+        # @return [String] the path to use
         def dockerfile_path(file)
           config[:build_context] ? Pathname.new(file.path).relative_path_from(Pathname.pwd).to_s : file.path
         end
 
+        # @param state [Hash] instance state naming the container
+        # @return [Boolean] whether the container is present and running
         def container_exists?(state)
           state[:container_id] && !!docker_command("top #{state[:container_id]}") rescue false
         end
 
+        # Runs a command inside the container.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param command [String] the command to run
+        # @return [String] the command's combined output
+        # @raise [RuntimeError] if the command fails
         def container_exec(state, command)
           cmd = build_exec_command(state, command)
           docker_command(cmd)
@@ -69,6 +100,13 @@ module Kitchen
           raise "Failed to execute command on Docker container. #{e}"
         end
 
+        # Creates a directory inside the container, on Linux or Windows.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param path [String] the directory to create; environment variable
+        #   references are expanded first
+        # @return [String] the command's combined output
+        # @raise [RuntimeError] if the directory cannot be created
         def create_dir_on_container(state, path)
           path = replace_env_variables(state, path)
           cmd = "mkdir -p #{path}"
@@ -84,6 +122,13 @@ module Kitchen
           raise "Failed to create directory #{path} on container. #{e}"
         end
 
+        # Copies a local file into the container.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param local_file [String] source path
+        # @param remote_file [String] destination path inside the container
+        # @return [String] the command's combined output
+        # @raise [RuntimeError] if the copy fails
         def copy_file_to_container(state, local_file, remote_file)
           debug("Copying local file #{local_file} to #{remote_file} on container")
 
@@ -97,6 +142,11 @@ module Kitchen
         end
 
         # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+
+        # Reads the container's environment.
+        #
+        # @param state [Hash] instance state naming the container
+        # @return [Hash] variable names to values
         def container_env_variables(state)
           # Retrieves all environment variables from inside container
           vars = {}
@@ -116,6 +166,14 @@ module Kitchen
         end
         # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
 
+        # Expands a container-side environment variable reference in a path.
+        #
+        # Handles both +$env:TEMP+ and +$TEMP+ forms. The value has to be read from
+        # inside the container, since the workstation's environment is unrelated.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param str [String] the string to expand
+        # @return [String] the expanded string
         def replace_env_variables(state, str)
           if str.include?("$env:")
             key = str[/\$env:(.*?)(\\|$)/, 1]
@@ -130,12 +188,20 @@ module Kitchen
           str
         end
 
+        # Runs the container and returns its id.
+        #
+        # @param state [Hash] instance state naming the image
+        # @param transport_port [Integer, nil] container port to publish, if any
+        # @return [String] the new container's id
         def run_container(state, transport_port = nil)
           cmd = build_run_command(state[:image_id], transport_port)
           output = docker_command(cmd)
           parse_container_id(output)
         end
 
+        # @param state [Hash] instance state naming the container
+        # @return [String] the container's address on the Docker network
+        # @raise [Kitchen::ActionFailed] if it cannot be determined
         def container_ip_address(state)
           cmd = "inspect --format '{{ .NetworkSettings.IPAddress }}'"
           cmd << " #{state[:container_id]}"
@@ -144,35 +210,41 @@ module Kitchen
           raise ActionFailed, "Error getting internal IP of Docker container"
         end
 
+        # Stops and removes the container.
+        #
+        # @param state [Hash] instance state naming the container
+        # @return [void]
         def remove_container(state)
           container_id = state[:container_id]
           docker_command("stop -t 0 #{container_id}")
           docker_command("rm #{container_id}")
         end
 
-        # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        # Dockerfile ENV lines carrying the configured proxy settings.
+        #
+        # Each is emitted in both lower and upper case, because different tools
+        # inside the image read different spellings.
+        #
+        # @return [String] the ENV lines, empty when no proxy is configured
         def dockerfile_proxy_config
-          env_variables = ""
-          if config[:http_proxy]
-            env_variables << "ENV http_proxy=#{config[:http_proxy]}\n"
-            env_variables << "ENV HTTP_PROXY=#{config[:http_proxy]}\n"
-          end
-
-          if config[:https_proxy]
-            env_variables << "ENV https_proxy=#{config[:https_proxy]}\n"
-            env_variables << "ENV HTTPS_PROXY=#{config[:https_proxy]}\n"
-          end
+          %i{http_proxy https_proxy no_proxy}.map do |proxy_type|
+            proxy_env_vars(proxy_type)
+          end.join
+        end
 
-          if config[:no_proxy]
-            env_variables << "ENV no_proxy=#{config[:no_proxy]}\n"
-            env_variables << "ENV NO_PROXY=#{config[:no_proxy]}\n"
-          end
+        # ENV lines for one proxy setting, in both spellings.
+        #
+        # @param proxy_type [Symbol] +:http_proxy+, +:https_proxy+, or
+        #   +:no_proxy+
+        # @return [String] two ENV lines, or empty when that proxy is unset
+        def proxy_env_vars(proxy_type)
+          return "" unless config[proxy_type]
 
-          env_variables
+          value = config[proxy_type]
+          "ENV #{proxy_type}=#{value}\nENV #{proxy_type.upcase}=#{value}\n"
         end
-        # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
       end
-      # rubocop:enable Metrics/ModuleLength, Style/Documentation
+      # rubocop:enable Metrics/ModuleLength
     end
   end
 end