kitchen-dokken 2.23.2 → 2.23.4

data/lib/kitchen/driver/dokken.rb

@@ -20,6 +20,7 @@ require "json" unless defined?(JSON)
 require "kitchen"
 require "tmpdir" unless defined?(Dir.mktmpdir)
 require "docker"
+require "shellwords" unless defined?(Shellwords)
 require "base64" unless defined?(Base64)
 require_relative "../helpers"
 
@@ -29,9 +30,16 @@ include Dokken::Helpers
 Excon.defaults[:ssl_verify_peer] = false
 
 module Kitchen
+  # @see Kitchen::Driver::Dokken
   module Driver
     # Dokken driver for Kitchen.
     #
+    # Creates three containers per instance: a *runner*, which the converge
+    # actually happens in; a *chef* volume container, whose /opt/chef is
+    # mounted into the runner instead of installing chef; and -- only when the
+    # docker daemon cannot read the local filesystem -- a *data* container that
+    # serves the kitchen sandbox over ssh.
+    #
     # @author Sean OMeara <sean@sean.io>
     class Dokken < Kitchen::Driver::Base
       default_config :api_retries, 20
@@ -81,9 +89,12 @@ module Kitchen
       default_config :write_timeout, 3600
       default_config :user_ns_mode, nil
       default_config :creds_file, nil
-      default_config :docker_config_creds, false
+      default_config :docker_config_creds, true
 
       # (see Base#create)
+      #
+      # @param state [Hash] mutable instance state
+      # @return [void]
       def create(state)
         # Authenticate the private registry
         authenticate!
@@ -116,6 +127,10 @@ module Kitchen
         save_misc_state state
       end
 
+      # (see Base#destroy)
+      #
+      # The chef volume container and the dokken network are deliberately left
+      # behind: both are shared by every instance using the same chef version.
       def destroy(_state)
         if remote_docker_host? || running_inside_docker?
           stop_data_container
@@ -130,6 +145,10 @@ module Kitchen
 
       private
 
+      # Attach DNS settings to a network endpoint configuration, in place.
+      #
+      # @param endpoint_config [Hash] the EndpointsConfig entry to extend
+      # @return [void]
       def add_dns_config(endpoint_config)
         return unless self[:dns] || self[:dns_search]
 
@@ -138,16 +157,30 @@ module Kitchen
         endpoint_config["DNSConfig"]["Search"] = self[:dns_search] if self[:dns_search]
       end
 
+      # A Hash that compares equal to any Hash containing all of its pairs.
+      #
+      # The daemon echoes back more volumes than we asked for, so a plain
+      # equality check against the requested set would never match.
       class PartialHash < Hash
+        # Whether `other` contains every pair this hash holds.
+        #
+        # @param other [Object] the value to compare against
+        # @return [Boolean] true when `other` is a superset hash
         def ==(other)
           other.is_a?(Hash) && all? { |key, val| other.key?(key) && other[key] == val }
         end
       end
 
+      # How many times to retry a retryable docker API call.
+      #
+      # @return [Integer] the retry count
       def api_retries
         config[:api_retries]
       end
 
+      # The docker-api connection this driver talks to.
+      #
+      # @return [::Docker::Connection] a memoised connection
       def docker_connection
         opts = ::Docker.options
         opts[:read_timeout] = config[:read_timeout]
@@ -155,6 +188,9 @@ module Kitchen
         @docker_connection ||= ::Docker::Connection.new(config[:docker_host_url], opts)
       end
 
+      # Remove this instance's work image, if nothing else still needs it.
+      #
+      # @return [void]
       def delete_work_image
         return unless ::Docker::Image.exist?(work_image, { "platform" => oci_platform(config[:platform]) }, docker_connection)
 
@@ -167,6 +203,11 @@ module Kitchen
         end
       end
 
+      # Build the per-instance image the runner container is created from.
+      #
+      # @param state [Hash] mutable instance state
+      # @return [void]
+      # @raise [RuntimeError] if the daemon rejects the build
       def build_work_image(state)
         info("Building work image..")
         return if ::Docker::Image.exist?(work_image, { "platform" => oci_platform(config[:platform]) }, docker_connection)
@@ -183,7 +224,7 @@ module Kitchen
         # credit to https://github.com/someara/kitchen-dokken/issues/95#issue-224697526
         rescue Docker::Error::UnexpectedResponseError => e
           msg = "work_image build failed: "
-          msg += JSON.parse(e.to_s.split("\r\n").last)["error"].to_s
+          msg += build_error_detail(e)
           msg += ". The common scenarios are incorrect intermediate "
           msg += "instructions such as not including `-y` on an `apt-get` "
           msg += "or similar. The other common scenario is a transient "
@@ -197,6 +238,24 @@ module Kitchen
         state[:work_image] = work_image
       end
 
+      # Pull the human-readable reason out of a failed build response.
+      #
+      # The daemon usually answers with a JSON document carrying an "error"
+      # key, but a proxy or a plain-text 500 does not -- and a JSON::ParserError
+      # raised from inside the rescue clause would bury the real failure.
+      #
+      # @param error [Exception] the error docker-api raised
+      # @return [String] the daemon's explanation, or the raw response
+      def build_error_detail(error)
+        last_line = error.to_s.split("\r\n").last.to_s
+        JSON.parse(last_line)["error"].to_s
+      rescue JSON::ParserError, TypeError
+        last_line
+      end
+
+      # The Dockerfile for the work image.
+      #
+      # @return [String] the Dockerfile contents
       def work_image_dockerfile
         from = registry_image_path(platform_image)
         debug("driver - Building work image from #{from}")
@@ -210,6 +269,10 @@ module Kitchen
         dockerfile_contents.join("\n")
       end
 
+      # Record the values the transport, provisioner and verifier read later.
+      #
+      # @param state [Hash] mutable instance state
+      # @return [void]
       def save_misc_state(state)
         state[:platform_image] = platform_image
         state[:instance_name] = instance_name
@@ -217,47 +280,81 @@ module Kitchen
         state[:image_prefix] = image_prefix
       end
 
+      # Delete the shared chef volume container.
+      #
+      # Not called during {#destroy}; it exists for callers that really do want
+      # to reclaim the shared container.
+      #
+      # @return [void]
       def delete_chef_container
         debug "driver - deleting container #{chef_container_name}"
         delete_container chef_container_name
       end
 
+      # Delete this instance's data container.
+      #
+      # @return [void]
       def delete_data_container
         debug "driver - deleting container #{data_container_name}"
         delete_container data_container_name
       end
 
+      # Delete this instance's runner container.
+      #
+      # @return [void]
       def delete_runner_container
         debug "driver - deleting container #{runner_container_name}"
         delete_container runner_container_name
       end
 
+      # The configured image name prefix, if any.
+      #
+      # @return [String, nil] the prefix
       def image_prefix
         config[:image_prefix]
       end
 
+      # The kitchen platform name, e.g. `almalinux-9`.
+      #
+      # @return [String] the platform name
       def instance_platform_name
         instance.platform.name
       end
 
+      # Stop this instance's runner container.
+      #
+      # @return [void]
       def stop_runner_container
         debug "driver - stopping container #{runner_container_name}"
         stop_container runner_container_name
       end
 
+      # Stop this instance's data container.
+      #
+      # @return [void]
       def stop_data_container
         debug "driver - stopping container #{data_container_name}"
         stop_container data_container_name
       end
 
+      # The name of the per-instance image the runner is created from.
+      #
+      # @return [String] a lowercase image name
       def work_image
         [image_prefix, instance_name].compact.join("/").downcase
       end
 
+      # The `Tmpfs` value for the runner container.
+      #
+      # @return [Hash, nil] a Docker API Tmpfs hash
       def dokken_tmpfs
         coerce_tmpfs(config[:tmpfs])
       end
 
+      # Normalise a `tmpfs:` setting into a Docker API Tmpfs hash.
+      #
+      # @param v [Hash, Array<String>, nil] the configured tmpfs mounts
+      # @return [Hash, nil] a Tmpfs hash, or nil to omit the key
       def coerce_tmpfs(v)
         case v
         when Hash, nil
@@ -270,6 +367,9 @@ module Kitchen
         end
       end
 
+      # The containers whose volumes the runner mounts.
+      #
+      # @return [Array<String>] container names
       def dokken_volumes_from
         ret = []
         ret << chef_container_name
@@ -277,6 +377,14 @@ module Kitchen
         ret
       end
 
+      # Split a `volumes:` setting into anonymous volumes and bind mounts.
+      #
+      # Entries containing a colon are bind mounts and are moved into `binds`;
+      # what is left becomes the `Volumes` hash. `binds` is mutated in place.
+      #
+      # @param v [Hash, Array<String>, nil] the configured volumes
+      # @param binds [Array] the bind list to append to
+      # @return [Hash, nil] a Volumes hash, or nil to omit the key
       def coerce_volumes(v, binds)
         case v
         when PartialHash, nil
@@ -297,8 +405,17 @@ module Kitchen
         end
       end
 
+      # Work out the runner container's `Volumes` and `Binds` values.
+      #
+      # The sandboxes are only bind-mounted when the daemon can read the host
+      # filesystem; otherwise the transport ships them into the data container.
+      #
+      # @return [Array(Hash, Array<String>)] the volumes and binds
       def calc_volumes_binds
-        volumes = Array.new(Array(config[:volumes]))
+        # Array() on a Hash yields its pairs, which would destroy an explicit
+        # `volumes:` mapping before coerce_volumes ever sees it.
+        configured_volumes = config[:volumes]
+        volumes = configured_volumes.is_a?(Hash) ? configured_volumes : Array.new(Array(configured_volumes))
         binds = Array.new(Array(config[:binds]))
 
         # Binds is mutated in-place, volumes *may* be.
@@ -312,6 +429,10 @@ module Kitchen
         [volumes, binds_ret.flatten]
       end
 
+      # Create and start the container the converge actually runs in.
+      #
+      # @param state [Hash] mutable instance state
+      # @return [void]
       def start_runner_container(state)
         debug "driver - starting #{runner_container_name}"
 
@@ -375,6 +496,10 @@ module Kitchen
         state[:runner_container] = runner_container.json
       end
 
+      # Create and start the container that serves the sandboxes over ssh.
+      #
+      # @param state [Hash] mutable instance state
+      # @return [void]
       def start_data_container(state)
         debug "driver - creating #{data_container_name}"
         config = {
@@ -408,6 +533,12 @@ module Kitchen
         state[:data_container] = data_container.json
       end
 
+      # Create the shared `dokken` network, unless it already exists.
+      #
+      # Several instances converge in parallel and all race to create the one
+      # shared network, so this is both file-locked and forgiving of a lost race.
+      #
+      # @return [void]
       def make_dokken_network
         return unless self[:network_mode] == "dokken"
 
@@ -416,17 +547,28 @@ module Kitchen
         rescue ::Docker::Error::NotFoundError
           begin
             with_retries { ::Docker::Network.create("dokken", network_settings) }
-          rescue ::Docker::Error => e
+          rescue ::Docker::Error::DockerError => e
             debug "driver - error :#{e}:"
           end
         end
       end
 
+      # Build the data image, unless it is already present.
+      #
+      # @return [void]
       def make_data_image
         debug "driver - calling create_data_image"
         create_data_image(config[:docker_registry])
       end
 
+      # Create the volume container /opt/chef is mounted into the runner from.
+      #
+      # The container is shared by every instance on the same chef version and
+      # platform, so creation is guarded by a file lock.
+      #
+      # @param state [Hash] mutable instance state
+      # @return [void]
+      # @raise [RuntimeError] if the container could not be created
       def create_chef_container(state)
         with_file_lock("#{home_dir}/.dokken-#{chef_container_name}.lock") do
           with_retries do
@@ -454,12 +596,20 @@ module Kitchen
             # has to be built for the same architecture as the runner.
             chef_container = create_container(config, platform: self[:platform])
             state[:chef_container] = chef_container.json
-          rescue ::Docker::Error, StandardError => e
+          # Both constants have to be spelled out: bare `StandardError` inside
+          # module Kitchen resolves to Kitchen::StandardError, and Docker::Error
+          # is a namespace module that no exception class includes.
+          rescue ::Docker::Error::DockerError, ::StandardError => e
             raise "driver - #{chef_container_name} failed to create #{e}"
           end
         end
       end
 
+      # Run a block holding an exclusive lock on a file.
+      #
+      # @param path [String] the lock file to create and hold
+      # @yield with the lock held
+      # @return [void]
       def with_file_lock(path)
         File.open(path, File::RDWR | File::CREAT, 0o644) do |f|
           f.flock(File::LOCK_EX)
@@ -467,6 +617,9 @@ module Kitchen
         end
       end
 
+      # Log the docker client in, when a creds_file has been configured.
+      #
+      # @return [void]
       def authenticate!
         # No need to authenticate if the credentials are empty
         return if docker_creds.empty?
@@ -474,6 +627,9 @@ module Kitchen
         ::Docker.authenticate! docker_creds
       end
 
+      # The credentials read from the configured creds_file.
+      #
+      # @return [Hash] the credentials, or an empty hash
       def docker_creds
         @docker_creds ||= if config[:creds_file]
                             JSON.parse(IO.read(config[:creds_file]))
@@ -482,6 +638,12 @@ module Kitchen
                           end
       end
 
+      # The credentials found in ~/.docker/config.json, keyed by registry.
+      #
+      # `auths` entries resolve to a credentials hash; `credHelpers` entries
+      # resolve to a proc that shells out to the helper only if it is needed.
+      #
+      # @return [Hash{String => Hash, Proc}] credentials by registry key
       def docker_config_creds
         return @docker_config_creds if @docker_config_creds
 
@@ -493,7 +655,8 @@ module Kitchen
             config["auths"].each do |k, v|
               next if v["auth"].nil?
 
-              username, password = Base64.decode64(v["auth"]).split(":")
+              # Split once: a colon is legal inside a registry password.
+              username, password = Base64.decode64(v["auth"]).split(":", 2)
               @docker_config_creds[k] = { serveraddress: k, username:, password: }
             end
           end
@@ -513,55 +676,129 @@ module Kitchen
         @docker_config_creds
       end
 
+      # The `auths` key `docker login` itself writes for Docker Hub.
+      DOCKER_HUB_REGISTRY_KEY = "https://index.docker.io/v1/".freeze
+
+      # Registry hosts that all refer to Docker Hub. Docker writes the legacy
+      # v1 URL above, but hand-written and tool-generated configs use any of
+      # these. Listed in preference order.
+      DOCKER_HUB_HOSTS = %w{index.docker.io docker.io registry-1.docker.io}.freeze
+
+      # An explicit "no credentials" value. Returning nil here instead would let
+      # docker-api fall back to the process-global ::Docker.creds, which
+      # authenticate! populates from creds_file and never clears -- so another
+      # instance's private registry password would be sent to this registry,
+      # which is the very leak this scoping exists to prevent.
+      NO_DOCKER_CREDS = {}.freeze
+
+      # Return the registry host an image reference points at, or nil when the
+      # reference resolves to Docker Hub. The leading path component only names
+      # a registry when it contains a "." or a ":", or is exactly "localhost" --
+      # the same heuristic Docker uses to tell "quay.io/org/image" apart from
+      # the Hub shorthand "dokken/almalinux-8".
+      #
+      # @param image [String] an image reference
+      # @return [String, nil] the registry host, or nil for Docker Hub
+      def image_registry_host(image)
+        first, remainder = image.split("/", 2)
+        return nil if remainder.nil?
+        return nil unless first.include?(".") || first.include?(":") || first == "localhost"
+
+        first
+      end
+
+      # Look up the ~/.docker/config.json entry that applies to an image's
+      # registry. Returns nil when that registry has no entry so the pull is
+      # attempted anonymously, rather than offering it another registry's
+      # credentials.
+      # Pick the config.json key that holds the Docker Hub credentials. A
+      # config may spell Hub several ways, so prefer the canonical key and then
+      # a fixed alias order rather than whichever happens to be listed first.
+      # @return [String, nil] the config.json key holding Docker Hub credentials
+      def docker_hub_creds_key
+        keys = docker_config_creds.keys.select { |k| DOCKER_HUB_HOSTS.include?(parse_registry_host(k)) }
+        return if keys.empty?
+
+        keys.find { |k| k == DOCKER_HUB_REGISTRY_KEY } ||
+          keys.min_by { |k| DOCKER_HUB_HOSTS.index(parse_registry_host(k)) }
+      end
+
+      # The ~/.docker/config.json credentials that apply to an image.
+      #
+      # @param image [String] an image reference
+      # @return [Hash, nil] the credentials, or nil when none apply
+      def docker_config_creds_for_image(image)
+        host = image_registry_host(image)
+
+        key = if host.nil? || DOCKER_HUB_HOSTS.include?(host)
+                docker_hub_creds_key
+              else
+                docker_config_creds.keys.find { |k| parse_registry_host(k) == host }
+              end
+        return if key.nil?
+
+        c = docker_config_creds[key]
+        c.respond_to?(:call) ? c.call : c
+      end
+
+      # The credentials to send when pulling an image.
+      #
+      # @param image [String] an image reference
+      # @return [Hash] credentials, or {NO_DOCKER_CREDS} to pull anonymously
       def docker_creds_for_image(image)
         return docker_creds if config[:creds_file]
+        return NO_DOCKER_CREDS unless config[:docker_config_creds]
 
-        image_registry = image.split("/").first
-
-        # NOTE: Try to use DockerHub auth if exact registry match isn't found
-        default_registry = "https://index.docker.io/v1/"
-        if docker_config_creds.key?(image_registry)
-          c = docker_config_creds[image_registry]
-          c.respond_to?(:call) ? c.call : c
-        elsif docker_config_creds.key?(default_registry)
-          c = docker_config_creds[default_registry]
-          c.respond_to?(:call) ? c.call : c
-        end
+        docker_config_creds_for_image(image) || NO_DOCKER_CREDS
       end
 
+      # Pull the platform image the work image is built from.
+      #
+      # @return [void]
       def pull_platform_image
         debug "driver - pulling #{short_image_path(platform_image)}"
         config[:pull_platform_image] ? pull_image(platform_image) : pull_if_missing(platform_image)
       end
 
+      # Pull the chef/cinc image the volume container is built from.
+      #
+      # @return [void]
       def pull_chef_image
         debug "driver - pulling #{short_image_path(chef_image)}"
         config[:pull_chef_image] ? pull_image(chef_image) : pull_if_missing(chef_image)
       end
 
+      # Force-remove an image.
+      #
+      # @param name [String] an image reference
+      # @return [void]
       def delete_image(name)
         with_retries { @image = ::Docker::Image.get(name, { "platform" => oci_platform(config[:platform]) }, docker_connection) }
         with_retries { @image.remove(force: true) }
-      rescue ::Docker::Error
+      rescue ::Docker::Error::DockerError
         puts "Image #{name} not found. Nothing to delete."
       end
 
+      # Whether the daemon knows about a container.
+      #
+      # @param name [String] the container name
+      # @return [Boolean] true when the container exists
       def container_exist?(name)
         true if ::Docker::Container.get(name, {}, docker_connection)
-      rescue StandardError, ::Docker::Error::NotFoundError
+      rescue ::StandardError
         false
       end
 
+      # Split an image reference into its repo and tag.
+      #
+      # @param image [String] the docker image path to parse
+      # @return [Array(String, String)] the repo and tag
       def parse_image_name(image)
-        parts = image.split(":")
+        repo, separator, tag = image.rpartition(":")
 
-        if parts.size > 2
-          tag = parts.pop
-          repo = parts.join(":")
-        else
-          tag = parts[1] || "latest"
-          repo = parts[0]
-        end
+        # A colon before a slash delimits a registry port, not a tag:
+        # "localhost:5000/almalinux" is an untagged image on a local registry.
+        return [image, "latest"] if separator.empty? || tag.include?("/")
 
         [repo, tag]
       end
@@ -605,27 +842,45 @@ module Kitchen
         end
       end
 
+      # Fetch a container by name, creating it if it does not exist.
+      #
+      # @param args [Hash] the `/containers/create` body
+      # @param platform [String, nil] an OCI platform to pin the container to
+      # @return [::Docker::Container] the container
+      # @raise [RuntimeError] if the container could not be created
       def create_container(args, platform: nil)
         with_retries { @container = ::Docker::Container.get(args["name"], {}, docker_connection) }
       rescue
         with_retries do
-          args["Env"] = [] if args["Env"].nil?
-          args["Env"] << "TEST_KITCHEN=1"
-          args["Env"] << "CI=#{ENV["CI"]}" if ENV.include? "CI"
+          # Merge rather than append: start_runner_container passes config[:env]
+          # straight through, so mutating args["Env"] would edit the driver's
+          # own configuration -- and stamp it again on every retry.
+          create_args = args.merge("Env" => Array(args["Env"]) + container_env)
           info "Creating container #{args["name"]}"
-          debug "driver - create_container args #{args}"
+          debug "driver - create_container args #{create_args}"
           with_retries do
-            @container = create_container_for_platform(args.clone, platform)
+            @container = create_container_for_platform(create_args, platform)
           rescue ::Docker::Error::ConflictError
             debug "driver - rescue ConflictError: #{args["name"]}"
             with_retries { @container = ::Docker::Container.get(args["name"], {}, docker_connection) }
           end
-        rescue ::Docker::Error => e
+        rescue ::Docker::Error::DockerError => e
           debug "driver - error :#{e}:"
           raise "driver - failed to create_container #{args["name"]}"
         end
       end
 
+      # Environment variables kitchen-dokken stamps onto every container it
+      # creates, so that recipes and tests can tell they are running under
+      # Test Kitchen.
+      #
+      # @return [Array<String>] `KEY=value` strings
+      def container_env
+        env = ["TEST_KITCHEN=1"]
+        env << "CI=#{ENV["CI"]}" if ENV.include? "CI"
+        env
+      end
+
       # Create a container, optionally pinned to an OCI platform.
       #
       # /containers/create takes `platform` as a *query* parameter, but
@@ -634,6 +889,10 @@ module Kitchen
       # is therefore accepted and silently ignored by the daemon, which is why
       # the platform config had no effect on container creation. Post directly
       # when a platform is wanted; otherwise use the gem as before.
+      #
+      # @param args [Hash] the `/containers/create` body
+      # @param platform [String, nil] an OCI platform such as `linux/arm64/v8`
+      # @return [::Docker::Container] the created container
       def create_container_for_platform(args, platform)
         return ::Docker::Container.create(args, docker_connection) if platform.to_s.empty?
 
@@ -643,8 +902,13 @@ module Kitchen
         ::Docker::Container.get(args["name"], {}, docker_connection)
       end
 
+      # Create a container if needed, then start it and wait for it to run.
+      #
+      # @param args [Hash] the `/containers/create` body
+      # @param platform [String, nil] an OCI platform to pin the container to
+      # @return [::Docker::Container] the running container
       def run_container(args, platform: nil)
-        create_container(args, platform: platform)
+        @container = create_container(args, platform: platform)
         with_retries do
           @container.start
           @container = ::Docker::Container.get(args["name"], {}, docker_connection)
@@ -653,10 +917,17 @@ module Kitchen
         @container
       end
 
+      # The current container's `State` payload.
+      #
+      # @return [Hash] the state, or an empty hash if there is no container
       def container_state
         @container ? @container.info["State"] : {}
       end
 
+      # Stop a container and wait for it to leave the running state.
+      #
+      # @param name [String] the container name
+      # @return [void]
       def stop_container(name)
         with_retries { @container = ::Docker::Container.get(name, {}, docker_connection) }
         with_retries do
@@ -667,6 +938,10 @@ module Kitchen
         debug "Container #{name} not found. Nothing to stop."
       end
 
+      # Force-remove a container along with its anonymous volumes.
+      #
+      # @param name [String] the container name
+      # @return [void]
       def delete_container(name)
         with_retries { @container = ::Docker::Container.get(name, {}, docker_connection) }
         with_retries { @container.delete(force: true, v: true) }
@@ -674,6 +949,14 @@ module Kitchen
         debug "Container #{name} not found. Nothing to delete."
       end
 
+      # Poll a container until it reaches the wanted running state.
+      #
+      # Gives up after a bounded number of polls rather than blocking a converge
+      # forever, and stops early once the container has actually finished.
+      #
+      # @param name [String] the container name
+      # @param v [Boolean] the running state to wait for
+      # @return [void]
       def wait_running_state(name, v)
         @container = ::Docker::Container.get(name, {}, docker_connection)
         i = 0
@@ -687,29 +970,51 @@ module Kitchen
         end
       end
 
+      # The name of the shared chef volume container.
+      #
+      # @return [String] the container name
       def chef_container_name
         prefix = instance.provisioner[:product_name] == "cinc" ? "cinc" : "chef"
-        config[:platform] != "" ? "#{prefix}-#{chef_version}-" + config[:platform].tr("/", "-") : "#{prefix}-#{chef_version}"
+        # `platform: ~` in a kitchen.yml yields nil rather than the "" default.
+        platform = config[:platform].to_s
+        return "#{prefix}-#{chef_version}" if platform.empty?
+
+        "#{prefix}-#{chef_version}-#{platform.tr("/", "-")}"
       end
 
+      # The chef/cinc image the volume container is built from.
+      #
+      # @return [String] an image reference
       def chef_image
         "#{config[:chef_image]}:#{chef_version}"
       end
 
+      # The chef version to use, as an image tag.
+      #
+      # @return [String] a tag
       def chef_version
         return "latest" if config[:chef_version] == "stable"
 
         config[:chef_version]
       end
 
+      # The name of this instance's data container.
+      #
+      # @return [String] the container name
       def data_container_name
         "#{instance_name}-data"
       end
 
+      # The image the data container is built from.
+      #
+      # @return [String] an image reference
       def data_image
         config[:data_image]
       end
 
+      # The `PortBindings` value for the data container.
+      #
+      # @return [Hash] a Docker API PortBindings hash
       def data_port_bindings
         return port_bindings unless config[:data_ssh_port]
 
@@ -731,15 +1036,25 @@ module Kitchen
         end
       end
 
+      # The base image for the platform under test.
+      #
+      # @return [String] an image reference
       def platform_image
         config[:image] || platform_image_from_name
       end
 
+      # Derive an image reference from the kitchen platform name.
+      #
+      # @return [String] an image reference
       def platform_image_from_name
         platform, release = instance.platform.name.split("-")
         release ? [platform, release].join(":") : platform
       end
 
+      # Pull an image only when the daemon does not already have it.
+      #
+      # @param image [String] an image reference
+      # @return [void]
       def pull_if_missing(image)
         return if ::Docker::Image.exist?(registry_image_path(image), { "platform" => oci_platform(config[:platform]) }, docker_connection)
 
@@ -747,10 +1062,18 @@ module Kitchen
       end
 
       # https://github.com/docker/docker/blob/4fcb9ac40ce33c4d6e08d5669af6be5e076e2574/registry/auth.go#L231
+      # Reduce a config.json registry key to a bare host.
+      #
+      # @param val [String] a registry key, possibly a URL
+      # @return [String] the host
       def parse_registry_host(val)
         val.sub(%r{https?://}, "").split("/").first
       end
 
+      # Pull an image from its registry.
+      #
+      # @param image [String] an image reference
+      # @return [Boolean] true when the pull changed what is on disk
       def pull_image(image)
         path = registry_image_path(image)
         with_retries do
@@ -758,7 +1081,7 @@ module Kitchen
             original_image = Docker::Image.get(path, { "platform" => oci_platform(config[:platform]) }, docker_connection)
           end
 
-          new_image = Docker::Image.create({ "fromImage" => path, "platform" => config[:platform] }, docker_creds_for_image(image), docker_connection)
+          new_image = Docker::Image.create({ "fromImage" => path, "platform" => config[:platform] }, docker_creds_for_image(path), docker_connection)
 
           !(original_image&.id&.start_with?(new_image.id))
         end
@@ -769,6 +1092,9 @@ module Kitchen
       # matters: the daemon will not match a filter of
       # {"os":"linux","architecture":"amd64"} against a linux/amd64/v2 image,
       # so dropping it makes every image lookup for a variant image miss.
+      #
+      # @param platform [String, nil] an "os/arch[/variant]" string
+      # @return [String, nil] a JSON OCI platform spec, or the input unchanged
       def oci_platform(platform)
         return platform if platform.nil? || !platform.include?("/")
 
@@ -778,10 +1104,18 @@ module Kitchen
         spec.to_json
       end
 
+      # The name of this instance's runner container.
+      #
+      # @return [String] the container name
       def runner_container_name
         instance_name.to_s
       end
 
+      # Retry a docker API call through the errors that retrying can fix.
+      #
+      # @yield the API call to attempt
+      # @return [Object] the block's value
+      # @raise [::Docker::Error::DockerError] if every attempt failed
       def with_retries
         tries = api_retries
         begin