Hello!

chef-standards

Prior art
===========

Cookbook style guides
---------------------
* https://github.com/ampledata/cookbook-style-guide
* https://github.com/infochimps-labs/ironfan/wiki/style_guide
* https://github.com/secondmarket/chef-style-guide
* http://acrmp.github.io/foodcritic/


Cookbook testing tutorials
---------------------------
* https://micgo.net/automating-cookbook-testing-with-test-kitchen-berkshelf-vagrant-and-guard/


Testing tools
-------------
* https://github.com/sethvargo/chefspec
* http://kitchen.ci/
* http://serverspec.org/
* http://leopard.in.ua/2013/12/01/chef-and-tdd/

Tutorials
--------------
* https://sethvargo.com/berkshelf-workflow/  How to use berkshelf
* http://dougireton.com/blog/2012/12/31/creating-an-lwrp/ How to do basic LWRP
* http://dougireton.com/blog/2013/01/07/creating-an-lwrp-part-2/ How to write a better lwrp
* http://dougireton.com/blog/2013/03/17/a-knife-dot-rb-for-our-time/ How to write a knife.rb
* http://dougireton.com/blog/2013/02/16/chef-cookbook-anti-patterns/ Ways to make your cookbook terrible (please read, not following these patterns will help us lots)

How to evaluate community cookbooks
-----------------------------------
* http://www.slideshare.net/JulianDunn/what-makes-a-good-cookbook?related=1

ChefSpec Examples
---------------
* https://github.com/aespinosa/cookbook-nginx/blob/definition-testing/spec/default_spec.rb


Getting Started
================

Your Local Environment
----------------------
A few important places:
* `~/.chef` This is where you should put all of your .pem files for the orgs that your are working on, and all of your validators.


Cookbook standards
==================

To increse the quality and maintainability of our platform the PAAS team has put together some basic requirements for a cookbook before it can go to production.


Chef-Data-Repo
==============
A chef-data repo has the following items:
* roles
* environments
* databags
** And scripts to get secrets that have to be in them
* Berksfile
** This should refer to all of the cookbooks needed to deploy the application
* deployment tools
** Preferably in /bin
* README.md
** Should describe of the operations and setup information needed to maintain the application
Its purpose in life is to act as a center of operations activities.
* .chef folder for configuring knife.
* `.chef/knife.rb` In this style

Cookbook Kinds
==============

* Library cookbook, These cookbook contain LWRPs that can be used in other cookbooks
https://github.com/bflad/chef-docker
https://github.com/opscode-cookbooks/yum

* Application cookbook, These cookbooks deploy some sort of applition
https://github.com/opscode-cookbooks/jenkins

* Integration cookbook, Takes some set of cookbooks and composes them into a easy tool to deploy.


All Cookbooks
========

Things that make life better
---------------------------

* https://github.com/sethvargo/chef-sugar for making cookbooks DRYer
* https://github.com/sethvargo/chef-api   for interacting with chef server
* https://github.com/sethvargo/knife-spec for scaffolding specs


Basics
------
* Chef execution Must be tested (using chefspec)
** To qualify as tested the cookbook must have over 90% test coverage. While normally I would discourage using code coverage as a testing metric in the case of chef cookbooks it is reasonable to require that they be concise enough that it is reasonable to shoot for high code coverage.
* All assumptions about how the cookbook affects the environment must be tested in severspecs
* Cookbooks dependencies much be resolved using berkshelf
** Furthermore, `berks install && berks upload` must work.
* Any part of the cookbook which are consumable by multiple products needs to be encoded as a lwrp.
** For example, in the play20 cookbook for dps we use a LWRP for the creation of a play app, hopefully so that we can reuse this code. But with out the redirection of control that an lwrp provides we will not be able to accomplish this.
* A metadata.rb that names the maintainer (or team), the cookbook, has a semantic version number, all depends, and the platforms it can run on.
* Minimize dependence on chef-server, if possible use orchestration tools instead (consul, etcd)


For CI/CD
------
* `kitchen test` must run and must return 0 (on success)
* `rspec test` (chefspec) must run and must return 0 (on success)
* `foodcritic` must run and must return no critiques
* A gem file to install of the the ruby tool needed to execute the cookbook

Bonus
-----
* `bundle exec guard start` starts a watcher that will run correct tests for changed files


Other things
------------
If you choose to consume a community cookbook it also needs to follow everything except the serverspec requirements.

When you a fork a community cookbook it needs to be forked to the shared autodesk org on github.com (so that we can contribute back to the community) or into the chef-shared org on our internal github. After it is forked it needs to be assigned a maintainer who will continue to own the cookbook and review any pull requests that are made to it.

Please always look here before you fork the same cookbook again.

If the forked cookbook is not in a state where it is compliant with all of the policies we have it must be updated to do so before it is deployed to production.

In general if you create a cookbook it needs to be able to run on the two most recent versions of centos.