A lint tool for your Opscode Chef cookbooks.
Foodcritic has two goals:
To make it easier to flag problems in your Chef cookbooks that will cause Chef to blow up when you attempt to converge. This is about faster feedback. If you automate checks for common problems you can save a lot of time.
To encourage discussion within the Chef community on the more subjective stuff - what does a good cookbook look like? Opscode have avoided being overly prescriptive which by and large I think is a good thing. Having a set of rules to base discussion on helps drive out what we as a community think is good style.
Foodcritic runs on Ruby (MRI) 1.9.2+ which depending on your workstation setup may be a more recent version of Ruby than you have installed. The Ruby Version Manager (RVM) is a popular choice for running multiple versions of ruby on the same workstation, so you can try foodcritic out without running the risk of damaging your main install.
RVM can be installed from the current development code on the projects GitHub - however if you are just getting started with RVM I would recommend installing the latest stable version with the stable argument. The full instructions for installing RVM can be found here:
See also this blog post from Michal Papis for more information:
With RVM installed successfully you can now use it to install MRI 1.9.3:
$ rvm install ruby-1.9.3Ok - now we can move on to installing foodcritic itself. Foodcritic is distributed as a Rubygem - run the following commands to install it:
$ rvm use 1.9.3
$ gem install foodcriticGreat - that’s it. You should now find you have a foodcritic command on your PATH. Run foodcritic to see what arguments it supports:
foodcritic [cookbook_path]
-r, --[no-]repl Drop into a REPL for interactive rule editing.
-t, --tags TAGS Only check against rules with the specified tags.
-f, --epic-fail TAGS Fail the build if any of the specified tags are matched.
-C, --[no-]context Show lines matched against rather than the default summary.
-I, --include PATH Additional rule file path(s) to load.
-S, --search-grammar PATH Specify grammar to use when validating search syntax.
-V, --version Display version.Now for the fun part. Try running it against your favourite cookbook.
style
attributes
Applies to Chef versions: >= 0.7.12
This rule has been deprecated. See the discussion against issue #86 for more detail.
style
strings
When you declare a resource in your recipes you frequently want to reference dynamic values such as node attributes. This warning will be shown if you are unnecessarily wrapping an attribute reference in a string.
This example would match the FC002 rule because the version attribute has been unnecessarily quoted.
This modified example would not match the FC002 rule:
# Don't do this
package "mysql-server" do
version "#{node['mysql']['version']}"
action :install
end
package "mysql-server" do
version node['mysql']['version']
action :install
end
portability
solo
Chef Server extends the feature-set of a Chef deployment and is probably the most popular configuration. It is also possible to run the Chef client in a standalone mode with Chef Solo. Where your cookbooks make use of features that only exist in a Chef Server based setup you should check whether you are running in solo mode.
This example would match the FC003 rule because it does not check if it is running in Chef Solo before using search which is a server-specific feature.
This modified example would not match the FC003 rule:
nodes = search(:node, "hostname:[* TO *] AND chef_environment:#{node.chef_environment}")
if Chef::Config[:solo]
Chef::Log.warn("This recipe uses search. Chef Solo does not support search.")
else
nodes = search(:node, "hostname:[* TO *] AND chef_environment:#{node.chef_environment}")
end
style
services
This warning is shown if you are starting or stopping a service using the Chef execute resource rather than the more idiomatic service resource. You can read more about the service resource here:
This example would match the FC004 rule because it uses execute for service control. There is no reason to use execute because the service resource exposes the start_command attribute to give you full control over the command issued.
This modified example would not match the FC004 rule:
# Don't do this
execute "start-tomcat" do
command "/etc/init.d/tomcat6 start"
action :run
end
service "tomcat" do
action :start
end
style
When writing Chef recipes you have the full power of Ruby at your disposal. One of the cases where this is helpful is where you need to declare a large number of resources that only differ in a single attribute - the canonical example is installing a long list of packages.
This example matches the FC005 rule because all the resources of type package differ only in a single attribute - the name of the package to be upgraded. This rule is very simple and looks only for resources that all differ in only a single attribute. For example - if only one of the packages specified the version then this rule would not match.
This modified example would not match the FC005 rule. It takes advantage of the fact that Chef processes recipes in two distinct phases:
Don’t worry about changing your recipe if it already does what you want - the amount of Ruby syntactic sugar to apply is very much a matter of personal taste. Note that this rule also isn’t clever enough yet to detect if your resources are wrapped in a control structure and not suitable for ‘rolling up’ into a loop.
# You could do this
package "erlang-base" do
action :upgrade
end
package "erlang-corba" do
action :upgrade
end
package "erlang-crypto" do
action :upgrade
end
package "rabbitmq-server" do
action :upgrade
end
# It's shorter to do this
%w{erlang-base erlang-corba erlang-crypto rabbitmq-server}.each do |pkg|
package pkg do
action :upgrade
end
end
correctness
files
When setting file or directory permissions via the mode attribute you should either quote the octal number or ensure it is specified to five digits. Otherwise the permissions that are set after Ruby coerces the number may not match what you expect.
These modified examples would not match the FC006 rule:
# Don't do this
directory "/var/lib/foo" do
owner "root"
group "root"
mode 644
action :create
end
# This is ok
directory "/var/lib/foo" do
owner "root"
group "root"
mode "644"
action :create
end
# And so is this
directory "/var/lib/foo" do
owner "root"
group "root"
mode 00644
action :create
end
correctness
metadata
This warning is shown when you include a recipe that is not in the current cookbook and not defined as a dependency in your cookbook metadata. This is potentially a big problem because things will blow up if the necessary dependency cannot be found when Chef tries to converge your node. For more information refer to the Chef wiki metadata page:
The fix is to declare the cookbook of the recipe you are including as a dependency in your metadata.rb file.
You may also see this warning if foodcritic has not been able to infer the name of your cookbook correctly when the cookbook directory does not match the name of the cookbook specified in the include.
Assuming you have a recipe that had the following line:
Then to remove this warning you would add the apache2 cookbook as a dependency to your own cookbook metadata in the metadata.rb file at the root of your cookbook.
include_recipe "apache2::default"
depends "apache2"
style
metadata
This warning is shown if you used knife cookbook create to create a new cookbook and didn’t override the maintainer and maintainer email. You need to set these to real values in metadata.rb or run knife again with the real values.
This modified example would not match the FC008 rule:
# Don't do this
maintainer "YOUR_COMPANY_NAME"
maintainer_email "YOUR_EMAIL"
license "All rights reserved"
description "Installs/Configures example"
long_description IO.read(File.join(File.dirname(__FILE__), 'README.rdoc'))
version "0.0.1"
maintainer "Example Ltd"
maintainer_email "postmaster@example.com"
license "All rights reserved"
description "Installs/Configures example"
long_description IO.read(File.join(File.dirname(__FILE__), 'README.rdoc'))
version "0.0.1"
correctness
This warning is likely to mean that your recipe will fail to run when you attempt to converge. Your recipe may be syntactically valid Ruby, but the attribute you have attempted to set on a built-in Chef resource is not recognised. This is commonly a typo or you need to check the documentation to see what the attribute you are trying to set is called:
This example matches the FC009 rule because punter is not a recognised attribute for the file resource.
Checking the documentation we can see the correct attribute is owner.
# Don't do this
file "/tmp/something" do
punter "root"
group "root"
mode "0755"
action :create
end
file "/tmp/something" do
owner "root"
group "root"
mode "0755"
action :create
end
correctness
search
The search syntax used is not recognised as valid Lucene search criteria. This is commonly because you have made a typo or are not escaping special characters in the query syntax.
Note that this rule will not identify syntax errors in searches composed of subexpressions. It checks only for literal search strings.
This example matches the FC010 rule because search metacharacters - in this case the square brackets - have not been properly escaped.
With the characters escaped this will no longer match the rule.
# Don't do this
search(:node, 'run_list:recipe[foo::bar]') do |matching_node|
puts matching_node.to_s
end
search(:node, 'run_list:recipe\[foo\:\:bar\]') do |matching_node|
puts matching_node.to_s
end
style
readme
The Opscode Community site will now render your cookbook README documentation inline - see this example for the mysql cookbook.
Your README needs to be in Markdown format for this to work. This rule will match any cookbook that does not have a README.md file in the root directory.
style
readme
Writing cookbook documentation in RDoc has been deprecated in favour of Markdown format. This rule will match any cookbook that has a README.rdoc file in the root directory.
style
files
This warning means that you have hard-coded a file download path in your cookbook to a temporary directory. This can be a problem on boxes built with a small /tmp mount point. Chef has its own configuration option file_cache_path you should use instead:
This example matches the FC013 rule because it hard-codes the download path to /tmp.
To remove this warning use the configured file_cache_path:
# Don't do this
remote_file "/tmp/large-file.tar.gz" do
source "http://www.example.org/large-file.tar.gz"
end
remote_file "#{Chef::Config[:file_cache_path]}/large-file.tar.gz" do
source "http://www.example.org/large-file.tar.gz"
end
style
libraries
Your cookbook has a fairly long ruby_block resource. Long ruby_block resources are often candidates for extraction to a separate module or class under the libraries directory.
style
definitions
lwrp
Chef definitions are an older approach to creating a higher-level abstraction for a group of resources. Unlike LWRPs they are not first class resources and cannot receive notifications. You should prefer LWRPs for new development.
correctness
lwrp
Applies to Chef versions: >= 0.7.12
This warning means that the LWRP does not declare a default action. You should normally define a default action on your resource to avoid confusing users. Most resources have an intuitive default action.
This example matches the FC016 rule because it does not declare a default action.
With a default action specified this warning will no longer be displayed.
# Don't do this
actions :create
actions :create
# Chef 0.10.10 or greater
default_action :create
# In earlier versions of Chef the LWRP DSL doesn't support specifying
# a default action, so you need to drop into Ruby.
def initialize(*args)
super
@action = :create
end
correctness
lwrp
Applies to Chef versions: >= 0.7.12
This warning means that the LWRP will not currently trigger notifications to other resources. This can be a source of difficult to track down bugs.
This example matches the FC017 rule because it does not mark that its state has changed and will therefore not send notifications.
The call to updated_by_last_action ensures that notifications will work correctly.
# Don't do this
action :create do
# create action implementation
end
action :create do
# create action implementation
# My state has changed so I'd better notify observers
new_resource.updated_by_last_action(true)
end
style
lwrp
deprecated
Applies to Chef versions: >= 0.9.10
This example matches the FC018 rule because it uses the old syntax for indicating it has been updated.
This example uses the newer syntax and will not raise the warning.
# Don't do this
action :create do
# create action implementation
# My state has changed so I'd better notify observers, but I'm using
# a deprecated syntax
new_resource.updated = true
end
# Also don't do this
action :create do
# create action implementation
# My state has changed so I'd better notify observers, but I'm using
# a deprecated syntax
@updated = true
end
action :create do
# create action implementation
# My state has changed so I'd better notify observers
new_resource.updated_by_last_action(true)
end
style
attributes
Node attributes can be accessed in multiple ways in Chef. This warning is shown when a cookbook is not consistent in the approach it uses to access attributes. It is not displayed for variations between cookbooks.
# Don't do this
node[:apache][:dir] = '/etc/apache2'
directory node['apache']['dir'] do
owner 'apache'
group 'apache'
action :create
end
node['apache']['dir'] = '/etc/apache2'
directory node['apache']['dir'] do
owner 'apache'
group 'apache'
action :create
end
correctness
This rule has been deprecated due to the frequency of false positives. See the discussion against issue #30 for more detail.
correctness
lwrp
Applies to Chef versions: >= 0.10.6
A change introduced in Chef 0.10.6 means that conditions may not work as expected for resources redeclared with the same name. If your LWRP defines a resource and that resource:
Then you will likely find that only the first resource will be applied. See this ticket for more background:
Because the feed_pet resource will have the same name across all instances of your LWRP, the condition will only be checked for the first resource.
By making the resource name change for each unique instance of our LWRP instance we avoid this behaviour.
# Don't do this
action :feed do
execute "feed_pet" do
command "echo 'Feeding: #{new_resource.name}'; touch '/tmp/#{new_resource.name}'"
not_if { ::File.exists?("/tmp/#{new_resource.name}")}
end
end
action :feed do
execute "feed_pet_#{new_resource.name}" do
command "echo 'Feeding: #{new_resource.name}'; touch '/tmp/#{new_resource.name}'"
not_if { ::File.exists?("/tmp/#{new_resource.name}")}
end
end
correctness
Applies to Chef versions: >= 0.10.6
A change introduced in Chef 0.10.6 means that conditions may not work as expected for resources declared within a loop. If your recipe defines a resource and that resource:
Then you will likely find that only the first resource will be applied. See this ticket for more background:
Because the feed_pet resource will have the same name for every iteration of the loop, the condition will only be checked for the first resource.
By making the resource name change for each iteration of the loop we avoid this behaviour.
# Don't do this
%w{rover fido}.each do |pet_name|
execute "feed_pet" do
command "echo 'Feeding: #{pet_name}'; touch '/tmp/#{pet_name}'"
not_if { ::File.exists?("/tmp/#{pet_name}")}
end
end
%w{rover fido}.each do |pet_name|
execute "feed_pet_#{pet_name}" do
command "echo 'Feeding: #{pet_name}'; touch '/tmp/#{pet_name}'"
not_if { ::File.exists?("/tmp/#{pet_name}")}
end
end
style
This warning means you have surrounded a resource with an if or unless rather than defining the condition directly on the resource itself. Note that this warning is only raised for single resources as you could reasonably enclose multiple resources in a condition like this for brevity.
Jay Feldblum has expressed criticism of this rule because the effect is that resources are defined unnecessarily and ignored only at run-time. His view is that it is cleaner to use standard Ruby conditionals to avoid defining them in the first place.
This example matches the FC023 rule because it encloses a rule within a condition, rather than using the built-in Chef not_if or only_if conditional execution attributes.
You can avoid the warning above with more idiomatic Chef that specifies the condition above as an attribute on the resource:
# Don't do this
if node['foo'] == 'bar'
service "apache" do
action :enable
end
end
service "apache" do
action :enable
only_if { node['foo'] == 'bar' }
end
portability
This warning is shown when:
If you are using Ohai 0.6.12 or greater you should probably use platform_family instead. Otherwise for the greatest portability consider adding the missing platforms to your conditional.
This example matches the FC024 rule because it includes a case statement that matches more than one flavour of a platform family but omits other popular flavours from the same family.
This warning is no longer raised when the other common equivalent RHEL-based distributions have been added to the when.
# The RHEL platforms branch below omits popular distributions
# including Amazon Linux.
case node[:platform]
when "debian", "ubuntu"
package "foo" do
action :install
end
when "centos", "redhat"
package "bar" do
action :install
end
end
end
case node[:platform]
when "debian", "ubuntu"
package "foo" do
action :install
end
when "centos", "redhat", "amazon", "scientific"
package "bar" do
action :install
end
end
style
deprecated
Applies to Chef versions: >= 0.10.10
This warning is shown if:
chef_gem resource.This example matches the FC025 rule because it uses the older approach for installing a gem so that it is available in the current run.
Use chef_gem to install the gem to avoid this warning.
r = gem_package "mysql" do
action :nothing
end
r.run_action(:install)
Gem.clear_paths
chef_gem "mysql"
correctness
Applies to Chef versions: >= 0.7.4
This warning is shown if you have a conditional attribute declared on a resource as a block that contains only a single string.
This example matches the FC026 rule because it returns a string from the block. This will always evalute to true, and often indicates that you are trying to run a command rather than execute a Ruby block as your condition.
If the intention is to run the string as an operating system command then remove the block surrounding the command.
# Don't do this
template "/etc/foo" do
mode "0644"
source "foo.erb"
not_if { "test -f /etc/foo" }
end
template "/etc/foo" do
mode "0644"
source "foo.erb"
not_if "test -f /etc/foo"
end
correctness
This warning is shown if you set an attribute on a Chef resource that is technically accessible but should not be set in normal usage. To avoid this warning allow Chef to set the value of the internal attribute rather than setting it yourself.
This example matches the FC027 rule because it sets the running attribute on a service resource. This attribute should normally be set by the provider itself and not in normal recipe usage.
In this particular example you can achieve the same effect by using the service :start action.
# Don't do this
service "foo" do
running true
end
service "foo" do
action :start
end
correctness
This warning is shown if you attempt to use the platform? Chef built-in method as node.platform?. Because of the way Chef attributes work the later approach will not error but will do the wrong thing which may result in resources you had intended to apply only to a single platform instead being applied to all platforms.
This example matches the FC028 rule because the platform? method is incorrectly prefixed with node.
Remove the leading node. from the use of platform? to resolve this warning.
# Don't do this
file "/etc/foo" do
only_if { node.platform?("commodore64") }
end
file "/etc/foo" do
only_if { platform?("commodore64") }
end
correctness
metadata
This warning is shown if you declare a recipe in your cookbook metadata without including the cookbook name as a prefix.
This example matches the FC029 rule because the metadata declares a recipe without prefixing it with the name of the current cookbook.
This modified example would not match the FC029 rule:
# Don't do this
name "example"
version "1.2.3"
recipe "default", "Installs Example"
name "example"
version "1.2.3"
recipe "example::default", "Installs Example"
annoyances
Pry is a fantastic tool for interactive exploration of a running Ruby program. You can place breakpoints in your cookbook code that will launch a Pry console. This warning is shown when your cookbook code contains these breakpoints, as failing to remove these will cause your Chef run to halt.
This rule currently only checks for use of binding.pry and not the Chef built-in breakpoint resource which is never used outside of Shef.
This example matches the FC030 rule because it includes a Pry breakpoint declared with binding.pry.
This modified example would not match the FC030 rule:
# Don't do this
template "/etc/foo" do
source "foo.erb"
end
binding.pry
template "/etc/foo" do
source "foo.erb"
end
correctness
metadata
Chef cookbooks normally include a metadata.rb file which can be used to express a wide range of metadata about a cookbook. This warning is shown when a directory appears to contain a cookbook, but does not include the expected metadata.rb file at the top-level.
correctness
notifications
Chef notifications allow a resource to define that it should be actioned when another resource changes state.
Notification timing can be controlled and set to immediate, or delayed until the end of the Chef run. This warning is shown when the timing specified is not recognised.
This example matches the FC032 rule because it specifies an invalid notification timing.
This modified example would not match the FC032 rule because the mispelt timing has been corrected.
# Don't do this
template "/etc/foo" do
notifies :restart, "service[foo]", :imediately
end
template "/etc/foo" do
notifies :restart, "service[foo]", :immediately
end
correctness
This warning is shown when the erb template associated with a template resource cannot be found.
correctness
This warning is shown when one or more variables passed into a template by a template resource are not then used within the template.
This is often a sign that a template still contains hard-coded values that you intended to parameterise.
This example matches the FC034 rule because it passes two variables to the template, of which only the first is used.
This modified example would not match the FC034 rule becuse the template has been updated to include both variables passed through.
template "/etc/foo/config.conf" do
source "config.conf.erb"
variables(
'config_var_a' => node['config']['config_var_a']
'config_var_b' => node['config']['config_var_b']
)
end
# config.conf.erb
var_a=<%= @config_var_a %>
template "/etc/foo/config.conf" do
source "config.conf.erb"
variables(
'config_var_a' => node['config']['config_var_a']
'config_var_b' => node['config']['config_var_b']
)
end
# config.conf.erb
var_a=<%= @config_var_a %>
var_b=<%= @config_var_b %>
style
This rule has been deprecated. See the discussion against issue #60 for more detail.
correctness
This warning is shown when a resource notifies another resource to take an action, but the action is invalid for the target resource type.
This example matches the FC037 rule because :activate_turbo_boost is not a valid action for services.
This modified example would not match the FC037 rule because the action has been corrected.
# Don't do this
template "/etc/foo.conf" do
notifies :activate_turbo_boost, "service[foo]"
end
template "/etc/foo.conf" do
notifies :restart, "service[foo]"
end
correctness
This warning is shown when a resource action is not valid for the type of resource.
This example matches the FC038 rule because :none is not a valid action.
This modified example would not match the FC038 rule because the action has been corrected.
# Don't do this
service "foo" do
action :none
end
service "foo" do
action :nothing
end
correctness
Chef allows you to use varying syntax to refer to node attributes. This warning is shown when you attempt to reference a method on Chef::Node using the same string or symbol syntax reserved for node attributes.
This example matches the FC039 rule because run_state is only accessible as a method and cannot be referenced as an attribute.
This modified example would not match the FC039 rule because the run_state is referenced as a method.
# Don't do this
node['run_state']['nginx_force_recompile'] = false
node.run_state['nginx_force_recompile'] = false
style
recipe
etsy
This warning is shown if you declare an execute resource that uses git. If the command you are attempting to execute is supported by the git resource you should probably use that instead.
This example matches the FC040 rule because an execute resource is used where you could instead use a git resource.
This modified example would not match the FC040 rule because the execute resource has been replaced by a git resource.
execute "git clone https://github.com/git/git.git" do
action :run
end
git "/foo/bar" do
repository "git://github.com/git/git.git"
reference "master"
action :sync
end
style
recipe
etsy
This warning is shown if you use an execute resource to run the curl or wget commands. If you are downloading a file consider using the remote_file resource instead.
This example matches the FC041 rule because an execute resource is used where you could instead use a remote_file resource.
This modified example would not match the FC041 rule because the execute resource has been replaced by a remote_file resource.
execute "cd /tmp && wget 'http://example.org/'" do
action :run
end
remote_file "/tmp/testfile" do
source "http://www.example.org/"
end
deprecated
This warning is shown when require_recipe is used. Because require_recipe has been deprecated you should replace any references to to require_recipe with include_recipe.
This example matches the FC042 rule because the deprecated require_recipe statement is used.
This modified example would not match the FC042 rule because the require_recipe statement has been replaced with include_recipe.
# Don't do this
require_recipe "apache2::default"
include_recipe "apache2::default"
style
notifications
deprecated
This warning is shown when you use the old-style notification syntax. You should prefer the new-style notification syntax which has the advantage that you can notify resources that are defined later.
This example matches the FC043 rule because it uses the older notification syntax.
This modified example would not match the FC043 rule because the syntax of the notification has been updated to use the new format.
template "/etc/www/configures-apache.conf" do
notifies :restart, resources(:service => "apache")
end
template "/etc/www/configures-apache.conf" do
notifies :restart, "service[apache]"
end
style
This warning is shown when, within a cookbook attributes file, you refer to an attribute as you would a local variable rather than as an attribute of the node object. It is valid to do the former, but you should prefer the later more explicit approach to accessing attributes because it is easier for users of your cookbooks to understand.
This example matches the FC044 rule because it refers to the hostname attribute as a bare attribute.
This modified example would not match the FC044 rule because the reference to the hostname attribute has been qualified so that the meaning is more apparent.
default['myhostname'] = hostname
default['myhostname'] = node['hostname']
annoyances
metadata
This warning is shown when your cookbook does not define a name within the cookbook metadata.rb file. It’s a good idea to specify a name in your cookbook metadata to avoid breakage if the name of the containing directory changes.
You can include or exclude rules to apply using the --tags argument to foodcritic. The tag expressions you can specify follow the same syntax as that used in Cucumber - see the Cucumber wiki page below for details.
For example if you don’t care about style warnings you could run foodcritic like so:
$ foodcritic --tags ~style cookbooksEach rule has an implicit tag so you can exclude individual rules by rule code:
$ foodcritic --tags ~FC002 cookbooksThis is because your current Ruby has not been installed with Readline. If you are using RVM you can follow the instructions on the RVM site to resolve this:
You can tell foodcritic which warnings you want it to fail the build on with the -f option. See the Failing the build section for more detail.
Because Chef cookbooks are simply Ruby, you don’t need a Chef-specific style tool to check your style. As such, some foodcritic users use tailor for assessing the style of their cookbooks. You can check the docs for more details, but here’s a quick getting-started guide.
Install tailor:
$ gem install tailorCreate a .tailor configuration file in the root of your project. What you consider to be the “root” is really up to you; if you intend to use the same style rules for all of your cookbooks, put it at the root of your cookbooks. Use tailor to create a default config file for you:
$ tailor --create-configView the .tailor file with your favorite text editor, and you’ll see something like (minus documentation at the top):
Tailor.config do |config|
config.formatters "text"
config.file_set 'lib/**/*.rb' do |style|
style.allow_camel_case_methods false, level: :error
style.allow_hard_tabs false, level: :error
style.allow_screaming_snake_case_classes false, level: :error
style.allow_trailing_line_spaces false, level: :error
style.allow_invalid_ruby false, level: :warn
style.indentation_spaces 2, level: :error
style.max_code_lines_in_class 300, level: :error
style.max_code_lines_in_method 30, level: :error
style.max_line_length 80, level: :error
style.spaces_after_comma 1, level: :error
style.spaces_after_lbrace 1, level: :error
style.spaces_after_lbracket 0, level: :error
style.spaces_after_lparen 0, level: :error
style.spaces_before_comma 0, level: :error
style.spaces_before_lbrace 1, level: :error
style.spaces_before_rbrace 1, level: :error
style.spaces_before_rbracket 0, level: :error
style.spaces_before_rparen 0, level: :error
style.spaces_in_empty_braces 0, level: :error
style.trailing_newlines 1, level: :error
end
endSince most Ruby project stick their code in a lib directory, the default “file set” is set to apply that default list of style rulers to all files ending in .rb under that directory–change 'lib/**/*.rb' to '**/*.rb' instead to capture all cookbook files.
Take a look at the list of files tailor will measure when you run it:
$ tailor --show-configMeasure!
$ tailorTake a look at the documentation in the config file or at https://github.com/turboladen/tailor for more explanation on the options. To disable any option, simply set level: :off.
Also, tailor will only return an exit status of 1 if errors are encountered. If you still want to know about the problems, but don’t want your builds failing, you can set level: :warn.
For public cookbooks hosted on GitHub Travis CI is a great choice for setting up continuous integration.
Nathen Harvey’s excellent blog post on Minimum Viable Testing with Foodcritic and Travis CI includes everything you need to get up and running.
To manually add a new job to Jenkins to check your cookbooks with foodcritic do the following:
Ensure you have Ruby 1.9.2+ and the foodcritic gem installed on the box running Jenkins.
You’ll probably need to install the Git plugin. In Jenkins select “Manage Jenkins” -> “Manage Plugins”. Select the “Available” tab. Check the checkbox next to the Git Plugin and click the “Install without restart” button.
In Jenkins select “New Job”. Enter a name for the job “my-cookbook”, select “Build a free-style software project” and click “OK”.
On the resulting page select “Git” under “Source Code Management” and enter the URL for your repo.
Check the checkbox “Poll SCM” under “Build Triggers”.
Click “Add Build Step” -> “Execute shell” under “Build”. This is where we will call foodcritic.
Assuming you are using rvm enter the following as the command:
#!/usr/bin/env rvm-shell 1.9.3
foodcritic .Click “Save”.
Cool, we’ve created your new job. Now lets see if it works. Click “Build Now” on the left-hand side.
You can click the build progress bar to be taken directly to the console output.
After a moment you should see that the build has been successful and foodcritic warnings (if any) are shown in your console output.
Yes, for maximum goodness you should be automating all this with Chef. :-)
For more information refer to the instructions for building a “free-style software project” here:
See also this blog post about rvm-shell which ensures you have the right version of Ruby loaded when trying to build with foodcritic:
The above is a start, but we’d also like to fail the build if there are any warnings that might stop the cookbook from working.
CI is only useful if people will act on it. Lets start by only failing the build when there is a correctness problem that would likely break our Chef run. We’ll continue to have the other warnings available for reference in the console log but only correctness issues will fail the build.
Select the “my-cookbook” job in Jenkins and click “Configure”.
Scroll down to our “Execute shell” command and change it to look like the following:
#!/usr/bin/env rvm-shell 1.9.3
foodcritic -f correctness .Click “Save” and then “Build Now”.
Foodcritic supports more complex expressions with the standard Cucumber tag syntax. For example:
#!/usr/bin/env rvm-shell 1.9.3
foodcritic -f any -f ~FC014 .Here we use any to fail the build on any warning, but then use the tilde ~ to exclude FC014. The build will fail on any warning raised, except FC014.
You can find more detail on Cucumber tag expressions at the Cucumber wiki:
The Jenkins Warnings plugin can be configured to understand foodcritic output and track your cookbook warnings over time.
You’ll need to install the Warnings plugin. In Jenkins select “Manage Jenkins” -> “Manage Plugins”. Select the “Available” tab. Check the checkbox next to the Warnings Plugin and click the “Install without restart” button.
From “Manage Jenkins” select “Configure System”. Scroll down to the “Compiler Warnings” section and click the “Add” button next to “Parsers”.
Enter “Foodcritic” in the Name field.
Enter the following regex in the “Regular Expression” field:
^(FC[0-9]+): (.*): ([^:]+):([0-9]+)$Enter the following Groovy script into the “Mapping Script” field:
import hudson.plugins.warnings.parser.Warning
String fileName = matcher.group(3)
String lineNumber = matcher.group(4)
String category = matcher.group(1)
String message = matcher.group(2)
return new Warning(fileName, Integer.parseInt(lineNumber), "Chef Lint Warning", category, message);To test the match, enter the following example message in the “Example Log Message” field:
FC001: Use strings in preference to symbols to access node attributes: ./recipes/innostore.rb:30Click in the “Mapping Script” field and you should see the following appear below the Example Log Message:
One warning found
file name: ./recipes/innostore.rb
line number: 30
priority: Normal Priority
category: FC001
type: Chef Lint Warning
message: Use strings in prefe[...]ols to access node attributesCool, it’s parsed our example message successfully. Click “Save” to save the parser.
Select the “my-cookbook” job in Jenkins and click “Configure”.
Check the checkbox next to “Scan for compiler warnings” underneath “Post-build Actions”.
Click the “Add” button next to “Scan console log” and select our “Foodcritic” parser from the drop-down list.
Click the “Advanced…” button and check the “Run always” checkbox.
Click “Save” and then “Build Now”.
Add the bottom of the console log you should see something similar to this:
[WARNINGS] Parsing warnings in console log with parsers [Foodcritic]
[WARNINGS] Foodcritic : Found 48 warnings.Click “Back to Project”. Once you have built the project a couple of times the warnings trend will appear here.
As an alternative to invoking foodcritic directly as a command-line program, you can also choose to run foodcritic from a build using Rake or Thor.
Foodcritic has unreleased experimental support for Rake included. With foodcritic and rake in your Gemfile your Rakefile would look like this:
require 'foodcritic'
task :default => [:foodcritic]
FoodCritic::Rake::LintTask.newYou can also pass a block when instantiating to configure the lint options:
require 'foodcritic'
task :default => [:foodcritic]
FoodCritic::Rake::LintTask.new do |t|
t.options = {:fail_tags => ['correctness']}
endWhile Rake is the old grand-daddy of Ruby build tools, a number of people prefer to use Thor.
Jamie Winsor has released the thor-foodcritic gem with some easy instructions to get started if you are using Thor for your build.
Find attributes accesses by type.
You might use this method to enforce local style rules on how attributes are accessed.
# All references to attributes using strings
# For example: node['foo']
attribute_access(ast, :type => :string)
# All references to attributes using symbols
# For example: node[:foo]
attribute_access(ast, :type => :symbol)
# All references to attributes using dots (vivified methods)
# For example: node.foo
attribute_access(ast, :type => :symbol)
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The AST of the cookbook recipe to check |
| param | Hash |
options |
The options hash (see allowed values below) |
| option | Symbol |
:type |
The approach used to access the attributes. One of |
| option | Boolean |
:ignore_calls |
Exclude attribute accesses that mix strings/symbols with dot notation. Defaults to |
| return | Array |
The matching nodes if any |
Does the specified recipe check for Chef Solo?
You can use this to check for the portability of the recipe between Chef Server and Chef Solo.
# Returns true if the recipe checks for Chef Solo before using
# server-specific functionality.
checks_for_chef_solo?(ast)
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The AST of the cookbook recipe to check |
| return | Boolean |
True if there is a test for |
The set of methods in the Chef DSL.
You can use this to see if a method reference is part of the Chef DSL or defined in a cookbook.
# Is search a method in the Chef DSL?
chef_dsl_methods.include?(:search)
=> true
| category | type | name | description |
|---|---|---|---|
| return | Array |
Array of method symbols |
Is the chef-solo-search library available?
Will return true if any cookbook in the cookbook tree relative to the specified recipe includes the chef-solo-search library. You can use this to see if search is available in Chef Solo mode.
# True if chef_solo_search is supported
chef_solo_search_supported?('foo/recipes/default.rb')
| category | type | name | description |
|---|---|---|---|
| param | String |
recipe_path |
The path to the current recipe |
| return | Boolean |
True if the chef-solo-search library is available. |
The name of the cookbook containing the specified file.
You can use this method in rules that need to work out if recipe code refers to the current cookbook: for example when looking at included_recipe statements or LWRP usage.
cookbook_name('foo/recipes/default.rb')
=> "foo"
| category | type | name | description |
|---|---|---|---|
| param | String |
file |
The file in the cookbook |
| return | String |
The name of the containing cookbook |
The dependencies declared in cookbook metadata.
You can use this to check if all dependencies have been declared correctly or to find all cookbooks that share a common dependency.
ast = read_ast('postgresql/metadata.rb')
declared_dependencies(ast)
=> ["openssl"]
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The metadata rb AST |
| return | Array |
List of cookbooks depended on |
Create a match for a specified file. Use this if the presence of the file triggers the warning rather than content.
This is an alternative to match where you don’t have a specific AST element to associate the warning with. The call to file_match will typically be the last line in your rule.
file_match('foo/recipes/default.rb')
=> {:filename=>"foo/recipes/default.rb",
:matched=>"foo/recipes/default.rb",
:line=>1,
:column=>1}
| category | type | name | description |
|---|---|---|---|
| param | String |
file |
The filename to create a match for |
| return | Hash |
Hash with the match details |
Find Chef resources of the specified type.
Note that currently this method does not return blockless resources.
# Returns all resources in the AST
find_resources(ast)
# Returns just the packages
find_resources(ast, :type => :package)
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The AST of the cookbook recipe to check |
| param | Hash |
options |
The options hash (see allowed values below) |
| option | Symbol |
:type |
The type of resource to look for (or |
| return | Array |
AST nodes of Chef resources. |
Retrieve the recipes that are included within the given recipe AST.
You can use this method to determine (and validate) recipe runtime dependencies.
# Find all include_recipe statements, discarding the AST nodes to just
# show the recipe names.
included_recipes(ast).keys
=> ["postgresql::client"]
included_recipes(ast, :with_partial_names => false).keys
=> ["postgresql::client"]
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The recipe AST |
| param | Hash |
options |
|
| return | Hash |
Hash keyed by included recipe name where the value is the AST node |
Searches performed by the specified recipe that are literal strings. Searches with a query formed from a subexpression will be ignored.
ast = read_ast('zenoss/recipes/server.rb')
literal_searches(ast).size
=> 3
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The AST of the cookbook recipe to check |
| return | Array |
The matching nodes |
Create a match from the specified node.
Return matches when a rule has matched against a recipe. A call to match is typically the last line of your rule.
Ensure that the AST node you are passing to this method has a descendant pos node so that the match can be associated with a line in the file.
# You will frequently use map to apply the match function to an array of
# nodes that you consider matches for your rule.
attribute_access(ast, :type => :string).map{|s| match(s)}
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
node |
The node to create a match for |
| return | Hash |
Hash with the matched node name and position with the recipe |
Provides convenient access to resource notification details. You can pass either the AST for an individual resource or the entire recipe to this method. Note that a resource may be registered for multiple notifications / subscriptions.
While Chef permits either :immediate or :immediately to be specified in cookbooks, the timing for both will be returned as :immediate to remove the need for callers to switch on both values.
find_resources(ast).select do |resource|
notifications(resource).any? do |notification|
! [:delayed, :immediate].include? notification[:timing]
end
end
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The AST to check for notifications. |
| return | Array |
A flat array of notification hashes.
|
Does the provided string look like an Operating System command? This is a rough heuristic to be taken with a pinch of salt.
| category | type | name | description |
|---|---|---|---|
| param | String |
str |
The string to check |
| return | Boolean |
True if this string might be an OS command |
Read the AST for the given Ruby or Erb source file.
Many of the other functions documented here take an ast as an argument. You can also use Nokogiri’s support querying the AST with XPath or CSS to implement your own rules.
# Normally the recipe AST will be passed in to your rule without you
# needing to use read_ast.
# However if you need to you can read in the AST for a cookbook recipe
# directly.
ast = read_ast('apache2/recipes/default.rb')
| category | type | name | description |
|---|---|---|---|
| param | String |
file |
The file to read |
| return | Nokogiri::XML::Node |
The recipe AST |
Determine if an action is valid for the given resource type.
resource_action?(:service, :restart)
=> true
| category | type | name | description |
|---|---|---|---|
| param | Symbol |
resource_type |
The type of resource |
| param | Symbol |
action |
The name of the action |
| return | Boolean |
True if the action is valid for this type of resource. |
Retrieve a single-valued attribute from the specified resource.
# Given resource is a package
resource_attribute(resource, 'action')
=> :install
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
resource |
The resource AST to lookup the attribute under |
| param | String |
name |
The attribute name |
| return | String |
The attribute value for the specified attribute |
Is the specified attribute valid for the type of resource? Note that this method will return true if the resource_type is not recognised.
resource_attribute?(:file, :mode)
=> true
resource_attribute?(:file, :size)
=> false
# If the resource is not a Chef built-in then the attribute is always
# valid
resource_attribute?(:my_custom_resource, :whatever)
=> true
| category | type | name | description |
|---|---|---|---|
| param | Symbol |
resource_type |
The type of Chef resource |
| param | Symbol |
attribute_name |
The attribute name |
| return | Boolean |
True if the attribute is valid for this type of resource |
Retrieve all attributes from the specified resource.
Use this method for convenient access to the resource attributes without needing to query the AST.
resource_attributes(resource)
=> {:name=>"zenoss", "arch"=>"kernel", "action"=>:install}
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
resource |
The resource AST |
| return | Hash |
The resource attributes |
Retrieve the attributes as a hash for all resources of a given type.
Use this if you want to compare the attributes and values used by resources of the same type.
# The values of the Hash (ignored here) are arrays of resource ASTs.
resource_attributes_by_type(ast).keys.sort
=> ["apt_package",
"apt_repository",
"execute",
"package",
"ruby_block"]
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The recipe AST |
| return | Hash |
Resources keyed by type, with an array for each |
Retrieve the name attribute associated with the specified resource.
resource_name(resource)
=> "zenoss"
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
resource |
The resource AST to lookup the name attribute under |
| return | String |
The name attribute value |
Return the type, e.g. ‘package’ of a given resource.
You could use this if you wanted to take different action in your rule based on the resource type.
resource_type(resource)
=> "yum_package"
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
resource |
The resource AST |
| return | String |
The type of resource |
Retrieve all resources of a given type.
The key of the hash is the type of resource (as a string). The value is an array of Hashes.
resources_by_type(ast).keys
=> ["yum_key",
"yum_repository",
"package",
"service",
"yum_package",
"apt_repository",
"apt_package"]
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The recipe AST |
| return | Hash |
The matching resources |
Does the provided string look like ruby code? This does not evaluate the expression, instead only checking that it appears syntactically valid.
You can use this method to check that ruby_block resources and recipes themselves look like Ruby code.
# Lots of strings are well-formed Ruby statements, including some strings
# you might not expect:
ruby_code?('System.out.println("hello world");')
=> true
# This operating system command doesn't look like valid Ruby but others
# might.
ruby_code?('find -type f -print')
=> false
| category | type | name | description |
|---|---|---|---|
| param | String |
str |
The string to check for rubiness |
| return | Boolean |
|
Searches performed by the specified recipe. In contrast to literal_searches this method returns all searches.
You could use this method to identify all searches that search for a particular type of object, or to identify searches that are valid for a particular Chef version.
| category | type | name | description |
|---|---|---|---|
| param | Nokogiri::XML::Node |
ast |
The AST of the cookbook recipe to check. |
| return | Array |
The AST nodes in the recipe where searches are performed |
The list of standard cookbook sub-directories.
You can use this method when you need to traverse cookbooks manually yourself in order to determine directories to descend into.
standard_cookbook_subdirs
=> ["attributes",
"definitions",
"files",
"libraries",
"providers",
"recipes",
"resources",
"templates"]
| category | type | name | description |
|---|---|---|---|
| return | Array |
The standard list of directories. |
Is this a valid Lucene query?
Use this method when acting on searches in a recipe in order to check that they are valid before continuing with the rest of your rule.
valid_query?('run_list:recipe[foo::bar]')
=> false
valid_query?('run_list:recipe\[foo\:\:bar\]')
=> true
| category | type | name | description |
|---|---|---|---|
| param | String |
query |
The query to check for syntax errors |
| return | Boolean |
|