kitchen.yml

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

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-20.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 simple kitchen.yml file:

driver:
  name: vagrant

provisioner:
  name: chef_zero

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

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

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

Provisioner Settings

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

client_rb:
  log_level: :warn

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

Transport Settings

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

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

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

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
• 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

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.

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:

kitchen-vagrant

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

box

The box on which Vagrant will run.

Default value: computed from the platform name of the instance.

Required

box_check_update

Whether to check for box updates.

Default value: false.

box_url

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 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.

Example: customize: memory: 1024 cpuexecutioncap: 50.

guest

The config.vm.guest setting in the default Vagrantfile.

gui

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

An array of network customizations to be applied to the virtual machine.

Example: network: - ["forwarded_port", {guest: 80, host: 8080}] - ["private_network", {ip: "192.168.33.33"}].

Default value: [].

pre_create_command

A command to run immediately before vagrant up --no-provisioner.

provider

The Vagrant provider. This value must match a provider name in Vagrant.

provision

Whether to provision Vagrant when the instance is created. This is useful if the operating system needs customization during provisioning.

Default value: false.

ssh_key

The private key file used for SSH authentication.

synced_folders

The collection of synchronized folders on each Vagrant instance. Source paths are relative to the Kitchen root path.

Example: synced_folders: - ["data/%{instance_name}", "/opt/instance_data"] - ["/host_path", "/vm_path", "create: true, type: :nfs"].

Default value: [].

vagrantfile_erb

The 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

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-18.04
- name: ubuntu-20.04
- name: centos-7
- name: centos-8
- name: debian-10

which will generate a configuration file similar to:

platforms:
- name: ubuntu-18.04
  driver:
    box: bento/ubuntu-18.04
- name: ubuntu-20.04
  driver:
    box: bento/ubuntu-20.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

Windows Platform

The following example shows platform settings for the 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-1804
  - name: ubuntu-2004

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-18.04
  - name: ubuntu-20.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 Infra Server attributes that are used by all three test suites:

driver:
  name: vagrant

provisioner:
  name: chef_zero

platforms:
  - name: ubuntu-18.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.