What makes a good Chef cookbook?

1. What Makes a Good
Cookbook?
Julian C. Dunn
Senior Consultant
Chef Software, Inc.
<jdunn@getchef.com>

2. Finding a Good Cookbook

4. Do judge a cookbook by its cover

9. Too Clever for Its Own Good
missing_attrs = %w{
postgres
}.select do |attr|
node['postgresql']['password'][attr].nil?
end.map { |attr| "node['postgresql']['password']['#{attr}']" }
if !missing_attrs.empty?
Chef::Application.fatal!([
"You must set #{missing_attrs.join(', ')} in chef-solo mode.",
"For more information, see
https://github.com/opscode-cookbooks/postgresql#chef-solo-note"
].join(' '))
end

10. Poking at Chef Internals
Chef::Application.fatal!([
"You must set #{missing_attrs.join(', ')} in chef-solo mode.",
"For more information, see
https://github.com/opscode-cookbooks/postgresql#chef-solo-note"
].join(' '))
• Other abuses: Messing with run_context and
run_state

11. Compile vs. Execute Errors
template "/etc/whatever.conf" do
...
not_if { foo }
end
not the same thing as
if foo
template "/etc/whatever.conf" do
...
end
end

12. Not declarative
execute “yum install httpd” do
not_if “rpm -qa | grep -x httpd”
end
• Also, the Chef recipe with 100 bash resource
declarations

13. Missing guards
execute "I will run every time" do
action :run
# because I don't have a guard here
end

14. Fear of LWRPs
• Missed abstraction opportunities
• No good example to put here; they’re all 200 lines
long (thus proving my point)

15. Hardcoded Strings
remote_file 'whatever.tar.gz' do
source 'http://hardcoded.url.com/’
end

16. Excess Conditions & Recipe Length
• https://github.com/opscode-cookbooks/mysql/blob/v3.0.1
• (We’ve since refactored this)

17. Good Cookbooks...

18. Put control flow in attributes
• Especially for cross-platform cookbooks
• Set common set of attributes, write common
behavior in recipe context

19. Control Flow in Attributes
case node['platform']
when "debian", "ubuntu"
default['postgresql']['client']['packages'] = %w{postgresql-client libpq-dev}
default['postgresql']['server']['packages'] = %w{postgresql}
default['postgresql']['contrib']['packages'] = %w{postgresql-contrib}
when "fedora", "amazon"
default['postgresql']['client']['packages'] = %w{postgresql-devel}
default['postgresql']['server']['packages'] = %w{postgresql-server}
default['postgresql']['contrib']['packages'] = %w{postgresql-contrib}
default['postgresql']['server']['service_name'] = "postgresql"
when "redhat", "centos", "scientific", "oracle"
default['postgresql']['version'] = "8.4"
default['postgresql']['dir'] = "/var/lib/pgsql/data"
if node['platform_version'].to_f >= 6.0
default['postgresql']['client']['packages'] = %w{postgresql-devel}
default['postgresql']['server']['packages'] = %w{postgresql-server}
default['postgresql']['contrib']['packages'] = %w{postgresql-contrib}
else
default['postgresql']['client']['packages'] = ["postgresql#{node['postgresql']['version'].split('.').join}-devel"]
default['postgresql']['server']['packages'] = ["postgresql#{node['postgresql']['version'].split('.').join}-server"]
default['postgresql']['contrib']['packages'] = ["postgresql#{node['postgresql']['version'].split('.').join}-contrib"]
end
default['postgresql']['server']['service_name'] = "postgresql"

20. Common Recipe Code
node['postgresql']['server']['packages'].each do |pg_pack|
package pg_pack
end
• Easy to support more platforms without modifying
recipe

21. Separate recipes by OS
• If things you do are very different per platform,
separate them into different recipes
default.rb
default.rb
server.rb
server.rb
_windows.rb
_windows.rb
_fedora.rb
_fedora.rb
_suse.rb
_suse.rb

22. “Public” versus “Private” recipes
• ‘_’ faux-namespacing

23. Do not abuse compile-time
loaded_recipes = if run_context.respond_to?(:loaded_recipes)
run_context.loaded_recipes
else
node.run_state[:seen_recipes]
end
node['mysql']['client']['packages'].each do |name|
resources("package[#{name}]").run_action(:install)
end
•.run_action(:must_die)
• Use sparingly, if at all!

24. Avoid poking Chef Internals
if some_error_condition
fail "Helpful error message"
# rather than Chef::Application.fatal!("error")
end
• Chef::Application.fatal is for use by Chef
itself
• fail or raise is better

25. Attributes only where necessary
• “Let’s create a node attribute for each of the 15,000
tunables in this daemon”
• Not necessary if you never touch 14,975 of those
knobs

26. Give people options for installation
git clone
git://github.com/foozolix/foozolix.git./configuremak
emake install
• Sigh.
• At least give people a way to install from packages.
• “Compile from source” should be banned in most cases.

27. Be declarative
• Know and use built-in Chef resources
• Know where to find LWRPs to avoid
batch/execute/powershell_script
• Consider using log resource versus Chef::Log
• Shows up in reporting as an updated resource instead of having to trawl
through client.log
• Set an idempotency guard!
• Log at the right log level

28. Repetition == LWRP Candidate
node['jboss']['instances'].each do |instance|
link "/etc/init.d/#{instance['name']}" do
to "/etc/init.d/jbossas"
end
template "/etc/sysconfig/#{instance['name']}" do
source "jbossas.sysconfig.erb"
owner node['jboss']['server']['user']
group node['jboss']['server']['group']
mode "00644"
variables(
:jbossconf => instance['name']
)
action :create
end
template "#{node['jboss']['server']['home']}/bin/standalone.sh" do
source "standalone.sh.erb"
owner node['jboss']['server']['user']
group node['jboss']['server']['group']
mode "00755"
action :create
end
link "#{node['jboss']['server']['home']}/bin/#{instance['name']}.sh" do
to "#{node['jboss']['server']['home']}/bin/standalone.sh"
end
end

29. Repetition == LWRP Candidate
• Perfect for abstracting!
• Resource interface:
actions :create, :delete
attribute :instance_name, :kind_of => String, :name_attribute => true
attribute :console_log_level, :kind_of => String, :required => true
attribute :datasources, :kind_of => Hash, :default => {}
.
.
.
default_action :create

30. Repetition == LWRP Candidate
jboss_instance "petstore" do
instance_name "can_haz_cheezburgerz"
console_log_level "DEBUG"
datasources {'db1' => 'jdbc://whatever:5432/db1'}
end
• Write/debug hard logic once
• Clear consumer interface
• Parameter validation & sanity checking
• Non-JBoss experts can invoke without knowing gnarly details

31. Write helper libraries
module MyCookbook
module Helper
# returns Windows friendly version of the provided path,
# ensures backslashes are used everywhere
def win_friendly_path(path)
path.gsub(::File::SEPARATOR, ::File::ALT_SEPARATOR) if path
end
end
end
• Create reusable helper functions in pure Ruby
• Move repetitive detail out of recipe context.

32. Keep Recipes Small
• < 100 lines
• If longer than this, consider breaking up functionality
• Example: nagios server recipe does too much
• Installs Nagios
• Configures Nagios
• Pokes around in data bags for config items

33. Use Community Helpers
• Chef Sugar - http://code.sethvargo.com/chef-sugar/
• Chef Cutlery https://github.com/realityforge/chef-cutlery
• You can also crib ideas if you want to avoid external
dependencies

34. Wrap-Up

35. Testing
• I didn’t mention testing once in this talk!
• I’m assuming you will write tests for your cookbooks.
• A whole other talk...
• ... including good/bad things to test

36. Make your code aromatic
• Keep recipes small
• Keep recipes simple
• Use a consistent style
• Use Foodcritic

37. Beware Expertise Bias
• Hide gnarly details from recipe context
• Libraries
• LWRPs
• Attributes
• Resist urge to be overly clever - not everyone’s an expert
• Akin to the one-line sed/awk script
• http://tinyurl.com/the-expertise-bias

38. Learn from Software Developers
• Everything I told you about information hiding, design
patterns, testing, etc.
• Ops can learn from devs as well!
• Maybe we should call it OpsDev...

39. Thank You!
E: jdunn@getchef.com
G: https://github.com/juliandunn
T: @julian_dunn
W: www.juliandunn.net