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