kitchen-docker 3.3.4 → 3.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be40fecdd59251c4d7b1a20de831bd939fd7018ce19d19a2a2f205ac2464f4fb
-  data.tar.gz: 04b4579a2569e8be9f943d77eca1d4fd9f5e72e2aefc2ad3009855bf1e565935
+  metadata.gz: 2d994f876f76b4950f4f85521fba2ed15fe2ed54d06b9993d464a578f2fd9c69
+  data.tar.gz: d942290a8f115d5b0937421b747ec3f413e180fd55cfc8af245524b8337b27d5
 SHA512:
-  metadata.gz: d14d1fcddd8c823cc51231351311d2130bb9e9dd8355bb09e0551635a982a38b8abc52fca32cb03b5813d484bc256a688574ad8da6ef44a3d20525bdeac8fb21
-  data.tar.gz: 93f7faf2b089f727c6c78808b6c3e4d3fc9234e22a4defa21a0b463b61992324d8ecd26fb5bb9bfbc7da415d00234c67815d7bc20e889c563da50324c76c1040
+  metadata.gz: 7db4fee864798aa758a3e253f433db4e120d7247e8b5125e34764cf393f4836c9885eb3df2eff767501a6910c2f895b4efab467b8a24f7e1ad6120cc58eeede2
+  data.tar.gz: f80f60d52168ea008378af1cb66530136bf1e53b6474b75877a9275ff336f0ae632f754833f3e3db7aadd2c0f3910d64269fd39be0bb3a90baf5367d6708f115

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "3.3.4"
+  ".": "3.4.1"
 }

data/CHANGELOG.md

@@ -6,6 +6,32 @@ Future CHANGELOG notes will be in GitHub release notes
 
 * Docs: document the last four options and split contributor docs ([#463](https://github.com/test-kitchen/kitchen-docker/pull/463)) ([4818bce](https://github.com/test-kitchen/kitchen-docker/commit/4818bce))
 
+## [3.4.1](https://github.com/test-kitchen/kitchen-docker/compare/v3.4.0...v3.4.1) (2026-08-30)
+
+
+### Bug Fixes
+
+* quote container paths interpolated into docker exec command lines ([#496](https://github.com/test-kitchen/kitchen-docker/issues/496)) ([ae3a754](https://github.com/test-kitchen/kitchen-docker/commit/ae3a754046cdb7c6d9fdb8622a6cef818643ad56))
+* read the image id from a quiet build ([#489](https://github.com/test-kitchen/kitchen-docker/issues/489)) ([ddc58b5](https://github.com/test-kitchen/kitchen-docker/commit/ddc58b50a16b7236ed047071228f5641092060a1))
+* report this gem's own version to kitchen diagnose ([#490](https://github.com/test-kitchen/kitchen-docker/issues/490)) ([e28171d](https://github.com/test-kitchen/kitchen-docker/commit/e28171d268ab0a4950c0d553fcee12688663e626))
+
+## [3.4.0](https://github.com/test-kitchen/kitchen-docker/compare/v3.3.5...v3.4.0) (2026-08-23)
+
+
+### Features
+
+* implement the driver's package, doctor, and status hooks ([#491](https://github.com/test-kitchen/kitchen-docker/issues/491)) ([1366895](https://github.com/test-kitchen/kitchen-docker/commit/13668957b5b802f91c30aa7e34fc1b9f761e3b8d))
+
+## [3.3.5](https://github.com/test-kitchen/kitchen-docker/compare/v3.3.4...v3.3.5) (2026-08-23)
+
+
+### Bug Fixes
+
+* report when docker cp silently writes nothing ([#487](https://github.com/test-kitchen/kitchen-docker/issues/487)) ([1bc62ba](https://github.com/test-kitchen/kitchen-docker/commit/1bc62ba615d25d402a97775dbf6ac252af5cbdd8))
+* require test-kitchen 3.0 or newer ([#492](https://github.com/test-kitchen/kitchen-docker/issues/492)) ([0c64225](https://github.com/test-kitchen/kitchen-docker/commit/0c64225dd22aca8a2a32e6f61a6d648bcd8c0b2b))
+* run every docker command through sudo when use_sudo is set ([#485](https://github.com/test-kitchen/kitchen-docker/issues/485)) ([2481aad](https://github.com/test-kitchen/kitchen-docker/commit/2481aadfc6415e5b7ed597e1095d0fe8db89afbb))
+* stop printing the image inspect JSON on destroy ([#488](https://github.com/test-kitchen/kitchen-docker/issues/488)) ([0011558](https://github.com/test-kitchen/kitchen-docker/commit/00115588236900d9ef3275a73892f9d3bdb4e3c8))
+
 ## [3.3.4](https://github.com/test-kitchen/kitchen-docker/compare/v3.3.3...v3.3.4) (2026-08-23)
 
 

data/README.md

@@ -28,6 +28,7 @@ machine to boot.
 * [Driver configuration](#driver-configuration)
 * [Transport configuration](#transport-configuration)
 * [Logging into a container](#logging-into-a-container)
+* [Other commands](#other-commands)
 * [Examples](#examples)
 * [Using with Chef](#using-with-chef)
 * [Troubleshooting](#troubleshooting)
@@ -204,9 +205,10 @@ platforms:
 | `dockerfile` | *(none)* | Path to your own Dockerfile, used instead of the generated one. Rendered as [ERB](#using-a-custom-dockerfile). |
 | `build_context` | `true` locally, `false` for a remote daemon | Send the working directory to the daemon as build context. Required for `ADD` and `COPY`; slow against a remote daemon. |
 | `build_options` | *(none)* | Extra flags for `docker build`, as a string or a map. |
-| `build_tempdir` | working directory | Where the generated Dockerfile is written, relative to `build_context`. |
+| `build_tempdir` | working directory | Directory the generated Dockerfile is written to. A relative path is resolved against the working directory, and the path must be inside the build context, since `docker build -f` is given it relative to the working directory. |
 | `use_cache` | `true` | Use Docker's build cache. `false` adds `--no-cache`. |
 | `remove_images` | `false` | Remove the built image on `kitchen destroy`. |
+| `package_name` | the instance name, tagged `latest` | Image `kitchen package` commits the container to. |
 | `docker_platform` | *(none)* | Target architecture, passed as `--platform` to both build and run — e.g. `linux/arm64`. |
 
 ### Provisioning the image
@@ -235,7 +237,9 @@ platforms:
 | `tty` | `false` | Pass `-t`, allocating a pseudo-TTY. |
 | `env_variables` | *(none)* | Environment variables set in the container, as a map. |
 | `wait_for_transport` | `true` | Wait for the transport to answer before converging. Set `false` for containers that do not stay up. |
-| `detach` | `false` | Run provisioner commands with `docker exec -d`, returning immediately instead of waiting for them. The container itself is always started detached, regardless of this setting, and `kitchen login` ignores it so the shell stays usable. |
+
+The container itself is always started detached — see [`detach`](#transport-configuration)
+under the transport for how provisioner commands are run.
 
 ### Networking
 
@@ -284,6 +288,7 @@ Each of these accepts a single value or a list.
 | `binary` | `docker` | Docker CLI to invoke — e.g. `docker.io`, or an absolute path. |
 | `socket` | `$DOCKER_HOST`, else `unix:///var/run/docker.sock` (`npipe:////./pipe/docker_engine` on Windows) | Daemon to talk to. A `tcp://` value also supplies the host used for SSH to the container. |
 | `use_sudo` | `false` | Run every `docker` command through `sudo`. |
+| `sudo_command` | `sudo -E` | The command `use_sudo` prefixes, for hosts that use something else (`doas`, say). |
 | `tls` | `false` | Use TLS when connecting. |
 | `tls_verify` | `false` | Verify the daemon's certificate. |
 | `tls_cacert` | *(none)* | Path to the CA certificate. |
@@ -311,14 +316,17 @@ These options go under `transport:`, not `driver:`.
 | `working_dir` | *(none)* | Working directory inside the container (`-w`). |
 | `temp_dir` | `/tmp`, or `$env:TEMP` on Windows | Directory used to stage uploaded files. |
 | `env_variables` | *(none)* | Environment variables for each command. |
+| `detach` | `false` | Run provisioner commands with `docker exec -d`, returning immediately instead of waiting for them to finish. `kitchen login` ignores it, so the shell stays usable. |
 | `privileged` | `false` | Run commands with `--privileged`. |
 | `interactive` | `false` | Pass `-i`. |
 | `tty` | `false` | Pass `-t`. |
+| `use_sudo` | `false` | Run every `docker` command through `sudo`. |
+| `sudo_command` | `sudo -E` | The command `use_sudo` prefixes. |
 | `tls`, `tls_verify`, `tls_cacert`, `tls_cert`, `tls_key` | as for the driver | TLS settings for the daemon connection. |
 
 The driver and transport each read their own copy of `binary`, `socket`,
-`username`, and the TLS settings. If you point one at a non-default daemon,
-point the other at it too.
+`username`, `use_sudo`, and the TLS settings. If you point one at a non-default
+daemon, or need `sudo` to reach it, configure the other the same way.
 
 ## Logging into a container
 
@@ -334,6 +342,68 @@ starts `powershell`. The transport's `username`, `working_dir`,
 `env_variables`, and `privileged` settings are honoured, so the shell matches
 the environment the provisioner ran in.
 
+## Other commands
+
+### `kitchen package`
+
+Commits the container to a Docker image, so a converged instance can be kept
+and reused:
+
+```sh
+kitchen package default-ubuntu-2404
+```
+
+```text
+-----> Packaging remote instance
+       [Docker] Packaged default-ubuntu-2404 as default-ubuntu-2404:latest (sha256:1f51c590...)
+```
+
+The image is named after the instance. Set `package_name` for something else:
+
+```yaml
+driver:
+  name: docker
+  package_name: myapp/under-test:candidate
+```
+
+Run `docker save` against the result if you want a tarball.
+
+### `kitchen doctor`
+
+Checks that the daemon is reachable and that the configuration points at
+things that exist:
+
+```sh
+kitchen doctor default-ubuntu-2404
+```
+
+```text
+-----> The doctor is in
+       Docker daemon at unix:///var/run/docker.sock is reachable, running 29.7.2.
+```
+
+It reports every problem it finds rather than stopping at the first, and exits
+non-zero when there is one: a daemon it cannot reach, a `tls_cacert`,
+`tls_cert`, `tls_key`, or `dockerfile` naming a path that is not there, or a
+state file naming a container the daemon no longer has.
+
+### `kitchen list --live`
+
+Asks Docker what state each container is actually in, rather than reporting
+only the last action Test Kitchen took:
+
+```sh
+kitchen list --live
+```
+
+```text
+Instance             Driver  Provisioner  Verifier  Transport  Last Action  Last Error  Live Status
+default-ubuntu-2404  Docker  Shell        Dummy     Docker     Created      <None>      running
+```
+
+`running`, `stopped`, `gone` (the state file names a container the daemon does
+not have), or `not created`.
+
 ## Examples
 
 ### Testing a systemd service
@@ -534,7 +604,8 @@ bootstrap. Set it to a supported family, or supply your own
 to `false` against a remote daemon.
 
 **Permission denied talking to the daemon.** Either add your user to the
-`docker` group, or set `use_sudo: true`.
+`docker` group, or set `use_sudo: true` under **both** `driver:` and
+`transport:` -- the transport runs its own `docker exec` and `docker cp`.
 
 **Anything else.** Run with `-l debug`:
 

data/kitchen-docker.gemspec

@@ -16,5 +16,5 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files`.split($/)
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "test-kitchen", ">= 1.0.0", "< 5.0"
+  spec.add_dependency "test-kitchen", ">= 3.0", "< 5.0"
 end

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

@@ -84,7 +84,10 @@ module Kitchen
           debug("Executing temp script #{remote_path}/#{filename} on container")
           remote_path = replace_env_variables(@config, remote_path)
 
-          container_exec(@config, "/bin/bash #{remote_path}/#{filename}")
+          # Escaped because the exec command line is assembled as one string:
+          # a temp_dir with a space in it was split before docker saw it, and
+          # bash was handed the first half of the directory as the script.
+          container_exec(@config, "/bin/bash #{Shellwords.escape("#{remote_path}/#{filename}")}")
         rescue => e
           raise "Failed to execute command on Linux container. #{e}"
         ensure

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

@@ -69,7 +69,11 @@ module Kitchen
           # Replace any environment variables used in the path and execute script file
           debug("Executing temp script #{remote_path}\\#{filename} on container")
           remote_path = replace_env_variables(@config, remote_path)
-          cmd = build_powershell_command("-File #{remote_path}\\#{filename}")
+          # Quoted because PowerShell's -File takes exactly one argument. An
+          # unquoted path with a space in it -- which $env:TEMP has whenever the
+          # user's name does -- left PowerShell looking for a script named
+          # after the first word of the directory.
+          cmd = build_powershell_command(%{-File "#{remote_path}\\#{filename}"})
 
           container_exec(@config, cmd)
         rescue => e

data/lib/kitchen/docker/docker_version.rb

@@ -18,6 +18,6 @@ module Kitchen
   # Everything belonging to the kitchen-docker plugin.
   module Docker
     # The version of the kitchen-docker gem.
-    DOCKER_VERSION = "3.3.4".freeze
+    DOCKER_VERSION = "3.4.1".freeze
   end
 end

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

@@ -64,11 +64,39 @@ module Kitchen
           docker << " --tlscacert=#{shell_escape(config[:tls_cacert])}" if config[:tls_cacert]
           docker << " --tlscert=#{shell_escape(config[:tls_cert])}" if config[:tls_cert]
           docker << " --tlskey=#{shell_escape(config[:tls_key])}" if config[:tls_key]
+          options = docker_sudo_opts(options)
           logger.debug("docker_command: #{docker} #{cmd} shell_opts: #{docker_shell_opts(options)}")
           run_command("#{docker} #{cmd}", docker_shell_opts(options))
         end
         # rubocop:enable Metrics/AbcSize
 
+        # Adds the sudo options {#run_command} reads, when +use_sudo+ is set.
+        #
+        # Sudo is a property of the call rather than of the configuration as far
+        # as the shell-out layer is concerned: it reads +:use_sudo+ from the
+        # options hash it is handed and knows nothing about +config+. So a
+        # docker command only runs through sudo if these are passed to it.
+        #
+        # Without this, +use_sudo+ reached exactly one command -- the
+        # `docker` probe in +verify_dependencies+ -- and every build, run,
+        # exec, cp, and rm still ran as the invoking user. On a host where the
+        # daemon socket needs root, that made the documented answer to
+        # "permission denied while trying to connect to the Docker daemon
+        # socket" do nothing at all.
+        #
+        # A copy is returned rather than the hash being edited in place, so a
+        # caller that reuses its options hash does not accumulate sudo.
+        #
+        # @param options [Hash] shell-out options
+        # @return [Hash] those options, with sudo added when configured
+        def docker_sudo_opts(options = {})
+          return options unless config[:use_sudo]
+
+          options = options.merge(use_sudo: true)
+          options[:sudo_command] = config[:sudo_command] if config[:sudo_command]
+          options
+        end
+
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
 
         # Runs a shell command, returning stderr as well as stdout.
@@ -79,7 +107,7 @@ module Kitchen
         # @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
+        # @raise [Kitchen::ShellOut::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}"

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

@@ -33,6 +33,11 @@ module Kitchen
         include Configurable
         include Kitchen::Docker::Helpers::CliHelper
 
+        # Printed by the probe in {#file_on_container?} when the file is there.
+        # A marker is echoed rather than the exit status being read, because a
+        # non-zero exit from `docker exec` is raised rather than returned.
+        COPIED_MARKER = "kitchen_docker_copied".freeze
+
         # Pulls the container id out of `docker run` output.
         #
         # Docker prints ids in short (12) or full (64) hex form, on a line of
@@ -150,6 +155,17 @@ module Kitchen
 
         # Creates a directory inside the container, on Linux or Windows.
         #
+        # The path is escaped for the shell, because it comes from the
+        # transport's +temp_dir+ and a `docker exec` command line is assembled
+        # as one string. A directory with a space in it was torn in two before
+        # docker ever saw it, and `mkdir -p` obligingly created both halves --
+        # neither of them the directory that was asked for. Every upload that
+        # followed then went to a path that did not exist.
+        #
+        # The PowerShell branch already quotes the path itself, and its
+        # argument is reassembled by PowerShell rather than split by a shell,
+        # so it is left as it is.
+        #
         # @param state [Hash] instance state naming the container
         # @param path [String] the directory to create; environment variable
         #   references are expanded first
@@ -157,7 +173,7 @@ module Kitchen
         # @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}"
+          cmd = "mkdir -p #{Shellwords.escape(path)}"
 
           if state[:platform].include?("windows")
             psh = "-Command if(-not (Test-Path '#{path}')) { New-Item -Path '#{path}' -Force }"
@@ -172,23 +188,84 @@ module Kitchen
 
         # Copies a local file into the container.
         #
+        # The copy is checked afterwards, because `docker cp` cannot write into
+        # a mount and does not say so. A destination under a tmpfs or a volume
+        # is written to the container's own filesystem layer, which the mount
+        # then hides, and docker exits 0 with no output -- so the copy looks
+        # like it worked and the file is simply not there.
+        #
+        # Left unchecked, that surfaces later and somewhere else. Running with
+        # `tmpfs: /tmp`, which is how the Docker documentation suggests running
+        # systemd, the first sign is the next command failing with
+        # `/bin/bash: /tmp/docker-<uuid>.sh: No such file or directory` (#387),
+        # which names neither the copy nor the mount.
+        #
         # @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
+        # @raise [RuntimeError] if the copy fails, or if it silently wrote
+        #   nothing
         def copy_file_to_container(state, local_file, remote_file)
           debug("Copying local file #{local_file} to #{remote_file} on container")
 
           remote_file = replace_env_variables(state, remote_file)
 
-          remote_file = "#{state[:container_id]}:#{remote_file}"
-          cmd = build_copy_command(local_file, remote_file)
-          docker_command(cmd)
+          cmd = build_copy_command(local_file, "#{state[:container_id]}:#{remote_file}")
+          output = docker_command(cmd)
+          verify_file_copied(state, local_file, remote_file)
+          output
         rescue => e
           raise "Failed to copy file #{local_file} to container. #{e}"
         end
 
+        # Checks that a copied file arrived, and says why if it did not.
+        #
+        # Only Linux containers are checked. tmpfs mounts are a Linux container
+        # feature, and `docker cp` against a Windows container is a different
+        # code path in Docker that this cannot be tried against, so those keep
+        # the behaviour they have always had.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param local_file [String] the source that was copied
+        # @param remote_file [String] the destination it was copied to
+        # @return [void]
+        # @raise [Kitchen::ActionFailed] if the file is not there
+        def verify_file_copied(state, local_file, remote_file)
+          return if state[:platform].to_s.include?("windows")
+          return if file_on_container?(state, remote_file, ::File.basename(local_file))
+
+          raise ActionFailed,
+            "docker reported no error copying it to #{remote_file}, but the file is " \
+            "not there. `docker cp` cannot write into a mount -- if #{remote_file} is " \
+            "a tmpfs or a volume, set the transport's temp_dir and the provisioner's " \
+            "root_path to a path that is not."
+        end
+
+        # Whether a `docker cp` destination now holds the file that was copied.
+        #
+        # `docker cp SRC CONTAINER:DEST` copies into DEST when DEST is a
+        # directory and to DEST otherwise. Which of those happened is only known
+        # inside the container, so the choice is made there, in the one command,
+        # rather than by asking twice from here.
+        #
+        # The two paths are passed as arguments to `sh` rather than interpolated
+        # into the script, so that nothing in either is read as shell syntax.
+        #
+        # @param state [Hash] instance state naming the container
+        # @param remote_file [String] the destination that was copied to
+        # @param basename [String] the source's file name
+        # @return [Boolean] whether the file is there
+        def file_on_container?(state, remote_file, basename)
+          script = 'p="$1"; if [ -d "$p" ]; then p="$p/$2"; fi; ' \
+                   "if [ -e \"$p\" ]; then echo #{COPIED_MARKER}; fi"
+          probe = "/bin/sh -c #{Shellwords.escape(script)} sh " \
+                  "#{Shellwords.escape(remote_file)} #{Shellwords.escape(basename)}"
+
+          output = docker_command(build_exec_command(state, probe), suppress_output: !logger.debug?)
+          output.include?(COPIED_MARKER)
+        end
+
         # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
 
         # Reads the container's environment.

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

@@ -27,6 +27,9 @@ module Kitchen
         include Kitchen::Docker::Helpers::CliHelper
         include Kitchen::Docker::Helpers::ContainerHelper
 
+        # An id on a line of its own, which is all `docker build -q` prints.
+        QUIET_BUILD_IMAGE_ID = /\A(sha256:[[:xdigit:]]{64})\z/
+
         # Pulls the built image's id out of `docker build` output.
         #
         # Scanned in reverse, and against several patterns, because the wording has
@@ -37,6 +40,13 @@ module Kitchen
         # @raise [Kitchen::ActionFailed] if no id could be found
         def parse_image_id(output)
           output.split("\n").reverse_each do |line|
+            line = line.strip
+            # `docker build -q` prints the id and nothing else -- none of the
+            # wording below appears -- so a build with `build_options: -q` had
+            # no line any of these matched and failed with "Could not parse
+            # Docker build output for image ID" (#225).
+            return Regexp.last_match(1) if line.match(QUIET_BUILD_IMAGE_ID)
+
             if line =~ /writing image (sha256:[[:xdigit:]]{64})(?: \d*\.\ds)? done/i
               img_id = line[/writing image (sha256:[[:xdigit:]]{64})(?: \d*\.\ds)? done/i, 1]
               return img_id
@@ -126,10 +136,28 @@ module Kitchen
           parse_image_id(output)
         end
 
+        # Whether the image named in state is present locally.
+        #
+        # The inspect is silenced, as every other predicate that shells out to
+        # docker is. Left speaking, `kitchen destroy` on an instance with
+        # +remove_images+ set printed the image's entire `docker inspect` JSON
+        # -- config, every layer digest, metadata -- into the middle of the
+        # destroy output, between the container being removed and the image
+        # being removed. Nothing read it: only whether the command succeeded is
+        # used.
+        #
+        # It is still printed under `-l debug`, where the rest of the driver's
+        # docker traffic is.
+        #
         # @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
+          return false unless state[:image_id]
+
+          !!docker_command("inspect --type=image #{state[:image_id]}",
+            suppress_output: !logger.debug?)
+        rescue
+          false
         end
       end
     end

data/lib/kitchen/driver/docker.rb

@@ -17,11 +17,13 @@ require "kitchen"
 require "json" unless defined?(JSON)
 require "securerandom" unless defined?(SecureRandom)
 require "net/ssh" unless defined?(Net::SSH)
+require "time" unless defined?(Time)
 
 require "kitchen/driver/base"
 
 require_relative "../docker/container/linux"
 require_relative "../docker/container/windows"
+require_relative "../docker/docker_version"
 require_relative "../docker/helpers/cli_helper"
 require_relative "../docker/helpers/container_helper"
 
@@ -36,6 +38,13 @@ module Kitchen
       include Kitchen::Docker::Helpers::ContainerHelper
       include ShellOut
 
+      # Reported by `kitchen diagnose`, which is what a bug report is asked to
+      # include. The version is this gem's own: the transport used to report
+      # Kitchen::VERSION, which is Test Kitchen's, so a diagnose said the
+      # plugin was at whatever version Test Kitchen happened to be.
+      kitchen_driver_api_version 2
+      plugin_version Kitchen::Docker::DOCKER_VERSION
+
       default_config :binary,        "docker"
       default_config :build_options, nil
       default_config :build_tempdir, Dir.pwd
@@ -52,6 +61,7 @@ module Kitchen
       default_config :remove_images, false
       default_config :run_options,   nil
       default_config :security_opt,  nil
+      default_config :sudo_command,  nil
       default_config :tls,           false
       default_config :tls_cacert,    nil
       default_config :tls_cert,      nil
@@ -79,6 +89,13 @@ module Kitchen
         ].join("-").downcase
       end
 
+      # The image `kitchen package` commits to. Derived from the instance name,
+      # which is already lowercase and dash-separated, so it is a valid Docker
+      # repository name as it stands.
+      default_config :package_name do |driver|
+        "#{driver.instance.name.downcase.gsub(/[^a-z0-9_.-]/, "-")}:latest"
+      end
+
       default_config :platform, &:default_platform
 
       default_config :run_command do |driver|
@@ -140,6 +157,82 @@ module Kitchen
         container.destroy(state)
       end
 
+      # Commits the container to a Docker image.
+      #
+      # `kitchen package` asks a driver to turn a converged instance into
+      # something reusable. For Docker that is an image: `docker commit` on the
+      # running container, which is the artifact every other docker tool
+      # already takes. Run `docker save` against the result for a tarball.
+      #
+      # @param state [Hash] instance state naming the container
+      # @return [void]
+      # @raise [Kitchen::ActionFailed] if the instance has not been created
+      def package(state)
+        unless state[:container_id]
+          raise ActionFailed, "Cannot package #{instance.name}: it has not been created."
+        end
+
+        # Asked here rather than left to `docker commit`, which reports a
+        # container that is gone as a bare "Error response from daemon: No such
+        # container: <64 hex characters>" with nothing about the instance or
+        # what to do next.
+        unless container_exists?(state)
+          raise ActionFailed, "Cannot package #{instance.name}: the state file names container " \
+                              "#{state[:container_id]}, which the daemon does not have. " \
+                              "Run `kitchen destroy` to clear it."
+        end
+
+        name = config[:package_name]
+        info("[Docker] Committing container #{state[:container_id]} to #{name}")
+        output = docker_command("commit #{shell_escape(state[:container_id])} #{shell_escape(name)}",
+          suppress_output: !logger.debug?)
+        image_id = output.lines.map(&:strip).find { |line| line.match?(/\Asha256:[[:xdigit:]]{64}\z/) }
+        info("[Docker] Packaged #{instance.name} as #{name}#{" (#{image_id})" if image_id}")
+      end
+
+      # Checks the configuration and the daemon it points at.
+      #
+      # Run by `kitchen doctor`. A true return is how Test Kitchen decides to
+      # exit non-zero, so every check runs and the results are OR-ed together
+      # rather than returning at the first problem -- somebody running `doctor`
+      # wants the whole list, not the first item on it.
+      #
+      # @param state [Hash] instance state
+      # @return [Boolean] whether a problem was found
+      def doctor(state)
+        [
+          doctor_daemon,
+          doctor_files,
+          doctor_container(state),
+        ].any?
+      end
+
+      # Reports whether the container backing this instance is up.
+      #
+      # Read by `kitchen list --live`, which showed "unknown" for every
+      # instance: {Kitchen::Driver::Base} cannot know, and this driver never
+      # said. Docker can answer directly, and these are the same two questions
+      # create and destroy already ask.
+      #
+      # @param state [Hash] instance state naming the container
+      # @return [Hash] normalized status data
+      def status(state)
+        common = { source: "driver", checked_at: Time.now.utc.iso8601, resource_id: state[:container_id] }
+
+        if !state[:container_id]
+          common.merge(live: false, state: "not created",
+            message: "No container is recorded in the state file")
+        elsif !container_exists?(state)
+          common.merge(live: false, state: "gone",
+            message: "The state file names a container the daemon does not have")
+        elsif container_running?(state)
+          common.merge(live: true, state: "running")
+        else
+          common.merge(live: false, state: "stopped",
+            message: "The container exists but is not running")
+        end
+      end
+
       # Waits for the transport to accept a connection, unless disabled.
       #
       # @param state [Hash] instance state describing how to connect
@@ -171,6 +264,44 @@ module Kitchen
 
       protected
 
+      # @return [Boolean] whether the daemon could not be reached
+      def doctor_daemon
+        version = docker_command("version --format '{{.Server.Version}}'", suppress_output: true).strip
+        info("Docker daemon at #{config[:socket]} is reachable, running #{version}.")
+        false
+      rescue => e
+        error("Cannot reach the Docker daemon at #{config[:socket]}. #{e}")
+        true
+      end
+
+      # Checks paths the configuration names.
+      #
+      # A missing TLS file or Dockerfile is worth catching here because docker
+      # reports it far from the cause -- a missing client certificate surfaces
+      # as a connection error rather than as a missing file.
+      #
+      # @return [Boolean] whether any named path is missing
+      def doctor_files
+        %i{tls_cacert tls_cert tls_key dockerfile}.map do |key|
+          path = config[key]
+          next false if path.nil? || ::File.exist?(::File.expand_path(path))
+
+          error("#{key} is set to #{path}, which does not exist.")
+          true
+        end.any?
+      end
+
+      # @param state [Hash] instance state naming the container
+      # @return [Boolean] whether state names a container that is gone
+      def doctor_container(state)
+        return false unless state[:container_id]
+        return false if container_exists?(state)
+
+        error("The state file names container #{state[:container_id]}, which the daemon does " \
+              "not have. Run `kitchen destroy` to clear it.")
+        true
+      end
+
       # The container implementation for this platform.
       #
       # @return [Kitchen::Docker::Container] a Windows or Linux container