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 67
  • Debian 89
  • 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 configurables 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'

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:
── documentation
│   ├──
│   ├──
│   ├──
│   ├──
│   ├──
│   ├──
│   └──
  • The 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