Skip to main content

kitchen.yml

[edit on GitHub]

Use Test Kitchen to automatically test cookbook data across any combination of platforms and test suites:

  • Defined in a kitchen.yml file
  • Uses a driver plugin architecture
  • Supports cookbook testing across many cloud providers and virtualization technologies
  • Supports all common testing frameworks that are used by the Ruby community
  • Uses a comprehensive set of base images provided by Bento

Use a kitchen.yml file to define what is required to run Test Kitchen, including drivers, provisioners, platforms, and test suites.

Note

This topic details functionality that is packaged with Chef Workstation. See https://kitchen.ci/docs/getting-started/ for more information about Kitchen.

Syntax

The basic structure of a kitchen.yml file is as follows:

driver:
  name: driver_name

provisioner:
  name: provisioner_name

verifier:
  name: verifier_name

transport:
  name: transport_name

platforms:
  - name: platform-version
    driver:
      name: driver_name
  - name: platform-version

suites:
  - name: suite_name
    run_list:
      - recipe[cookbook_name::recipe_name]
    attributes: { foo: "bar" }
    excludes:
      - platform-version
  - name: suite_name
    driver:
      name: driver_name
    run_list:
      - recipe[cookbook_name::recipe_name]
    attributes: { foo: "bar" }
    includes:
      - platform-version

where:

  • driver_name is the name of a driver that will be used to create platform instances used during cookbook testing. This is the default driver used for all platforms and suites unless a platform or suite specifies a driver to override the default driver for that platform or suite; a driver specified for a suite will override a driver set for a platform

  • provisioner_name specifies how Chef Infra Client will be simulated during testing. chef_zero and chef_solo are the most common provisioners used for testing cookbooks

  • verifier_name specifies which application to use when running tests, such as inspec

  • transport_name specifies which transport to use when executing commands remotely on the test instance. winrm is the default transport on Windows. The ssh transport is the default on all other operating systems.

  • platform-version is the name of a platform on which Test Kitchen will perform cookbook testing, for example, ubuntu-16.04 or centos-7; depending on the platform, additional driver details—for example, instance names and URLs used with cloud platforms like OpenStack or Amazon EC2—may be required

  • platforms may define Chef Infra Server attributes that are common to the collection of test suites

  • suites is a collection of test suites, with each suite_name grouping defining an aspect of a cookbook to be tested. Each suite_name must specify a run-list, for example:

    run_list:
      - recipe[cookbook_name::default]
      - recipe[cookbook_name::recipe_name]
    
  • Each suite_name grouping may specify attributes as a Hash: { foo: "bar" }

  • A suite_name grouping may use excludes and includes to exclude/include one (or more) platforms. For example:

    excludes:
       - platform-version
       - platform-version       # for additional platforms
    

For example, a very simple kitchen.yml file:

driver:
  name: vagrant

provisioner:
  name: chef_zero

platforms:
  - name: ubuntu-18.04
  - name: centos-8
  - name: debian-10

suites:
  - name: default
    run_list:
      - recipe[apache::httpd]
    excludes:
      - debian-10

This file uses Vagrant as the driver, which requires no additional configuration because it’s the default driver used by Test Kitchen, chef-zero as the provisioner, and a single (default) test suite that runs on Ubuntu 16.04, and CentOS 7.

Provisioner Settings

Test Kitchen’s provisioner settings will be changing in a future version. See Chef RFC 091 for details. Settings that will be deprecated are listed in the descriptions below. The new recommended settings are listed in the New Provisioner Settings table.

Kitchen can configure the chef-zero provisioner with the following Chef-specific settings:

Setting Description
attributes Chef attributes for use in the suite
chef_client_path Chef Infra Client provisioner only.
chef_metadata_url This will be deprecated in a future version.
chef_omnibus_install_options Use to specify the package to be installed. Possible values: -P chef (for Chef Infra Client) and -P chef-workstation (for the Chef Infra Client that is packaged as part of Chef Workstation). Use -n to specify the nightly build. For example: -P chef-workstation or -n -P chef-workstation. This will be deprecated in a future version. See the product_name, product_version, and channel settings instead.
chef_omnibus_root Default value: /etc/opt for UNIX and Linux, $env:systemdrive\\opscode\\chef on Microsoft Windows.
chef_omnibus_url The URL for an install.sh script that will install Chef Infra Client on the machine under test. Default value: https://www.chef.io/chef/install.sh. This will be deprecated in a future version.
chef_solo_path chef-solo provisioner only.
chef_zero_host Chef Infra Client provisioner only.
chef_zero_port Chef Infra Client provisioner only. The port on which chef-zero is to listen.

client_rb

Chef Infra Client provisioner only. A list of client.rb file settings. For example:

client_rb:
  log_level: :warn
clients_path The relative path to the directory in which client data is located. This data must be defined as JSON.
cookbook_files_glob A file glob (pattern) that matches files considered to be part of the cookbook. (Typically, this value does not need to be modified from the default.)
data_path Use to specify the path from which non-cookbook files are copied to a Kitchen instance.
data_bags_path The relative path to a directory in which data bags and data bag items are defined. This data must be structured as if it were in the chef-repo.
deprecations_as_errors Set to true to treat deprecation warning messages as error messages.
driver Use to specify a driver for a platform. This will override the default driver.
enforce_idempotency Use with multiple_converge > 1. Set to true to force test-kitchen to fail if last converge has any updated resources.
encrypted_data_bag_secret_key_path The path to an RSA key file that is used to decrypt encrypted data bag items.
environments_path The relative path to the directory in which environment data is located. This data must be defined as JSON.
http_proxy The proxy server for HTTP connections.
https_proxy The proxy server for HTTPS connections.
no_proxy The comma-separated exception list of host patterns to exclude from proxying.
install_msi_url An alternate URL for a Windows MSI package that will install Chef Infra Client on the machine under test. This will be deprecated in a future version. Use the download_url setting instead.
json_attributes Chef Infra Client provisioner only.
log_file
multiple_converge Number of times to converge the node. Defaults to 1.
nodes_path The relative path to the directory in which node data is located. This data must be defined as JSON.
require_chef_omnibus Use to install the latest version of Chef Infra Client on a node. Set to true to install the latest version, false to not install Chef Infra Client (assumes the box already has it installed), or a version specifier like 15.3.12 to install a particular version, or simply 15 to install the latest 15.x package. When set to true or a version number, the chef_omnibus_url may be used to specify the URL of the install.sh that installs the specified version of Chef Infra Client. Default value: true. This will be deprecated in a future version. See the product_version and install_strategy settings.
roles_path The relative path to the directory in which role data is located. This data must be defined as JSON.
root_path The directory in which Kitchen will stage all content on the target node. This directory should be large enough to store all the content and must be writable. (Typically, this value does not need to be modified from the default value.) Default value: /tmp/kitchen.
ruby_bindir Chef Infra Client provisioner only.
run_list
solo_rb chef-solo provisioner only.
retry_on_exit_code Takes an array of exit codes to indicate that kitchen should retry the converge command. Default value: [35, 213].
max_retries Number of times to retry the converge before passing along the failed status. Defaults value: 1.
wait_for_retry Number of seconds to wait between converge attempts. Default value: 30.

These settings may be added to the provisioner section of the kitchen.yml file when the provisioner is chef-zero or chef-solo.

New Provisioner Settings

New Setting Description Default Replaces
product_name chef or chef-workstation. This setting must be specified in order to use the new settings. Using this setting overrides Test Kitchen's default behavior based on the require_chef_omnibus setting. chef_omnibus_install_options
product_version Product version number. Supports partial version numbers. latest require_chef_omnibus
channel Artifact repository name. stable, current or unstable. stable chef_omnibus_install_options
install_strategy Product install strategy. once (Don't install if any product installation detected), always or skip. once require_chef_omnibus
download_url Direct package URL. Supports all platforms. install_msi_url
checksum Optional setting when using download_url. Validates SHA256 checksum after download.
platform Override platform. <auto detected>
platform_version Override platform platform. <auto detected>
architecture Override platform architecture. <auto detected>

Note

There are two community provisioners for Kitchen: kitchen-dsc and kitchen-pester.

Transport Settings

Kitchen can configure a transport with the following settings for either ssh or winrm transports:

Setting Description
connection_retries Maximum number of times to retry after a failed attempt to open a connection. The default is 5.
connection_retry_sleep Number of seconds to wait until attempting to make another connection after a failure.
max_wait_until_ready Maximum number of attempts to determine if the test instance is ready to accept commands. This defaults to 600.
password The password used for authenticating to the test instance.
port The port used to connect to the test instance. This defaults to 22 for the ssh transport and 5985 or 5986 for winrm using http or https respectively.
username The username used for authenticating to the test instance. This defaults to administrator for the winrm transport and root for the ssh transport. Some drivers may change this default.

These settings may be added to the transport section of the kitchen.yml file when the transport is SSH:

Setting Description
compression Wether or not to use compression. The default is false.
compression_level The default is 6 if compression is true.
connection_timeout Defaults to 15.
keepalive Defaults to true.
keepalive_interval Defaults to 60.
max_ssh_sessions Maximum number of parallel ssh sessions.
ssh_key Path to an ssh key identity file.

These settings may be added to the transport section of the kitchen.yml file when the transport is WinRM:

Setting Description
elevated When true, all commands are executed via a scheduled task. This may eliminate access denied errors related to double hop authentication, interacting with windows updates and installing some MSIs such as sql server and .net runtimes. Defaults to false.
elevated_password The password used by the identity running the scheduled task. This may be null in the case of service accounts. Defaults to password.
elevated_username The identity that the task runs under. This may also be set to service accounts such as System. This defaults to username.
rdp_port Port used making rdp connections for kitchen login commands. Defaults to 3389.
winrm_transport The transport type used by winrm as explained here. The default is negotiate. ssl and plaintext are also acceptable values.

Work with Proxies

The environment variables http_proxy, https_proxy, and ftp_proxy are honored by Test Kitchen for proxies. The client.rb file is read to look for proxy configuration settings. If http_proxy, https_proxy, and ftp_proxy are specified in the client.rb file, Chef Infra Client will configure the ENV variable based on these (and related) settings. For example:

http_proxy 'http://proxy.example.org:8080'
http_proxy_user 'myself'
http_proxy_pass 'Password1'

will be set to:

ENV['http_proxy'] = 'http://myself:Password1@proxy.example.org:8080'

Test Kitchen also supports http_proxy and https_proxy in the kitchen.yml file. You can set them manually or have them read from your local environment variables:

driver:
  name: vagrant

provisioner:
  name: chef_zero
  # Set proxy settings manually, or
  http_proxy: 'http://user:password@server:port'
  https_proxy: 'http://user:password@server:port'

  # Read from local environment variables
  http_proxy: <%= ENV['http_proxy'] %>
  https_proxy: <%= ENV['https_proxy'] %>

This will not set the proxy environment variables for applications other than Chef. The Vagrant plugin, vagrant-proxyconf, can be used to set the proxy environment variables for applications inside the VM.

Chef Infra Client Settings

A kitchen.yml file may define Chef Infra Client-specific settings, such as whether to require the Chef installer or the URL from which Chef Infra Client is downloaded, or to override settings in the client.rb file:

provisioner:
  name: chef_zero *or* chef_solo
  require_chef_omnibus: true
  chef_omnibus_url: https://www.chef.io/chef/install.sh

...

suites:
  - name: config
    run_list:
    ...
    attributes:
      chef_client:
        load_gems:
          chef-handler-updated-resources:
            require_name: "chef/handler/updated_resources"
        config:
          log_level: ":debug"
          ssl_verify_mode: ":verify_peer"
          start_handlers: [{class: "SimpleReport::UpdatedResources", arguments: []}]
          report_handlers: [{class: "SimpleReport::UpdatedResources", arguments: []}]
          exception_handlers: [{class: "SimpleReport::UpdatedResources", arguments: []}]
      ohai:
        disabled_plugins: ["passwd"]

where:

  • require_chef_omnibus is used to ensure that the Chef installer will be used to install Chef Infra Client to all platform instances; require_chef_omnibus may also be set to latest, which means the newest version of Chef Infra Client for that platform will be used for cookbook testing
  • chef_omnibus_url is used to specify the URL from which Chef Infra Client is downloaded
  • All of the attributes for the config test suite contain specific client.rb settings for use with this test suite

Driver Settings

Driver-specific configuration settings may be required. Use a block similar to:

driver:
  name: driver_name
  optional_settings: values

Specific optional_settings: values may be specified.

Bento

Bento is a Chef Software project that produces base testing VirtualBox, Parallels, and VMware boxes for multiple operating systems for use with Test Kitchen. By default, Test Kitchen uses the base images provided by Bento although custom images may also be built using Hashicorp Packer.

Drivers

Test Kitchen uses a driver plugin architecture to enable Test Kitchen to test instances on cloud providers such as Amazon EC2, Google Compute Engine, and Microsoft Azure. You can also test on multiple local hypervisors, such as VMware, Hyper-V, or VirtualBox.

Note

Chef Workstation includes many common Test Kitchen drivers.

Most drivers have driver-specific configuration settings that must be added to the kitchen.yml file before Test Kitchen will be able to use that platform during cookbook testing. For information about these driver-specific settings, please refer to the driver-specific documentation.

Some popular drivers:

Driver Plugin Description
kitchen-cloudstack A driver for CloudStack.
kitchen-digitalocean A driver for DigitalOcean.
kitchen-docker A driver for Docker.
kitchen-dsc A driver for Windows PowerShell Desired State Configuration (DSC).
kitchen-ec2 A driver for Amazon EC2. This driver ships in Chef Workstation.
kitchen-google A driver for Google Compute Engine. This driver ships in Chef Workstation
kitchen-hyperv A driver for Hyper-V Server.
kitchen-openstack A driver for OpenStack.
kitchen-rackspace A driver for Rackspace.
kitchen-vagrant A driver for Vagrant. This driver ships in Chef Workstation.

kitchen-vagrant

The kitchen-vagrant driver for Kitchen generates a single Vagrantfile for each instance of Kitchen in a sandboxed directory. The kitchen-vagrant driver supports VirtualBox and VMware Fusion, requires Vagrant 1.1.0 (or higher), and is the default driver for Test Kitchen.

The following attributes are used to configure kitchen-vagrant for Chef:

Attribute Description
box Required. Use to specify the box on which Vagrant will run. Default value: computed from the platform name of the instance.
box_check_update Use to check for box updates. Default value: false.
box_url Use to specify the URL at which the configured box is located. Default value: computed from the platform name of the instance, but only when the Vagrant provider is VirtualBox- or VMware-based.
communicator Use to override the config.vm.communicator setting in Vagrant. For example, when a base box is a Microsoft Windows operating system that does not have SSH installed and enabled, Vagrant will not be able to boot without a custom Vagrant file. Default value: nil (assumes SSH is available).
customize A hash of key-value pairs that define customizations that should be made to the Vagrant virtual machine. For example: customize: memory: 1024 cpuexecutioncap: 50.
guest Use to specify the config.vm.guest setting in the default Vagrantfile.
gui Use to enable the graphical user interface for the defined platform. This is passed to the config.vm.provider setting in Vagrant, but only when the Vagrant provider is VirtualBox- or VMware-based.
network Use to specify an array of network customizations to be applied to the virtual machine. Default value: []. For example: network: - ["forwarded_port", {guest: 80, host: 8080}] - ["private_network", {ip: "192.168.33.33"}].
pre_create_command Use to run a command immediately prior to vagrant up --no-provisioner.
provider Use to specify the Vagrant provider. This value must match a provider name in Vagrant.
provision Use to provision Vagrant when the instance is created. This is useful if the operating system needs customization during provisioning. Default value: false.
ssh_key Use to specify the private key file used for SSH authentication.
synced_folders Use to specify a collection of synchronized folders on each Vagrant instance. Source paths are relative to the Kitchen root path. Default value: []. For example: synced_folders: - ["data/%{instance_name}", "/opt/instance_data"] - ["/host_path", "/vm_path", "create: true, type: :nfs"].
vagrantfile_erb Use to specify an alternate Vagrant Embedded Ruby (ERB) template to be used by this driver.
vagrantfiles An array of paths to one (or more) Vagrant files to be merged with the default Vagrant file. The paths may be absolute or relative to the kitchen.yml file.
vm_hostname Use to specify the internal hostname for the instance. This is not required when connecting to a Vagrant virtual machine. Set this to false to prevent this value from being rendered in the default Vagrantfile. Default value: computed from the platform name of the instance.

The kitchen-vagrant driver can predict the box name for Vagrant and the download URL that have been published by Chef. For example:

platforms:
- name: ubuntu-16.04
- name: ubuntu-18.04
- name: centos-7
- name: centos-8
- name: debian-10

which will generate a configuration file similar to:

platforms:
- name: ubuntu-16.04
  driver:
    box: bento/ubuntu-16.04
- name: ubuntu-18.04
  driver:
    box: bento/ubuntu-18.04
# ...

Examples

The following examples show actual kitchen.yml files used in Chef-maintained cookbooks.

Chef, Chef Workstation

The following example shows the provisioner settings needed to install Chef Workstation, and then use the version of Chef that is embedded in Chef Workstation to converge the node.

To install the latest version of Chef Workstation:

provisioner:
  ...
  chef_omnibus_install_options: -P chef-workstation
  chef_omnibus_root: /opt/chef-workstation

and to install a specific version of Chef Workstation:

provisioner:
  ...
  chef_omnibus_install_options: -P chef-workstation
  chef_omnibus_root: /opt/chef-workstation
  require_chef_omnibus: 0.9

Microsoft Windows Platform

The following example shows platform settings for the Microsoft Windows platform:

---

platforms:
  - name: eval-win2012r2-standard
    os_type: windows
    transport:
      name: winrm
      elevated: true

If name begins with win then the os_type defaults to windows. The winrm transport is the default on Windows operating systems. Here elevated is true which runs windows commands via a scheduled task to imitate a local user.

Chef Infra Client Cookbook

The following kitchen.yml file is part of the chef-client cookbook and ensures Chef Infra Client is configured correctly.

driver:
  name: vagrant

provisioner:
  name: chef_zero

platforms:
  - name: centos-8
  - name: fedora-latest
  - name: ubuntu-1604
  - name: ubuntu-1804

suites:

- name: service_init
  run_list:
  - recipe[minitest-handler]
  - recipe[chef-client::config]
  - recipe[chef-client_test::service_init]
  - recipe[chef-client::init_service]
  attributes: {}

- name: service_runit
  run_list:
  - recipe[minitest-handler]
  - recipe[runit]
  - recipe[chef-client_test::service_runit]
  - recipe[chef-client::runit_service]
  attributes: {}

- name: service_upstart
  run_list:
  - recipe[minitest-handler]
  - recipe[chef-client_test::service_upstart]
  - recipe[chef-client::upstart_service]
  excludes: ["centos-5.9"]
  attributes: {}

- name: cron
  run_list:
  - recipe[minitest-handler]
  - recipe[chef-client::cron]
  attributes: {}

- name: delete_validation
  run_list:
  - recipe[chef-client::delete_validation]
  attributes: {}

chef-splunk Cookbook

The following kitchen.yml file is part of the chef-splunk cookbook and is used to help ensure the installation of the Splunk client and server is done correctly.

driver:
  name: vagrant
  customize:
    memory: 1024

provisioner:
  name: chef_zero

platforms:
  - name: ubuntu-16.04
  - name: ubuntu-18.04
  - name: centos-7
  - name: centos-8

suites:
  - name: client
    run_list:
      - recipe[chef-splunk::default]
      - recipe[test::default]
    attributes:
      dev_mode: true
      splunk:
        accept_license: true

  - name: server
    run_list:
      - recipe[chef-splunk::default]
    attributes:
      dev_mode: true
      splunk:
        is_server: true
        accept_license: true
        ssl_options:
          enable_ssl: true

yum Cookbook

The following kitchen.yml file is part of the yum cookbook:

driver:
  name: vagrant

provisioner:
  name: chef_zero

platforms:
  - name: centos-7
  - name: centos-8
  - name: fedora-latest

suites:
  - name: default
    run_list:
      - recipe[yum::default]
      - recipe[yum_test::test_repo]

Platform Attributes

The following kitchen.yml file sets up a simple tiered configuration of the Chef Infra Server, including two front-end servers, a single back-end server, and two add-ons (Chef Push Jobs and Chef management console). The platforms block uses an attributes section to define Chef server-specific attributes that are used by all three test suites:

---
driver:
  name: vagrant

provisioner:
  name: chef_zero

platforms:
  - name: ubuntu-16.04
    attributes:
      chef-server:
        api_fqdn: backend.chef-server.com
        backend:
          fqdn: backend.chef-server.com
          ipaddress: 123.456.789.0
        frontends:
          frontend1.chef-server.com: 123.456.789.0
          frontend2.chef-server.com: 123.456.789.0
        urls:
          private_chef: http://123.456.789.0/path/to/private-chef_11.1.4-1_amd64.deb
          manage: http://123.456.789.0/path/to/opscode-manage_1.3.1-1_amd64.deb
          push_jobs: http://123.456.789.0/path/to/opscode-push-jobs-server_1.1.1-1_amd64.deb

suites:
  - name: frontend1
    driver:
      vm_hostname: frontend1.chef-server.com
      network:
      - ["private_network", {ip: "123.456.789.0"}]
      customize:
        memory: 2048
        cpus: 2
    run_list:
      - recipe[chef-server::configfile]
      - recipe[chef-server::ntp]
      - recipe[chef-server::server]
      - recipe[chef-server::frontend]
  - name: frontend2
    driver:
      vm_hostname: frontend2.chef-server.com
      network:
      - ["private_network", {ip: "123.456.789.0"}]
      customize:
        memory: 2048
        cpus: 2
    run_list:
      - recipe[chef-server::configfile]
      - recipe[chef-server::ntp]
      - recipe[chef-server::server]
      - recipe[chef-server::frontend]
  - name: backend
    driver:
      vm_hostname: backend.chef-server.com
      network:
      - ["private_network", {ip: "123.456.789.0"}]
      customize:
        memory: 8192
        cpus: 4
    run_list:
      - recipe[chef-server::configfile]
      - recipe[chef-server::ntp]
      - recipe[chef-server::server]
      - recipe[chef-server::backend]

Kitchen Converge On System Reboot

Test-Kitchen can handle reboots (when initiated from Chef Infra Client) by setting retry_on_exit_code, max_retries and wait_for_retry attributes on the provisioner in kitchen.yml file as follows :

---
provisioner:
   name: chef_zero
   retry_on_exit_code:
     - 35 # 35 is the exit code signaling that the node is rebooting
     - 1
   max_retries: 1
   client_rb:
     exit_status: :enabled # Opt-in to the standardized exit codes
     client_fork: false  # Forked instances don't return the real exit code

One note on linux nodes: The shutdown command blocks (as opposed to the windows variant which registers the reboot and returns right away), so once the timeout period passes, Chef Infra Client and the node are in a race to see who can exit/shutdown first - so you may or may not get the exit code out of linux instances. In that case, you can add 1 to the retry_on_exit_code array and that should catch both cases.

Please refer YAML documentation to set retry_on_exit_code attribute.