kitchen-docker 3.3.0 → 3.3.1

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,8 +15,16 @@ 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.
+        #
+        # @param file [String] path to write
+        # @param contents [String] what to write
+        # @return [void]
+        # @raise [RuntimeError] if the write fails
         def create_temp_file(file, contents)
           debug("[Docker] Creating temp file #{file}")
           debug("[Docker] --- Start Temp File Contents ---")

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,22 @@ module Kitchen
           end
         end
 
+        # @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])
         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 +108,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)

data/lib/kitchen/transport/docker.rb

@@ -21,8 +21,14 @@ require_relative "../docker/helpers/inspec_helper"
 # require_relative "../../docker/version"
 
 module Kitchen
+  # Test Kitchen's transport plugins.
   module Transport
+    # Test Kitchen transport that runs commands inside a Docker container.
+    #
+    # Commands go through `docker exec` rather than a network protocol, so no
+    # SSH or WinRM server is needed inside the image.
     class Docker < Kitchen::Transport::Base
+      # Raised when a docker command against the container fails.
       class DockerFailed < TransportFailed; end
 
       # kitchen_transport_api_version 1
@@ -64,6 +70,15 @@ module Kitchen
         end
       end
 
+      # Builds a connection to the container.
+      #
+      # +DOCKER_HOST+ is exported here because the docker-api gem, used by the
+      # InSpec verifier, reads the daemon address from the environment rather
+      # than from Test Kitchen's configuration.
+      #
+      # @param state [Hash] instance state naming the container
+      # @yieldparam connection [Connection] if a block is given
+      # @return [Connection]
       def connection(state, &block)
         options = config.to_hash.merge(state)
         options[:platform] = instance.platform.name
@@ -77,10 +92,19 @@ module Kitchen
         Kitchen::Transport::Docker::Connection.new(options, &block)
       end
 
-      class Connection < Kitchen::Transport::Docker::Connection
+      # A connection to one container.
+      #
+      # The superclass is named in full rather than relying on Ruby resolving
+      # the bare `Connection` constant through this class's ancestors.
+      class Connection < Kitchen::Transport::Base::Connection
         # Include the InSpec patches to be able to execute tests on Windows containers
         include Kitchen::Docker::Helpers::InspecHelper
 
+        # Runs a command inside the container.
+        #
+        # @param command [String] the command to run; nil is a no-op
+        # @return [void]
+        # @raise [DockerFailed] if the command fails
         def execute(command)
           return if command.nil?
 
@@ -92,10 +116,18 @@ module Kitchen
           raise DockerFailed, "Docker failed to execute command on container. Error Details: #{e}"
         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)
           container.upload(locals, remote)
         end
 
+        # The container implementation for this platform.
+        #
+        # @return [Kitchen::Docker::Container] a Windows or Linux container
         def container
           @container ||= if windows_container?
                            Kitchen::Docker::Container::Windows.new(@options)
@@ -105,7 +137,13 @@ module Kitchen
           @container
         end
 
-        # (see Base::Connection#login_command)
+        # The command `kitchen login` execs to open a shell in the container.
+        #
+        # Documented here rather than inherited via `(see ...)`, because the
+        # superclass lives in the test-kitchen gem and YARD cannot resolve a
+        # reference into it from this project's docs.
+        #
+        # @return [Kitchen::LoginCommand] an interactive `docker exec` session
         def login_command
           argv = build_login_command
           LoginCommand.new(argv.first, argv.drop(1))
@@ -113,6 +151,7 @@ module Kitchen
 
         private
 
+        # @return [Boolean] whether the platform under test is Windows
         def windows_container?
           @options[:platform].to_s.include?("windows")
         end
@@ -150,6 +189,8 @@ module Kitchen
           docker + cmd
         end
 
+        # @return [Array<String>] the shell to drop the user into, PowerShell on
+        #   Windows and an interactive login bash elsewhere
         def login_shell
           windows_container? ? ["powershell"] : ["/bin/bash", "--login", "-i"]
         end