"Anyone can cook."

Build Status Coverage Status Gem Version

Gusteau is an easy to use configuration manager for Chef Solo and Vagrant. It aims to:

  • Provide existing Chef Solo users with a more efficient workflow
  • Make Chef Solo usable for a small to mid scale multi-node setup
  • Make Chef Solo more accessible for the new users

Some of the features include:

  • YAML for readable, flexible infrastructure configuration
  • Usage of a single SSH connection to stream compressed files and commands
  • Support for normal Chef CLI flags:
    • -W or --why-run (dry run mode)
    • -l for setting a log level and -F for setting an output formatter
  • Bootstrapping target systems with Chef-Omnibus or custom scripts.

Getting started

Gusteau is a Ruby gem:

gem install gusteau

The following command generates an example Chef-repo:

gusteau init project-name

Make sure you read through project-name/ first.

A typical .gusteau.yml looks like this:

  - bundle exec berks install --path ./cookbooks

        server_root_password: ASahiweqwqe2
        default_ruby: 1.9.3-p362
       - linguini

      - role[base]
      - recipe[mysql::server]
      - recipe[iptables]

        password: omgsecret

Converging a server

The following command will run the whole run_list on the node.

gusteau converge development-playground

Use the --bootstrap or -b flag to bootstrap chef-solo (e.g. during the first run).

Applying individual recipes

You may choose to run a custom run_list instead of the full convergence.

gusteau apply development-playground "role[base],recipe[oh-my-zsh]"


Gusteau provides a useful shortcut that you may use to ssh into a node. If you haven't got passwordless authentication set up, Gusteau will use user and password values from the node configuration.

gusteau ssh development-playground

Please note that expect utility must be installed for gusteau ssh to work.

If you prefer calling ssh directly, you will find the gusteau ssh_config subcommand useful:

gusteau ssh_config >> ~/.ssh/config

Vagrant Plugin

Gusteau can save you from writing some Vagrantfile boilerplate code. It enables you to move node specific Vagrant configuration away from the Vagrantfile into node definitions. The Vagrant plugin for Gusteau means you can then bring up this node in VirtualBox.

        cpus: 1
        memory: 512
        box_url: ''

The following snippet in the Vagrantfile configures Vagrant for all nodes (as above) listed in Gusteau which have vagrant sections defined.

Vagrant.configure('2') do |config|
  Gusteau::Vagrant.detect(config) do |setup|
    setup.prefix = 'loco'
    setup.defaults.box_url = ''
  • The prefix option lets you prepend your VirtualBox VMs names, e.g. loco-nodename.
  • The defaults one lets you provide default values for cpus, memory, box_url, box.

Please note that the add-on only works with Vagrant ~> 1.2 and needs Gusteau to be installed as a Vagrant plugin:

vagrant plugin install gusteau

Once the Gusteau plugin for Vagrant is installed you can start up VirtualBox using the environment and node data for vagrant in .gusteau.yml:

vagrant up development-www


Before and after hooks

You can tell Gusteau to execute specific commands before and / or after converge or apply take place. They get executed on the host system. Example .gusteau.yml snippet:

  - bundle exec librarian-chef install

  - bundle exec rake spec


In addition to specifying attributes for environments you can set node-specifc ones. They will be deep-merged with environment ones:

      hostname: staging
        attributes: { hostname: staging-one }
        attributes: { hostname: staging-two }

Run lists

You can also override run_list for specific nodes.

Bootstrap script

By default, Gusteau installs the Omnibus Chef 11.4.4. You can also set the Omnibus Chef version explicitly by specifying it in .gusteau.yml:

chef_version: 10.26.0

If you're targeting a non Omnibus-supported platform you might want to specify the platform value for a node: this invokes a specific script.

Alternatively, you can specify a custom script in .gusteau.yml:

bootstrap: ./scripts/

Custom cookbooks path

By default, Gusteau uploads and sets Chef Solo up to use cookbooks from ./cookbooks and ./site-cookbooks directories. If it doesn't work for you, you can override these values in .gusteau.yml:

cookbooks_path: [ './my-cookbooks', '../something-else' ]
roles_path: './base-roles'

Custom Chef run configuration directory (e.g. /etc/chef)

By default, Gusteau uploads the necessary files and folders (i.e. cookbooks and roles directories) to /etc/chef/.

You can specify a custom target directory in .gusteau.yml:

chef_config_dir: /etc/custom_chef_dir