Collaborative community of Chef practitioners dedicated to improving the quality of cookbooks

Sous-Chefs Cookbook Best Practises

· by Dan Webb · Read in about 2 min · (215 Words)

Cookbook Best Practices

If we’re adopting a cookbook and trying to bring it up to scratch, these are likely the first things people will expect.

Platform Support

The majority of our survey userbase uses the following and as such as aim to support these platforms by default:

  • Centos 6/7
  • Debian 8/9
  • Ubuntu 16.04/18.04
  • Amazon 1 and 2

Custom Resources over Attribute Driven

Our cookbooks are application cookbooks, and therefore designed to only manage a single type of application at a time. For example, a PostgreSQL server.

All configurablebles should be surfaced through a easy to understand, custom resource interface.

For example the postgresql_client_install resource, surfaces a version atrribute. Which is obvious to the user. Much like a template, or file resource.

postgresql_client_install 'Client install' do
  version '9.5'
end

Resource Documentation

README docuemntation can get very long and hard to navigate. Splitting information down into easily digestable information is crucial in users being able to effectively use the cookbook.

Example structure:

README.md
── documentation
│   ├── resource_apache2_conf.md
│   ├── resource_apache2_config.md
│   ├── resource_apache2_default_site.md
│   ├── resource_apache2_install.md
│   ├── resource_apache2_mod.md
│   ├── resource_apache2_module.md
│   └── resource_apache2_site.md
  • The README.md should have links to both resource documents
  • The resource documentation should have the following headings:
    • resource title
    • a table of available properties
    • a set of examples using the resource

Comments