Awesome
Kitchen-Docker
A Test Kitchen Driver and Transport for Docker.
MAINTAINERS WANTED: This Test-Kitchen driver is currently without a maintainer and has many known issues. If you're interested in maintaining this driver for the long run including expanding the CI testing please reach out on Chef Community Slack: #test-kitchen. Until such a time that this driver is maintained we highly recommend the kitchen-dokken for Chef Infra testing with Docker containers.
Requirements
- Docker (>= 1.5)
Installation and Setup
Please read the Test Kitchen docs for more details.
Example (Linux) .kitchen.local.yml
:
---
driver:
name: docker
env_variables:
TEST_KEY: TEST_VALUE
platforms:
- name: ubuntu
run_list:
- recipe[apt]
- name: centos
driver_config:
image: centos
platform: rhel
run_list:
- recipe[yum]
transport:
name: docker
Example (Windows) .kitchen.local.yml
:
---
driver:
name: docker
platforms:
- name: windows
driver_config:
image: mcr.microsoft.com/windows/servercore:1607
platform: windows
run_list:
- recipe[chef_client]
transport:
name: docker
env_variables:
TEST_KEY: TEST_VALUE
Default Configuration
This driver can determine an image and platform type for a select number of platforms.
Examples:
---
platforms:
- name: ubuntu-18.04
- name: centos-7
This will effectively generate a configuration similar to:
---
platforms:
- name: ubuntu-18.04
driver_config:
image: ubuntu:18.04
platform: ubuntu
- name: centos-7
driver_config:
image: centos:7
platform: centos
Configuration
binary
The Docker binary to use.
The default value is docker
.
Examples:
binary: docker.io
binary: /opt/docker
socket
The Docker daemon socket to use. By default, Docker will listen on unix:///var/run/docker.sock
(On Windows, npipe:////./pipe/docker_engine
),
and no configuration here is required. If Docker is binding to another host/port or Unix socket, you will need to set this option.
If a TCP socket is set, its host will be used for SSH access to suite containers.
Examples:
socket: unix:///tmp/docker.sock
socket: tcp://docker.example.com:4242
If you are using the InSpec verifier on Windows, using named pipes for the Docker engine will not work with the Docker transport. Set the socket option with the TCP socket address of the Docker engine as shown below:
socket: tcp://localhost:2375
The Docker engine must be configured to listen on a TCP port (default port is 2375). This can be configured by editing the configuration file
(usually located in C:\ProgramData\docker\config\daemon.json
) and adding the hosts value:
"hosts": ["tcp://0.0.0.0:2375"]
Example configuration is shown below:
{
"registry-mirrors": [],
"insecure-registries": [],
"debug": true,
"experimental": false,
"hosts": ["tcp://0.0.0.0:2375"]
}
If you use Boot2Docker
or docker-machine set
your DOCKER_HOST
environment variable properly with export DOCKER_HOST=tcp://192.168.59.103:2375
or eval "$(docker-machine env $MACHINE)"
then use the following:
socket: tcp://192.168.59.103:2375
image
The Docker image to use as the base for the suite containers. You can find images using the Docker Index.
The default will be computed, using the platform name (see the Default Configuration section for more details).
isolation
The isolation technology for the container. This is not set by default and will use the default container isolation settings.
For example, the following driver configuration options can be used to specify the container isolation technology for Windows containers:
# Hyper-V
isolation: hyperv
# Process
isolation: process
platform
The platform of the chosen image. This is used to properly bootstrap the suite container for Test Kitchen. Kitchen Docker currently supports:
arch
debian
orubuntu
amazonlinux
,rhel
,centos
,fedora
,oraclelinux
,almalinux
orrockylinux
gentoo
orgentoo-paludis
opensuse/tumbleweed
,opensuse/leap
,opensuse
orsles
windows
The default will be computed, using the platform name (see the Default Configuration section for more details).
require_chef_omnibus
Determines whether or not a Chef Omnibus package will be installed. There are several different behaviors available:
true
- the latest release will be installed. Subsequent converges will skip re-installing if chef is present.latest
- the latest release will be installed. Subsequent converges will always re-install even if chef is present.<VERSION_STRING>
(ex:10.24.0
) - the desired version string will be passed the the install.sh script. Subsequent converges will skip if the installed version and the desired version match.false
ornil
- no chef is installed.
The default value is true
.
disable_upstart
Disables upstart on Debian/Ubuntu containers, as many images do not support a working upstart.
The default value is true
.
provision_command
Custom command(s) to be run when provisioning the base for the suite containers.
Examples:
provision_command: curl -L https://www.opscode.com/chef/install.sh | bash
provision_command:
- apt-get install dnsutils
- apt-get install telnet
driver_config:
provision_command: curl -L https://www.opscode.com/chef/install.sh | bash
require_chef_omnibus: false
env_variables
Adds environment variables to Docker container
Examples:
env_variables:
TEST_KEY_1: TEST_VALUE
SOME_VAR: SOME_VALUE
use_cache
This determines if the Docker cache is used when provisioning the base for suite containers.
The default value is true
.
use_sudo
This determines if Docker commands are run with sudo
.
The default value depends on the type of socket being used. For local sockets, the default value is true
. For remote sockets, the default value is false
.
This should be set to false
if you're using boot2docker, as every command passed into the VM runs as root by default.
remove_images
This determines if images are automatically removed when the suite container is destroyed.
The default value is false
.
run_command
Sets the command used to run the suite container.
The default value is /usr/sbin/sshd -D -o UseDNS=no -o UsePAM=no -o PasswordAuthentication=yes -o UsePrivilegeSeparation=no -o PidFile=/tmp/sshd.pid
.
Examples:
run_command: /sbin/init
memory
Sets the memory limit for the suite container in bytes. Otherwise use Dockers
default. You can read more about memory.limit_in_bytes
here.
cpu
Sets the CPU shares (relative weight) for the suite container. Otherwise use Dockers defaults. You can read more about cpu.shares here.
volume
Adds a data volume(s) to the suite container.
Examples:
volume: /ftp
volume:
- /ftp
- /srv
volumes_from
Mount volumes managed by other containers.
Examples:
volumes_from: repos
volumes_from:
- repos
- logging
- rvm
mount
Attach a filesystem mount to the container (NOTE: supported only in docker 17.05 and newer).
Examples:
mount: type=volume,source=my-volume,destination=/path/in/container
mount:
- type=volume,source=my-volume,destination=/path/in/container
- type=tmpfs,tmpfs-size=512M,destination=/path/to/tmpdir
tmpfs
Adds a tmpfs volume(s) to the suite container.
Examples:
tmpfs: /tmp
tmpfs:
- /tmp:exec
- /run
dns
Adjusts resolv.conf
to use the dns servers specified. Otherwise use
Dockers defaults.
Examples:
dns: 8.8.8.8
dns:
- 8.8.8.8
- 8.8.4.4
http_proxy
Sets an http proxy for the suite container using the http_proxy
environment variable.
Examples:
http_proxy: http://proxy.host.com:8080
https_proxy
Sets an https proxy for the suite container using the https_proxy
environment variable.
Examples:
https_proxy: http://proxy.host.com:8080
forward
Set suite container port(s) to forward to the host machine. You may specify the host (public) port in the mappings, if not, Docker chooses for you.
Examples:
forward: 80
forward:
- 22:2222
- 80:8080
hostname
Set the suite container hostname. Otherwise use Dockers default.
Examples:
hostname: foobar.local
privileged
Run the suite container in privileged mode. This allows certain functionality inside the Docker container which is not otherwise permitted.
The default value is false
.
Examples:
privileged: true
cap_add
Adds a capability to the running container.
Examples:
cap_add:
- SYS_PTRACE
cap_drop
Drops a capability from the running container.
Examples:
cap_drop:
- CHOWN
security_opt
Apply a security profile to the Docker container. Allowing finer granularity of access control than privileged mode, through leveraging SELinux/AppArmor profiles to grant access to specific resources.
Examples:
security_opt:
- apparmor:my_profile
dockerfile
Use a custom Dockerfile, instead of having Kitchen-Docker build one for you.
Examples:
dockerfile: test/Dockerfile
instance_name
Set the name of container to link to other container(s).
Examples:
instance_name: web
links
Set instance_name
(and alias) of other container(s) that connect from the suite container.
Examples:
links: db:db
links:
- db:db
- kvs:kvs
publish_all
Publish all exposed ports to the host interfaces. This option used to communicate between some containers.
The default value is false
.
Examples:
publish_all: true
devices
Share a host device with the container. Host device must be an absolute path.
Examples:
devices: /dev/vboxdrv
devices:
- /dev/vboxdrv
- /dev/vboxnetctl
build_context
Transfer the cookbook directory (cwd) as build context. This is required for Dockerfile commands like ADD and COPY. When using a remote Docker server, the whole directory has to be copied, which can be slow.
The default value is true
for local Docker and false
for remote Docker.
Examples:
build_context: true
build_options
Extra command-line options to pass to docker build
when creating the image.
Examples:
build_options: --rm=false
build_options:
rm: false
build-arg: something
run_options
Extra command-line options to pass to docker run
when starting the container.
Examples:
run_options: --ip=1.2.3.4
run_options:
tmpfs:
- /run/lock
- /tmp
net: br3
build_tempdir
Relative (to build_context
) temporary directory path for built Dockerfile.
Example:
build_tempdir: .kitchen
use_internal_docker_network
If you want to use kitchen-docker from within another Docker container you'll need to set this to true. When set to true uses port 22 as the SSH port and the IP of the container that chef is going to run in as the hostname so that you can connect to it over SSH from within another Docker container.
Examples:
use_internal_docker_network: true
docker_platform
Configure the CPU platform (architecture) used by docker to build the image.
Examples:
docker_platform: linux/arm64
docker_platform: linux/amd64
Development
- Source hosted at GitHub
- Report issues/questions/feature requests on GitHub Issues
Pull requests are very welcome! Make sure your patches are well tested. Ideally create a topic branch for every separate change you make. For example:
- Fork the repo
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Added some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
License
Copyright 2013-2016, [Sean Porter](https://github.com/portertech)
Copyright 2015-2016, [Noah Kantrowitz](https://github.com/coderanger)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.