Updated by Linode Written by Linode
Use promo code DOCS10 for $10 credit on a new account.
KitchenSalt allows you to use Test Kitchen to test your Salt configurations locally without a Salt master or minions. In this guide you will install KitchenSalt and use Docker to test a Salt state. This guide was created using a system running Ubuntu 18.04.
Before You Begin
- You will need root access to your computer, or a user account with
sudoprivilege. For more information on privileges, see our Users and Groups guide.
- Install Git on your local computer, if it is not already installed.
- Update your system packages.
Install rbenv and Ruby
Kitchen runs on Ruby. The following commands will install the Ruby version controller rbenv, set rbenv in your PATH, and install Ruby via rbenv.
Install the packages necessary for rbenv:
sudo apt install libssl-dev libreadline-dev zlib1g-dev bzip2 gcc make git ruby-dev
Clone the rbenv git repository and set up your PATH:
sudo git clone git://github.com/rbenv/rbenv.git /usr/local/rbenv sudo mkdir /usr/local/rbenv/plugins sudo git clone git://github.com/rbenv/ruby-build.git /usr/local/rbenv/plugins/ruby-build sudo tee /etc/profile.d/rbenv.sh <<< 'export PATH="/usr/local/rbenv/plugins/ruby-build/bin:/usr/local/rbenv/bin:$PATH"' sudo tee -a /etc/profile.d/rbenv.sh <<< 'source <(rbenv init -)'
Reload your system’s profile so that the rbenv commands are added to your
You can also restart your shell session so the
PATHchanges take effect.
rbenv install 2.5.1
These steps install Docker Community Edition (CE) using the official Ubuntu repositories. To install on another distribution, see the official installation page.
Remove any older installations of Docker that may be on your system:
sudo apt remove docker docker-engine docker.io
Make sure you have the necessary packages to allow the use of Docker’s repository:
sudo apt install apt-transport-https ca-certificates curl software-properties-common
Add Docker’s GPG key:
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
Verify the fingerprint of the GPG key:
sudo apt-key fingerprint 0EBFCD88
You should see output similar to the following:
pub 4096R/0EBFCD88 2017-02-22 Key fingerprint = 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88 uid Docker Release (CE deb) <email@example.com> sub 4096R/F273FCD8 2017-02-22
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
Update your package index and install Docker CE:
sudo apt update sudo apt install docker-ce
Add your limited Linux user account to the
sudo usermod -aG docker exampleuser
You will need to restart your shell session for this change to take effect.
Check that the installation was successful by running the built-in “Hello World” program:
docker run hello-world
Install the bundler gem:
sudo gem install bundler
Create a Gemfile in your working directory and add the
1 2 3 4 5 6
#Gemfile source 'https://rubygems.org' gem 'kitchen-salt' gem 'kitchen-docker' gem 'kitchen-sync'
kitchen-syncis used to copy files to Docker containers more quickly.
Install the gems with bundler:
sudo bundle install
Create a Sample .sls File
For testing purposes, create a Salt state file that installs NGINX and ensures that it is running. In a text editor, create an
nginx.sls file in your working directory and add the following lines:
1 2 3 4 5 6 7 8
nginx: pkg: - installed service.running: - enable: True - reload: True - watch: - pkg: nginx
Now, write the Kitchen configuration file, beginning with the provisioner section. Copy the following lines into a
kitchen.ymlfile in your working directory.
1 2 3 4 5 6 7 8 9 10 11
provisioner: name: salt_solo salt_install: bootstrap is_file_root: true require_chef: false state_top: base: "*": - nginx ...
This section defines
salt_soloas the provisioner, which will allow Kitchen to use Salt without a Salt master. In this section Salt is installed via the bootstrap script by setting
salt_install: bootstrap, the Salt file root is mapped to the directory where
.kitchen.ymlis located by setting
is_file_root: true, and Chef is disabled by setting
require_chef: false. Instead of providing a top file for Salt states, the top file is declared inline. This section is also where Salt pillar files are added. For reference, they are added under the provisioner block:
1 2 3 4 5 6 7 8 9
provisioner: ... pillars: top.sls: base: "*": - nginx_pillar pillars_from_files: nginx_pillar.sls: nginx.pillar
Next, configure the driver section:
1 2 3 4 5 6 7 8 9 10
... driver: name: docker user_sudo: false privileged: true forward: - 80 ...
This section declares Docker as the driver, though you could also use Vagrant. Kitchen does not need to use
sudoto build the Docker containers, so
user_sudois set to
privilegedis set to
trueto ensure that the containers run systemd as the exec command. The Docker container will
forwardtraffic to the host on port
Configure the platforms section:
1 2 3 4 5 6 7 8
... platforms: - name: ubuntu driver_config: run_command: /lib/systemd/systemd ...
This section defines which platform Docker will run. By default Docker will run the latest version of that platform. Because different platforms place systemd in different locations, the
driver_configsection is used to point to the systemd install path of that platform. More than one platform can be defined.
Configure the suites section:
1 2 3 4 5 6 7 8
... suites: - name: oxygen provisioner: salt_bootstrap_options: -X -p git stable 2018.3 ...
suitesdefines which software suite Kitchen will test against. In this context, Kitchen will test against the Oxygen release of Salt. More than one suite can be defined.
Lastly, the transport section allows us to specify the use of
kitchen-syncfor transferring files:
1 2 3 4
... transport: name: sftp
You can now test your Salt configuration with Kitchen. Type the following command to run the test:
This command will create, converge, and then destroy the test instance. If completed successfully, the final terminal output will be:
-----> Kitchen is finished. (13m32.13s)
For a more granular approach to running your test, you can use the individual commands in series:
kitchen list kitchen create kitchen converge kitchen destroy
Using a Verifier and Next Steps
Though it is beyond the scope of this article, Kitchen allows for more robust testing than just checking a Salt configuration. You can write tests in bash using Bats, in Ruby using Minitest, Rspec, Serverspec and Inspec, or if you’re more familiar with Python you can use pytest.
As an example, you can add the following code to your
kitchen.yaml to verify your tests using the Inspec gem:
1 2 3 4
... verifier: name: inspec
For more information on writing tests, visit the links in the More Information section below.
You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.
Find answers, ask questions, and help others.
This guide is published under a CC BY-ND 4.0 license.