kitchen-docker

by test-kitchen

test-kitchen / kitchen-docker

A Test Kitchen Driver for Docker

458 Stars 234 Forks Last release: Not found Apache License 2.0 416 Commits 42 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Kitchen-Docker

Build Status Gem Version Coverage License

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

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:

yaml
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: ```yaml

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
    or
    ubuntu
  • amazonlinux
    ,
    rhel
    ,
    centos
    ,
    fedora
    or
    oraclelinux
  • gentoo
    or
    gentoo-paludis
  • opensuse/tumbleweed
    ,
    opensuse/leap
    ,
    opensuse
    or
    sles
  • 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.
  •  (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
    or
    nil
    - 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

useinternaldocker_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

Development

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:

  1. Fork the repo
  2. Create your feature branch (
    git checkout -b my-new-feature
    )
  3. Commit your changes (
    git commit -am 'Added some feature'
    )
  4. Push to the branch (
    git push origin my-new-feature
    )
  5. Create new Pull Request

License

Copyright 2013-2016, Sean Porter Copyright 2015-2016, Noah Kantrowitz

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.