kitchen-docker 3.3.0 → 3.3.3

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

@@ -24,44 +24,122 @@ 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, on a line of
+        # their own. The id is looked for line by line rather than by taking the
+        # whole output, because {CliHelper#run_command} returns stdout and stderr
+        # together and some daemons write warnings to stderr on a run that
+        # otherwise succeeds. Rootless Docker emits "WARNING: IPv4 forwarding is
+        # disabled. Networking will not work." on every run; setting
+        # +run_options+ to +--net=host+ produces "WARNING: Published ports are
+        # discarded when using host network mode", since the driver always
+        # publishes port 22 for Linux containers. Treating the whole output as
+        # the id failed those runs *after* the container had been created,
+        # leaving it running and untracked.
+        #
+        # Scanning forward is deterministic: +run_command+ concatenates stdout
+        # before stderr, so the id always precedes anything a warning adds.
+        #
+        # @param output [String] the command output, stdout and stderr together
+        # @return [String] the container id
+        # @raise [Kitchen::ActionFailed] if no id could be found
         def parse_container_id(output)
-          container_id = output.chomp
-
-          unless [12, 64].include?(container_id.size)
-            raise ActionFailed, "Could not parse Docker run output for container ID"
+          container_id = output.to_s.lines.map(&:strip).find do |line|
+            line.match?(/\A[0-9a-f]{12}(?:[0-9a-f]{52})?\z/)
           end
 
+          raise ActionFailed, "Could not parse Docker run output for container ID" unless container_id
+
           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
 
+        # Whether the container named in state is present, running or not.
+        #
+        # Asked with `docker inspect` rather than `docker top`, which answers a
+        # different question: `top` lists processes, so it fails on a container
+        # that exists but has stopped. Reading that as "does not exist" made
+        # {Kitchen::Docker::Container#destroy} skip removal and leave the
+        # container behind, while Test Kitchen deleted the state file and
+        # reported success.
+        #
+        # @param state [Hash] instance state naming the container
+        # @return [Boolean] whether the container exists in any state
         def container_exists?(state)
-          state[:container_id] && !!docker_command("top #{state[:container_id]}") rescue false
+          return false unless state[:container_id]
+
+          !!docker_command("inspect --type=container #{state[:container_id]}",
+            suppress_output: !logger.debug?)
+        rescue
+          false
+        end
+
+        # Whether the container named in state is running.
+        #
+        # Separate from {#container_exists?} because the two callers want
+        # different questions answered: destroy removes a container in any
+        # state, while create has to tell a container it can use from one that
+        # has stopped.
+        #
+        # @param state [Hash] instance state naming the container
+        # @return [Boolean] whether the container exists and is running
+        def container_running?(state)
+          return false unless state[:container_id]
+
+          output = docker_command(
+            "inspect --type=container --format '{{.State.Running}}' #{state[:container_id]}",
+            suppress_output: !logger.debug?
+          )
+          output.strip == "true"
+        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 +147,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 +169,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 +189,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 = {}
@@ -109,13 +206,28 @@ module Kitchen
           else
             cmd = build_exec_command(state, "printenv")
             stdout = docker_command(cmd, suppress_output: !logger.debug?).strip
-            stdout.split("\n").each { |line| vars[line.split("=")[0]] = line.split("=")[1] }
+            # printenv writes NAME=VALUE, and values routinely contain "=" --
+            # LS_COLORS and anything -Dkey=value shaped do. Split on the first
+            # one only, or the value is truncated at it. Lines with no "=" are
+            # continuations of a multi-line value and carry no name.
+            stdout.split("\n").each do |line|
+              name, value = line.split("=", 2)
+              vars[name] = value unless value.nil?
+            end
           end
 
           vars
         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 +242,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 +264,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

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

@@ -16,10 +16,20 @@ require "kitchen/configurable"
 
 module Kitchen
   module Docker
+    # Mixins shared by the driver, transport, and container classes.
     module Helpers
+      # Per-distribution Dockerfile fragments that prepare a Linux image for SSH.
       module DockerfileHelper
         include Configurable
 
+        # Dockerfile lines that prepare the configured platform for SSH.
+        #
+        # Each distribution needs its own package manager invocation to install an
+        # SSH server and sudo, and its own host-key generation, which is why there
+        # is one method per family rather than a shared one.
+        #
+        # @return [String] the RUN lines for this platform
+        # @raise [Kitchen::ActionFailed] if the platform is not recognised
         def dockerfile_platform
           case config[:platform]
           when "arch"
@@ -51,6 +61,9 @@ module Kitchen
           end
         end
 
+        # Dockerfile lines installing an SSH server and sudo on Arch Linux.
+        #
+        # @return [String] the RUN lines
         def arch_platform
           <<-CODE
             RUN pacman --noconfirm -Sy archlinux-keyring
@@ -60,6 +73,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on Debian and Ubuntu.
+        #
+        # @return [String] the RUN lines
         def debian_platform
           disable_upstart = <<-CODE
             RUN [ ! -f "/sbin/initctl" ] || dpkg-divert --local --rename --add /sbin/initctl \
@@ -74,6 +90,9 @@ module Kitchen
           config[:disable_upstart] ? disable_upstart + packages : packages
         end
 
+        # Dockerfile lines installing an SSH server and sudo on Fedora.
+        #
+        # @return [String] the RUN lines
         def fedora_platform
           <<-CODE
             ENV container=docker
@@ -83,6 +102,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on Gentoo with Portage.
+        #
+        # @return [String] the RUN lines
         def gentoo_platform
           <<-CODE
             RUN emerge-webrsync
@@ -91,6 +113,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on Gentoo with Paludis.
+        #
+        # @return [String] the RUN lines
         def gentoo_paludis_platform
           <<-CODE
             RUN cave sync
@@ -99,6 +124,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on openSUSE and SLES.
+        #
+        # @return [String] the RUN lines
         def opensuse_platform
           <<-CODE
             ENV container=docker
@@ -107,6 +135,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on RHEL, CentOS, and Oracle Linux.
+        #
+        # @return [String] the RUN lines
         def rhel_platform
           <<-CODE
             ENV container=docker
@@ -117,6 +148,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on Amazon Linux.
+        #
+        # @return [String] the RUN lines
         def amazonlinux_platform
           <<-CODE
             ENV container=docker
@@ -126,6 +160,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on CentOS Stream.
+        #
+        # @return [String] the RUN lines
         def centosstream_platform
           <<-CODE
             ENV container=docker
@@ -135,6 +172,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on AlmaLinux.
+        #
+        # @return [String] the RUN lines
         def almalinux_platform
           <<-CODE
             ENV container=docker
@@ -144,6 +184,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on Rocky Linux.
+        #
+        # @return [String] the RUN lines
         def rockylinux_platform
           <<-CODE
             ENV container=docker
@@ -153,6 +196,9 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines installing an SSH server and sudo on Photon OS.
+        #
+        # @return [String] the RUN lines
         def photonos_platform
           <<-CODE
             ENV container=docker
@@ -163,6 +209,14 @@ module Kitchen
           CODE
         end
 
+        # Dockerfile lines creating the login user and its SSH directory.
+        #
+        # The user gets passwordless sudo and +Defaults !requiretty+, because Test
+        # Kitchen runs commands non-interactively and sudo would otherwise refuse.
+        #
+        # @param username [String] the login user to create
+        # @param homedir [String] that user's home directory
+        # @return [String] the RUN lines
         def dockerfile_base_linux(username, homedir)
           <<-CODE
             RUN if ! getent passwd #{username}; then \

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

@@ -15,24 +15,38 @@ require "fileutils" unless defined?(FileUtils)
 
 module Kitchen
   module Docker
+    # Mixins shared by the driver, transport, and container classes.
     module Helpers
+      # Local temp-file handling.
       module FileHelper
+        # Writes a temp file, creating its parent directory if needed.
+        #
+        # Written with +File.write+, which opens, writes and closes in one call.
+        # The previous implementation assigned the open file back over the +file+
+        # parameter and closed it in an +ensure+, so when opening failed -- a
+        # read-only directory, a parent that is not a directory, a full disk --
+        # +file+ was still the path String and the ensure raised
+        # "undefined method 'close' for an instance of String", replacing the
+        # real error with a Ruby one. Its rescue did not help either: it caught
+        # +IOError+, while opening a file fails with +Errno+ classes, which are
+        # +SystemCallError+ and not +IOError+.
+        #
+        # @param file [String] path to write
+        # @param contents [String] what to write
+        # @return [void]
+        # @raise [RuntimeError] if the file cannot be written, naming the path
+        #   and the underlying cause
         def create_temp_file(file, contents)
           debug("[Docker] Creating temp file #{file}")
           debug("[Docker] --- Start Temp File Contents ---")
           debug(contents)
           debug("[Docker] --- End Temp File Contents ---")
 
-          begin
-            path = ::File.dirname(file)
-            ::FileUtils.mkdir_p(path) unless ::Dir.exist?(path)
-            file = ::File.open(file, "w")
-            file.write(contents)
-          rescue IOError => e
-            raise "Failed to write temp file. Error Details: #{e}"
-          ensure
-            file.close unless file.nil?
-          end
+          path = ::File.dirname(file)
+          ::FileUtils.mkdir_p(path) unless ::Dir.exist?(path)
+          ::File.write(file, contents)
+        rescue SystemCallError, IOError => e
+          raise "Failed to write temp file #{file}. Error Details: #{e}"
         end
       end
     end

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

@@ -19,12 +19,22 @@ require_relative "container_helper"
 
 module Kitchen
   module Docker
+    # Mixins shared by the driver, transport, and container classes.
     module Helpers
+      # Building, inspecting, and removing Docker images.
       module ImageHelper
         include Configurable
         include Kitchen::Docker::Helpers::CliHelper
         include Kitchen::Docker::Helpers::ContainerHelper
 
+        # Pulls the built image's id out of `docker build` output.
+        #
+        # Scanned in reverse, and against several patterns, because the wording has
+        # changed across Docker and BuildKit versions.
+        #
+        # @param output [String] the build output
+        # @return [String] the image id
+        # @raise [Kitchen::ActionFailed] if no id could be found
         def parse_image_id(output)
           output.split("\n").reverse_each do |line|
             if line =~ /writing image (sha256:[[:xdigit:]]{64})(?: \d*\.\ds)? done/i
@@ -44,6 +54,10 @@ module Kitchen
           raise ActionFailed, "Could not parse Docker build output for image ID"
         end
 
+        # Removes the built image, unless a container is still using it.
+        #
+        # @param state [Hash] instance state naming the image
+        # @return [void]
         def remove_image(state)
           image_id = state[:image_id]
           if image_in_use?(state)
@@ -54,10 +68,40 @@ module Kitchen
           end
         end
 
+        # Whether any container was created from the image.
+        #
+        # Asked with a filter rather than by searching `docker ps -a` output for
+        # the id. That output abbreviates the IMAGE column to twelve characters,
+        # while state carries the full +sha256:+ digest, so the substring never
+        # matched and the answer was always false -- which defeated the guard
+        # entirely and let {#remove_image} run `docker rmi` against an image a
+        # container was still using.
+        #
+        # @param state [Hash] instance state naming the image
+        # @return [Boolean] whether any container references it
         def image_in_use?(state)
-          docker_command("ps -a", suppress_output: !logger.debug?).include?(state[:image_id])
+          return false unless state[:image_id]
+
+          output = docker_command("ps -a -q --filter ancestor=#{state[:image_id]}",
+            suppress_output: !logger.debug?)
+
+          # Matched line by line rather than by emptiness, so a warning docker
+          # writes to stderr is not mistaken for a container id.
+          output.lines.map(&:strip).any? do |line|
+            line.match?(/\A[0-9a-f]{12}(?:[0-9a-f]{52})?\z/)
+          end
         end
 
+        # Builds the image from the given Dockerfile.
+        #
+        # The Dockerfile is written to a temp file and also passed on stdin, so the
+        # build works both with a build context and without one. The temp file is
+        # removed whether or not the build succeeded.
+        #
+        # @param state [Hash] instance state
+        # @param dockerfile [String] the Dockerfile contents
+        # @return [String] the new image's id
+        # @raise [Kitchen::ActionFailed] if the id cannot be parsed from the output
         def build_image(state, dockerfile)
           cmd = "build"
           cmd << " --no-cache" unless config[:use_cache]
@@ -82,6 +126,8 @@ module Kitchen
           parse_image_id(output)
         end
 
+        # @param state [Hash] instance state naming the image
+        # @return [Boolean] whether the image is present locally
         def image_exists?(state)
           state[:image_id] && !!docker_command("inspect --type=image #{state[:image_id]}") rescue false
         end

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

@@ -52,6 +52,7 @@ end
 
 module Kitchen
   module Docker
+    # Mixins shared by the driver, transport, and container classes.
     module Helpers
       # Marker module included by the Docker transport Connection class.
       # Actual verifier patches are applied directly to verifier classes above.

data/lib/kitchen/driver/docker.rb

@@ -26,6 +26,7 @@ require_relative "../docker/helpers/cli_helper"
 require_relative "../docker/helpers/container_helper"
 
 module Kitchen
+  # Test Kitchen's driver plugins.
   module Driver
     # Docker driver for Kitchen.
     #
@@ -111,28 +112,50 @@ module Kitchen
         end
       end
 
+      # Checks that the Docker CLI is installed and runnable.
+      #
+      # @return [void]
+      # @raise [Kitchen::UserError] if the binary cannot be run
       def verify_dependencies
         run_command("#{config[:binary]} >> #{dev_null} 2>&1", quiet: true, use_sudo: config[:use_sudo])
       rescue
         raise UserError, "You must first install the Docker CLI tool https://www.docker.com/get-started"
       end
 
+      # Builds the image and starts the container.
+      #
+      # @param state [Hash] mutable instance state
+      # @return [void]
       def create(state)
         container.create(state)
 
         wait_for_transport(state)
       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)
         container.destroy(state)
       end
 
+      # Waits for the transport to accept a connection, unless disabled.
+      #
+      # @param state [Hash] instance state describing how to connect
+      # @return [void]
       def wait_for_transport(state)
         if config[:wait_for_transport]
           instance.transport.connection(state, &:wait_until_ready)
         end
       end
 
+      # The Docker image implied by the platform name.
+      #
+      # +ubuntu-22.04+ becomes +ubuntu:22.04+. CentOS is special-cased, since its
+      # images are tagged +centos7+ rather than +centos:7+.
+      #
+      # @return [String] an image reference
       def default_image
         platform, release = instance.platform.name.split("-")
         if platform == "centos" && release
@@ -141,12 +164,16 @@ module Kitchen
         release ? [platform, release].join(":") : platform
       end
 
+      # @return [String] the platform family, e.g. +ubuntu+ from +ubuntu-22.04+
       def default_platform
         instance.platform.name.split("-").first
       end
 
       protected
 
+      # The container implementation for this platform.
+      #
+      # @return [Kitchen::Docker::Container] a Windows or Linux container
       def container
         @container ||= if windows_os?
                          Kitchen::Docker::Container::Windows.new(config)