{"id":22529463,"url":"https://github.com/test-kitchen/kitchen-dokken","last_synced_at":"2026-01-23T00:38:23.998Z","repository":{"id":31565823,"uuid":"35130558","full_name":"test-kitchen/kitchen-dokken","owner":"test-kitchen","description":"Test Kitchen driver/provisioner for lightning faster Chef Infra cookbook testing with Docker","archived":false,"fork":false,"pushed_at":"2024-04-08T15:06:42.000Z","size":564,"stargazers_count":191,"open_issues_count":33,"forks_count":88,"subscribers_count":16,"default_branch":"main","last_synced_at":"2024-04-14T01:51:11.770Z","etag":null,"topics":["containers","docker","hacktoberfest","infrastucture","managed-by-terraform","ruby","ruby-gem","test-kitchen","testing"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/test-kitchen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2015-05-06T00:18:34.000Z","updated_at":"2024-02-26T11:46:20.000Z","dependencies_parsed_at":"2023-12-15T02:17:48.829Z","dependency_job_id":"e83f90c2-626e-4de1-aa0c-a843b7e93bc5","html_url":"https://github.com/test-kitchen/kitchen-dokken","commit_stats":{"total_commits":500,"total_committers":81,"mean_commits":6.172839506172839,"dds":0.692,"last_synced_commit":"f09859e7b28ef79030eccc4639e4214edd5c4733"},"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-kitchen%2Fkitchen-dokken","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-kitchen%2Fkitchen-dokken/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-kitchen%2Fkitchen-dokken/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-kitchen%2Fkitchen-dokken/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/test-kitchen","download_url":"https://codeload.github.com/test-kitchen/kitchen-dokken/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246578250,"owners_count":20799777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["containers","docker","hacktoberfest","infrastucture","managed-by-terraform","ruby","ruby-gem","test-kitchen","testing"],"created_at":"2024-12-07T07:14:48.513Z","updated_at":"2026-01-23T00:38:23.983Z","avatar_url":"https://github.com/test-kitchen.png","language":"Ruby","readme":"# kitchen-dokken\n\n[![Gem Version](https://badge.fury.io/rb/kitchen-dokken.svg)](https://badge.fury.io/rb/kitchen-dokken)\n\n## Overview\n\nThis Test Kitchen plugin provides a driver, transport, and provisioner for rapid cookbook testing and container development using Docker and Chef Infra Client.\n\n### Why should I use kitchen-dokken?\n\nkitchen-dokken is fast. Really fast.\n\nTest Kitchen itself has four components: Drivers, Transports, Provisioners, and Verifiers. Drivers are responsible for creating a system on local hypervisors or a cloud. Transports such as ssh or winrm are responsible for connecting to these hosts. Provisioners are responsible for provisioning the hosts to the desired state using scripts or configuration management tools. The final component is the verifier which is responsible for verifying the system state matches the desired state.\n\nUnlike all other Test Kitchen drivers, kitchen-dokken handles all the tasks of the driver, transport, and provisioner itself. This approach requires a narrow focus of just Chef Infra cookbook testing, but provides ultra-fast testing times. Docker containers have a fast creation and start time, and dokken uses the official Chef Infra Client containers instead of spending the time to download and install the client. These design decisions result in tests that run in seconds instead of minutes and don't require high bandwidth Internet connections.\n\n### kitchen-dokken vs. other drivers\n\nAs stated above kitchen-dokken is purpose-built for speed and it achieves this by narrowing the testing scope to just Chef Infra cookbook testing. Other drivers like kitchen-vagrant or kitchen-docker are general-purpose drivers that can be used with any of the Kitchen provisioners such as kitchen-puppet or kitchen-ansible. Also, keep in mind that testing with containers is not a perfect analog to a full-blown system. The dokken-images containers are designed to be similar to a standard OS install, but they do not perfectly match those installs and may need additional packages to work properly. If you're looking for a perfect analog to your production systems, without the additional work of package installation, then consider a driver such as kitchen-vagrant. If you're willing to potentially invest in a bit of package troubleshooting in exchange for faster feedback cycles then kitchen-dokken is for you.\n\n## Usage\n\nA sample kitchen-dokken `kitchen.yml` config:\n\n```yaml\n---\ndriver:\n  name: dokken\n  chef_version: latest # or 16 or 16.0 or 16.0.300 or current\n\ntransport:\n  name: dokken\n\nprovisioner:\n  name: dokken\n\nverifier:\n  name: inspec\n\nplatforms:\n- name: centos-7\n  driver:\n    image: dokken/centos-7\n\nsuites:\n  - name: default\n    run_list:\n    - recipe[hello_dokken::default]\n```\n\n## Podman usage\n\nFor specific podman guidance please see [the podman documentation](documentation/PODMAN.md).\n\n## How it works\n\n### Primordial State\n\n#### List kitchen suites\n\n```shell\n$ kitchen list\nInstance          Driver  Provisioner  Verifier  Transport  Last Action    Last Error\n```\n\n#### List containers\n\n```shell\n$ docker ps -a\nCONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES\n```\n\n#### List images\n\n```shell\n$ docker images\nREPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE\n```\n\n### Create phase\n\n#### kitchen create\n\n```shell\n$ kitchen create\n-----\u003e Starting Kitchen (v1.15.0)\n-----\u003e Creating \u003cdefault-centos-7\u003e...\n       Creating local sandbox at /Users/someara/.dokken/sandbox/6e1b03ab46-default-centos-7\n       Building work image..\n       Finished creating \u003cdefault-centos-7\u003e (0m21.04s).\n-----\u003e Kitchen is finished. (0m21.95s)\n```\n\nThe `kitchen create` phase of the kitchen run pulls (if missing) the `chef/chef` image from the Docker hub, then creates a volume container named `chef-\u003cversion\u003e`. This makes `/opt/chef` available for mounting by other containers.\n\nWhen talking to a local Docker host (over a socket), the driver creates and bind mounts a sandbox directory to `/opt/kitchen`. This prevents us from having to \"upload\" the test data.\n\nWhen talking to a *remote* Docker host (tcp://somewhere.else), dokken starts a container named `\u003csuite-name\u003e-data`. It makes `/opt/kitchen` and `/opt/verifier` available for mounting by the runner. The data container is the \"trick\" to the whole thing. It comes with rsync, runs an openssh daemon, and uses an insecure, authorized_key ala Vagrant. This is later used to upload cookbook test data.\n\nThe venerable `/tmp` directory is avoided, due to the popularity of `tmpfs` clobbering by inits.\n\nFinally, the driver pulls the image specified by the suite's platform section and creates a runner container named `\u003cunique_prefix\u003e-\u003csuitename\u003e`. This container bind-mounts the volumes from `chef-\u003cversion\u003e` and `\u003csuite-name\u003e-data`, giving access to Chef and the test data. By default, the `pid_one_command` of the runner container is a script that sleeps in a loop, letting us `exec` our provisioner in the next phase. It can be overridden with init systems like Upstart and systemd, for testing recipes with service resources as needed.\n\n#### List containers\n\n```shell\n$ docker ps -a\nCONTAINER ID        IMAGE                                COMMAND                  CREATED              STATUS              PORTS               NAMES\n3489588d4470        6e1b03ab46-default-centos-7:latest   \"sh -c 'trap exit ...\"   About a minute ago   Up About a minute                       6e1b03ab46-default-centos-7\nf678882b1575        chef/chef:current                    \"true\"                   About a minute ago   Created                                 chef-current\n```\n\n#### List images\n\n```shell\n$ docker images\nREPOSITORY                    TAG                 IMAGE ID            CREATED              SIZE\n6e1b03ab46-default-centos-7   latest              2ea1040b9c10        About a minute ago   192 MB\nchef/chef                     current             01ec788610e2        6 days ago           124 MB\ncentos                        7                   67591570dd29        7 weeks ago          192 MB\n```\n\n### Converge phase\n\n#### kitchen converge\n\n```shell\n$ time kitchen converge\n-----\u003e Starting Kitchen (v1.15.0)\n-----\u003e Converging \u003cdefault-centos-7\u003e...\n       Creating local sandbox in /Users/someara/.dokken/sandbox/6e1b03ab46-default-centos-7\n       Preparing dna.json\n       Preparing current project directory as a cookbook\n       Removing non-cookbook files before transfer\n       Preparing validation.pem\n       Preparing client.rb\nStarting Chef Infra Client, version 16.10.8\nCreating a new client identity for default-centos-7 using the validator key.\nresolving cookbooks for run list: [\"hello_dokken::default\"]\nSynchronizing Cookbooks:\n  - hello_dokken (0.1.0)\nInstalling Cookbook Gems:\nCompiling Cookbooks...\nConverging 1 resources\nRecipe: hello_dokken::default\n  * file[/hello] action create\n    - create new file /hello\n    - update content in file /hello from none to 2d6944\n    --- /hello    2017-02-08 04:23:01.780659287 +0000\n    +++ /.chef-hello20170208-41-105f1ha    2017-02-08 04:23:01.780659287 +0000\n    @@ -1 +1,2 @@\n    +hello\\n\n    - change mode from '' to '0644'\n    - change owner from '' to 'root'\n    - change group from '' to 'root'\n\nRunning handlers:\nRunning handlers complete\nChef Client finished, 1/1 resources updated in 01 seconds\n       Finished converging \u003cdefault-centos-7\u003e (0m2.61s).\n-----\u003e Kitchen is finished. (0m3.46s)\n\nreal    0m3.887s\nuser    0m1.080s\nsys    0m0.210s\n```\n\nThe `kitchen-converge` phase of the kitchen run uses the provisioner to upload cookbooks through the data container, then execs `chef-client` in the runner container. It does NOT install Chef Infra Client, as it has already been mounted by the driver. The transport then commits the runner container, creating an image that only contains the changes made by Chef.\n\n#### List containers\n\n```shell\n$ docker ps -a\nCONTAINER ID        IMAGE                          COMMAND                  CREATED             STATUS              PORTS                   NAMES\nc153dfd8e53d        e9fa5d3a0d0e                   \"sh -c 'trap exit 0 S\"   9 minutes ago       Up 9 minutes                                default-centos-7\n32c42fba4a8c        someara/kitchen-cache:latest   \"/usr/sbin/sshd -D -p\"   9 minutes ago       Up 9 minutes        0.0.0.0:32846-\u003e22/tcp   default-centos-7-data\n7e327add6bf2        chef/chef:12.5.1               \"true\"                   17 minutes ago      Created                                     chef-12.5.1\n```\n\n#### List images\n\n```shell\n$ docker images\nREPOSITORY              TAG                 IMAGE ID            CREATED             VIRTUAL SIZE\ndefault-centos-7        latest              ec1d208d77cd        8 minutes ago       172.3 MB\nsomeara/kitchen-cache   latest              abbdb063dff1        2 weeks ago         300.8 MB\nchef/chef               12.5.1              86245605bbe3        4 weeks ago         168.1 MB\ncentos                  7                   e9fa5d3a0d0e        6 weeks ago         172.3 MB\n```\n\n#### Diff container\n\n```shell\n$ docker diff default-centos-7\nA /hello\nC /opt\nA /opt/chef\nA /opt/kitchen\nC /run\nA /run/mount\nA /run/mount/utab\nC /tmp\nC /var/lib/rpm/.dbenv.lock\nC /var/lib/rpm/__db.001\nC /var/lib/rpm/__db.002\nC /var/lib/rpm/__db.003\n```\n\n### Verify phase\n\n#### kitchen verify\n\n```shell\n$ time kitchen verify\n-----\u003e Starting Kitchen (v1.15.0)\n-----\u003e Setting up \u003cdefault-centos-7\u003e...\n       Finished setting up \u003cdefault-centos-7\u003e (0m0.00s).\n-----\u003e Verifying \u003cdefault-centos-7\u003e...\n       Loaded\n\nTarget:  docker://84def4c49ce3703e42ac2be8a95c672d561c052520ca90788d42bbdb94e7cc6f\n\n\n  File /hello\n     ✔  should be file\n     ✔  should be mode 420\n     ✔  should be owned by \"root\"\n     ✔  should be grouped into \"root\"\n\nTest Summary: 4 successful, 0 failures, 0 skipped\n       Finished verifying \u003cdefault-centos-7\u003e (0m0.80s).\n-----\u003e Kitchen is finished. (0m1.99s)\n\nreal    0m2.695s\nuser    0m1.310s\nsys    0m0.365s\n```\n\nThe `kitchen-verify` phase uses the transport to run acceptance tests, verifying image state.\n\n#### List containers\n\n```shell\n$ docker ps -a\nCONTAINER ID        IMAGE                                COMMAND                  CREATED             STATUS              PORTS               NAMES\n84def4c49ce3        6e1b03ab46-default-centos-7:latest   \"sh -c 'trap exit ...\"   6 minutes ago       Up 6 minutes                            6e1b03ab46-default-centos-7\nf678882b1575        chef/chef:current                    \"true\"                   9 minutes ago       Created                                 chef-current\n```\n\n#### List images\n\n```shell\n$ docker images\nREPOSITORY                    TAG                 IMAGE ID            CREATED             SIZE\n6e1b03ab46-default-centos-7   latest              fec1a50470ed        6 minutes ago       192 MB\nchef/chef                     current             01ec788610e2        6 days ago          124 MB\ncentos                        7                   67591570dd29        7 weeks ago         192 MB\n```\n\n### Destroy phase\n\n#### kitchen destroy\n\n```shell\n$ kitchen destroy\n-----\u003e Starting Kitchen (v1.15.0)\n-----\u003e Destroying \u003cdefault-centos-7\u003e...\n       Deleting local sandbox at /Users/someara/.dokken/sandbox/6e1b03ab46-default-centos-7\n       Finished destroying \u003cdefault-centos-7\u003e (0m0.83s).\n-----\u003e Kitchen is finished. (0m1.81s)\n```\n\n#### List containers\n\n```shell\n$ docker ps -a\nCONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES\nf678882b1575        chef/chef:current   \"true\"              10 minutes ago      Created                                 chef-current\n```\n\n#### List images\n\n```shell\n$ docker images\nREPOSITORY          TAG                 IMAGE ID            CREATED             SIZE\nchef/chef           current             01ec788610e2        6 days ago          124 MB\ncentos              7                   67591570dd29        7 weeks ago         192 MB\n```\n\n## Advanced Configuration\n\nDue to the nature of Docker, a handful of considerations need to be addressed.\n\nA complete example of a non-trivial `kitchen.yml` is found in the `docker` cookbook, at \u003chttps://github.com/chef-cookbooks/docker/blob/master/kitchen.yml\u003e\n\n### Minimalist images\n\nThe Distros (debian, centos, etc) will typically manage an official image on the Docker Hub. They are really pushing the boundaries of minimalist images, well beyond what is typically laid to disk as part of a \"base installation\".\n\nVery often, an image will come with a package manager, GNU coreutils, and that's about it. This can differ greatly from what is found in typical Vagrant and IaaS images.\n\nBecause of this, it is often necessary to \"cheat\" and install prerequisites\ninto the image before running Chef, Serverspec, or your own programs.\n\nTo help with this, the Dokken driver provides an `intermediate_instructions` directive. Here is an example from `httpd`\n\n```yaml\nplatforms:\n- name: debian-7\n  driver:\n    image: debian:7\n    intermediate_instructions:\n      - RUN /usr/bin/apt-get update\n      - RUN /usr/bin/apt-get install -y apt-transport-https net-tools\n```\n\nIf present, an intermediate image is built, using a Dockerfile rendered from lines\nprovided. Any valid instruction will work, including `MAINTAINER`,\n`ENTRYPOINT`, `VOLUMES`, etc. Knowledge of Docker is assumed.\n\nThis should be used as little as possible.\n\n#### Example use case of intermediate_instruction\n\nA possible use case is running kitchen behind a [MITM proxy](https://en.wikipedia.org/wiki/Man-in-the-middle_attack)\nIf you did read the link, it's scary yes, but a reality in many corporate networks where any HTTPS connection is intercepted, when done right (morally) the proxy uses an internal Certificate Authority (CA) which is not trusted by most programs.\n\nIt's always a problem to get things accessing TLS secured servers through this kind of proxy when working in a container and here is how you can do it for Chef specifically.\n\nUsing kitchen `intermediate_instructions` and `entrypoint` you can overcome the problem in dokken in this way:\n\n```yaml\ndriver:\n  name: dokken\n  chef_version: 16\n  entrypoint: /bin/entrypoint\n  intermediate_instructions:\n    - RUN /usr/bin/openssl s_client -showcerts -verify 5 -connect free.fr:443 \u003c/dev/null | /usr/bin/awk '/BEGIN/,/END/{if(/BEGIN/){a++}; certs[a]=(certs[a] \"\\n\" $0)}; END {print certs[a]}' \u003e\u003e /usr/local/share/ca-certificates/ca.crt \u0026\u0026 update-ca-certificates\n    - RUN echo  \"#!/bin/shell -ex\\ncat /usr/local/share/ca-certificates/ca.crt \u003e\u003e /opt/chef/embedded/ssl/certs/cacert.pem\\nexec \\\"\\$@\\\"\\n\" \u003e\u003e /bin/entrypoint \u0026\u0026 chmod +x /bin/entrypoint\n```\n\nThe code above does call a site (here free.fr, my french ISP :)) with openssl s_client and does an ugly awk parsing to extract the root CA from the chain and write it in `/usr/local/share/ca-certificate/ca.crt` and then update system certs (which makes curl, wget, and other system calls works with the proxy)\n\nThe second RUN creates an entrypoint for the container which will add the cert to Chef CA bundle and then exec whatever is passed as `pid_one_command` (see next paragraph, it does match CMD in dockerfile), this ensures once the container is created with chef volume and data volume mounted, the Chef's CA bundle accept your proxy certificate.\n\nCaveat: multiple suites running will add the cert to the chef container each time and consume a significant amount of disk space over time. In CI systems you'll want to regularly prune containers to avoid this problem.\n\n### Process orientation\n\nDocker containers are process oriented rather than machine oriented. This makes life interesting when testing things not necessarily destined to run in Docker. Specifically, Chef Infra recipes that utilize the `service` resource present a problem. To overcome this, we run the container in a way that mimics a machine.\n\nAs mentioned previously, we use an infinite loop to keep the container process from exiting. This allows us to do multiple `kitchen converge` and `kitchen login` operations without needing to commit a layer and start a new container. This is fine until we need to start testing recipes that use the `service` resource.\n\nThe default `pid_one_command` is `'sh -c \"trap exit 0 SIGTERM; while :; do sleep 1; done\"'`\n\nIf you need to use the service resource to drive Upstart or systemd, you'll need to specify the path to init. Here are more examples from `httpd`\n\n- systemd for RHEL-7 based platforms\n\n```yaml\nplatforms:\n- name: centos-7\n  driver:\n    image: centos:7\n    privileged: true\n    pid_one_command: /usr/lib/systemd/systemd\n    volumes:\n      - /sys/fs/cgroup:/sys/fs/cgroup:ro # required by systemd\n\n```\n\nYou can combine `intermediate_instructions` and `pid_one_command` as needed.\n\n- Upstart for Ubuntu 12.04\n\n```yaml\n- name: ubuntu-12.04\n  driver:\n    image: ubuntu-upstart:12.04\n    pid_one_command: /sbin/init\n    intermediate_instructions:\n      - RUN /usr/bin/apt-get update\n      - RUN /usr/bin/apt-get install apt-transport-https\n```\n\n### Running with User Namespaces enabled\n\nIF you are running a Docker daemon with user namespace remapping enabled you'll get errors running dokken with privileged containers.\n\nTo mitigate this, add the following to your driver definition:\n\n```yaml\nplatforms:\n- name: centos-7\n  driver:\n    image: centos:7\n    privileged: true\n    userns_host: true\n```\n\nThis will disable user namespaces for the running container.\n\n### Caching Downloaded Files\n\nOn Debian/Ubuntu systems, all files downloaded via it's package manager (`apt`) are stored at `/var/cache/apt/archives/`.\nTherefore one may save the downloads on a different volume and therefore save time. One may even use one's own apt cache folder to save even more time.\n\nOn some versions of Ubuntu (16.04 at least), the container deletes all the downloads upon every run of `apt-get update`, so that must be disabled\n\n- `apt` Caching on Ubuntu 16.04\n\n```yaml\n---\ndriver:\n  name: dokken\n  volumes:\n  # saves the apt archives outside of the container\n  - /var/cache/apt/archives/:/var/cache/apt/archives/\n\nplatforms:\n- name: ubuntu-16.04\n  driver:\n    image: dokken/ubuntu-16.04\n    pid_one_command: /bin/systemd\n    intermediate_instructions:\n      # prevent APT from deleting the APT folder\n      - RUN rm /etc/apt/apt.conf.d/docker-clean\n```\n\n### Chef cache\n\nWhen chef converges `kitchen-dokken` populates `/opt/kitchen/` with the chef and test kitchen data required to converge. By default this directory is cleared out at the end of every run. One of the subdirectories of `/opt/kitchen/` is the chef cache directory. For cookbooks that download significant amounts of data from the network, i.e. many `remote_file` calls, this can make subsequent converges unnecessarily slow.\nIf you would like the chef cache to be preserved between converges add `clean_dokken_sandbox: false` to the provisioner section of `kitchen.yml`. The default value is true.\n\n```yaml\nprovisioner:\n  name: dokken\n  clean_dokken_sandbox: false\n```\n\n### Using dokken-images\n\nWhile the `intermediate_instructions` directive is a fine hack around the\nminimalist image issue, it remains exactly that: A hack. If you\nwork on a lot of cookbooks you will find yourself copying around\nboilerplate to get things working. Also, it's slow. Running\n`apt-get update` and\n[installing iproute2](https://github.com/test-kitchen/dokken-images/pull/13/files)\nall the time is a huge bummer.\n\nTo solve this, we maintain the\n[dokken-images](https://github.com/test-kitchen/dokken-images) collection\nof fat images that you can find pushed to [Docker Hub](https://hub.docker.com/u/dokken). The package list aims to make sure things like ohai\nfunction in a reasonable way and doing a `kitchen login` yields a\nuseful environment for debugging. They're hosted on the Docker cloud\nand are rebuilt every day to keep the package metadata fresh.\n\nTo use them, simply prefix a distro with \"dokken/\" in the `image`\nname. Unfortunately, you'll still have to specify `pid_one_command` (for\nthe time being).\n\n```yaml\n- name: ubuntu-16.04\n  driver:\n    image: dokken/ubuntu-16.04\n    pid_one_command: /bin/systemd\n  run_list:\n  - recipe[whatever::recipe]\n```\n\nIf you have your own mirror of Docker Hub, or you are using a registry other\nthan Docker Hub, you can tell Dokken to always pull from a different registry\nby setting `docker_registry` under `driver`:\n\n```yaml\ndriver:\n  docker_registry: docker.sample.com\n```\n\nIf you do this, it must have access to the dokken images for the platforms you\nwant to test as well as the `centos` image that is used for the dynamic\ntesting image.\n\n### Tmpfs on /tmp\n\nWhen starting a container with an init system, it will often mount a tmpfs into `/tmp`. When this happens, it is necessary to specify a `root_path` for the verifier if using traditional Bats or Serverspec. This is due to Docker bind mounting the kitchen data before running init. This is not necessary when using Inspec.\n\n```yaml\nverifier:\n  root_path: '/opt/verifier'\n  sudo: false\n```\n\n### Install Chef Infra Client from current channel\n\nChef publishes all functioning builds to the [Docker Hub](https://hub.docker.com/r/chef/chef/tags),\nincluding those from the \"current\" channel. If you wish to use pre-release versions of Chef, set your `chef_version` value to \"current\". If you need to test older versions of `chef-client` that are not available on docker hub as `chef/chef`, you can overwrite `chef_image` under the [driver context](https://github.com/test-kitchen/kitchen-dokken/blob/2.5.1/lib/kitchen/driver/dokken.rb#L40) to a custom image name such as `someara/chef`.\n\n### Chef Infra Client options\n\nIt is possible to pass several extra configs to configure the chef binary and options, for example\n to use older versions that do not have the \"-z\" switch or to get some debug logging.\n\n```yaml\nprovisioner:\n  chef_binary: /opt/chef/bin/chef-solo\n  chef_options: \"\"\n  chef_log_level: debug\n  chef_output_format: minimal\n  profile_ruby: true\n```\n\n### Disable pulling platform Docker images\n\nTo test a locally built image without pulling it first, one can disable\npulling of platform images, which will avoid pulling images that already\nexist locally.\n\n```yaml\ndriver:\n  name: dokken\n  pull_platform_image: false\n```\n\n### Disable pulling chef Docker images\n\nTo skip the pulling of the Chef Docker image unless it doesn't exist locally:\n\n```yaml\ndriver:\n  name: dokken\n  pull_chef_image: false\n```\n\n### Testing for Slow Resources in Cookbooks\n\nYou can enable the slow resource report at the end of the run in Chef Infra Client 17.2 or later with the `slow_resource_report` config option:\n\n```yaml\nprovisioner:\n  slow_resource_report: true\n```\n\n### Testing without Chef\n\nContainers that supply a no-op binary which returns a successful exit status can be tested without requiring Chef Infra to actually converge.\n\n```yaml\nverifier:\n  name: inspec\n\nplatforms:\n  - name: alpine\n    driver:\n      image: alpine:latest\n    provisioner:\n      chef_binary: /bin/true\n```\n\n### Controlling container memory\n\nBy default the memory limit of the containers you run is unbound (or limited by the Docker client on OSX). If however you need to constrain the container memory allocation you can set a memory limit in bytes on the driver:\n\n```yaml\ndriver:\n  name: dokken\n  memory_limit: 2147483648 # 2GB\n```\n\n### Adding hostname aliases\n\nYou can set the `hostname_aliases` parameter to create additional hostnames that will resolve to the container:\n\n```yaml\ndriver:\n  name: dokken\n  hostname_aliases:\n    - foo\n```\n\n### Specifying SSH port for data container\n\nWhen using a remote Docker host, the data container's SSH service is mapped to a random host port (typically starting from 32768). You can specify a fixed port using the `data_ssh_port` parameter to simplify firewall configuration:\n\n```yaml\ndriver:\n  name: dokken\n  data_ssh_port: 30000\n```\n\nThis will bind the data container's SSH port (22) to host port 30000. This is only applicable when using remote Docker hosts or when running kitchen-dokken inside a Docker container.\n\n**Note:** If you don't specify `data_ssh_port`, Docker will automatically assign a random available port (default behavior).\n\n### IPv6 Networking\n\nYou can set the `ipv6` parameter to enable IPv6 networking on the `dokken` Docker network. Additionally, the `ipv6_subnet` parameter can be used to determine the subnet the network should use.\n\n```yaml\ndriver:\n  name: dokken\n  ipv6: true\n  ipv6_subnet: \"2001:db8:1::/64\"  # \"2001:db8::/32 Range reserved for documentation\"\n```\n\nThis parameter should be considered a global setting for all dokken containers since dokken does not update the `dokken` network once it's been created. It is *not* recommend to use this parameter within suites.\n\nYou can check to see if IPv6 is enabled on the dokken network by seeing if the following command returns `true`:\n\n```shell\ndocker network inspect dokken --format='{{.EnableIPv6}}'\n```\n\nIf the command returns `false`, we recommend you delete the network and allow dokken to recreate it with IPv6.\n\nTo allow IPv6 Docker networks to reach the internet IPv6 firewall rules must be set up. The simplest way to achieve this is to update Docker's `/etc/docker/daemon.json` to use the following settings. You will need to restart the docker daemon after making these changes.\n\n```json\n{\n  \"experimental\": true,\n  \"ip6tables\": true\n}\n```\n\nSome containers require the `ip6table_filter` kernel module to be loaded on the host system or ip6tables will not function on the container (Centos 7 for example). To check if the module is loaded use the command\n\n```shell\nsudo lsmod | grep ip6table_filter\n```\n\n. If there is no output than the module is not loaded and should be loaded using the command\n\n```shell\nmodprobe ip6table_filter\n```\n\n### Private Docker Registries\n\nIf the registry is private, you can configure the credentials that are required to authenticate the private docker registry in `creds_file` configuration.\n\n```yaml\nplatforms:\n  - name: centos-7\n    driver:\n      image: reg/centos-7\n      creds_file: './creds.json'\n```\n\nAnd the `creds.json` file may look like this:\n\n```json\n{\n   \"username\": \"org_username\",\n   \"password\": \"password\",\n   \"email\": \"email@org.com\",\n   \"serveraddress\": \"https://registry.org.com/\"\n}\n```\n\n### Docker config file auth\n\nInstead of using a `creds_file`, you can read authentication information from your docker config at `~/.docker/config.json`\n\n```yaml\nplatforms:\n  - name: centos-7\n    driver:\n      image: quay.io/example/centos:7\n      docker_config_creds: true\n```\n\nAnd your `~/.docker/config.json` would have an auth section for your private registry:\n\n```json\n{\n  \"auths\": {\n    \"quay.io\": {\n      \"auth\": \"\u003cbase64 encoded username:password\u003e\"\n    }\n  }\n}\n```\n\nAdditionally, you can use [Docker credential helpers](https://docs.docker.com/engine/reference/commandline/login/#credential-helpers)\n\n```yaml\nplatforms:\n  - name: centos-7\n    driver:\n      image: 1234-cloud-registry.example.com/centos:7\n      docker_config_creds: true\n```\n\nand your docker config has\n\n```json\n{\n  \"credHelpers\": {\n    \"1234-cloud-registry.example.com\": \"example-cloud\"\n  }\n}\n```\n\nThen `kitchen-dokken` will run the `docker-credential-example-cloud` command to get the credentials.\n\n## FAQ\n\n### What about kitchen-docker?\n\nWe already had a thing that drives Docker, why did you make this instead of modifying that?\n\nThe current `kitchen-docker` driver ends up baking SSH, Chef, and the kitchen data\ninto the image. This does not. To make this work, I had to create a Driver, a Transport,\nand a Provisioner that blur the traditional duties of each. The current Docker driver\ncan be used with Puppet, Ansible, CFEngine provisioners. This requires Chef.\n\nSee [\"Kitchen-Docker or Kitchen-Dokken? Using Test Kitchen and Docker for fast cookbook testing\"](https://www.chef.io/blog/kitchen-docker-or-kitchen-dokken-using-test-kitchen-and-docker-for-fast-cookbook-testing) for a more detailed comparison.\n\n### How can I use kitchen to automatically test and publish containers?\n\nRight now there is no `kitchen publish` mechanism. [See this issue](https://github.com/test-kitchen/test-kitchen/issues/329).\n\nYou can, however, do it manually.\n\n```shell\ncd my_cookbook ;\nkitchen verify suite_name\ndocker stop suite_name\ndocker tag suite_name:latest my.computers.biz:5043/something/whatever\ndocker push my.computers.biz:5043/something/whatever\nkitchen destroy\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftest-kitchen%2Fkitchen-dokken","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftest-kitchen%2Fkitchen-dokken","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftest-kitchen%2Fkitchen-dokken/lists"}