Chef wrapper cookbook best practices

Question

In learning chef, I see conflicting patterns for wrapper cookbooks. For example.

Some cookbooks use default.rb and others use customize.rb for overrides.

Answer 1

There is very little in the way of best practices out there, sadly, but there are a few gotchas to be careful about.

Attribute loading order

Attributes files are loaded (Executed) in a very specific, albeit not very clear, order.

1. The required cookbooks are resolved based on the runlist and metadata for each cookbook referenced in the runlist, and all dependencies.
2. Once a list of involved cookbooks has been compiled, they are ordered lexigraphically.
3. The attribute files from each cookbook are then ordered lexigraphically.
4. Execution starts at the to of the list, however, if an include_attribute statement is encountered, that attribute file will be immediately executed (and removed from the list so that it is not executed a second time.)

This is important because if the same attribute is set at the same level ie default by more than one attributes file, then the last file to execute will determine which value wins. __So always include_attribute the attribute file from your library cookbook at the top of the attribute file for your wrapper cookbook. Then set attributes at the default level (so that they can more easily be overridden elsewhere).

One of these things is not like the others

Normal attributes (node.set or node.normal) are a funny beast. They persist between chef runs. So once you set an attribute to normal, it will stick around until you either remove it, or change it. Sometimes this is a good thing, like a uuid you want to remember, but sometimes it is an unexpected side effect.

Style

symbols and strings, and methods, oh my.

There is a LOT of debate regarding node.attribute, node[:attribute], and node['attribute'] access styles. Just read up on foodcritic 001 if you want to see both sides of the coin. In my opinion, node['attribute'] has won the majority of community cookbook developers, but it is a pretty slim majority. node.attribute is almost universally frowned upon because it can have evil side effects. Ultimately, you use what you like best, but if your library cookbooks are fairly consistent, I'd suggest you follow their convention.

Where to override

Personally, I try hard to never set an attribute outside of an attributes file. It too often leads to headaches. It's just easier to keep all attribute set operations in the attributes files, so you can easily hunt them down. But there are times when you either cannot do it in the attributes file, or it just makes more sense in the recipe. As with most programing rules, you just have to weigh consistency with what feels right.

Answer 2

I haven't seen any formal best practice on how to override attributes in wrapper cookbooks, I think one has to pick a style and as long as all your cookbooks are consistent within your organization, you should be good. What follows is my person opinions.

---

Attributes File

We initially followed the style of separating attribute files similar to that attributes/customize.rb format you described. However, we found it's much simpler to just keep all attributes in attributes/default.rb, especially since our attributes stay under 50 lines of code.

Override Precedence

We always use the lowest attribute precedence when overriding attributes in our wrapper cookbook. We stick to default whenever possible, because the order of precedence dictates your cookbook's default wins out over the wrapped cookbooks default.

Attribute Access Style

Most cookbooks you see out there use the string access format.

default['foo']['bar'] = 42

In fact there's a foodcritic rule specifically discouraging the use of symbol access. Foodcritic also encourages using a consistent style for accessing attributes. If you're deciding on a style, keep in mind that the community has pretty much decided on the string access format.

However, there is another way. Attributes in Chef are not a Hash, they're actually a Mash. Mash happens to support accessing attributes as methods, so:

default.foo.bar = 42

We prefer that syntax because it's more compact.

However, be cautious, as Tejay Cardon points out, Chef implemented this with method_missing, so you could run into issues if the attribute name is the same as a current (or future) node object method. We preface all our cookbooks with our org name, so collision is unlikely, but when we override community cookbooks we might run into issues. Thankfully testing should catch any such lapses.

Cautionary Note

Overriding attributes in a wrapper cookbook will not work in surprising ways, particularly when string interpolation is involved. This is explained very well in this blog post. The main gist is if a cookbook defines attributes as:

default['version'] = '1.0'
default['url'] = "http://example.com/#{node['version']}.zip"

And in your wrapper cookbook you override version:

default['version'] = '2.0'

The default['url'] will still resolve to http://example.com/1.0.zip, not http://example.com/2.0.zip as you might expect. This happens because the url attribute is interpolated before your override happens. The blog post goes into more depth and offers a potential solution.

Wrap Up

At the end of the day, there are multiple ways to do things in Chef and the community is still maturing. There's some best practices around writing reusable cookbooks, etc, but the practices are still evolving.

The best thing you can do is try the various styles and figure out which one works best for you and your team. Once you've decided on a style, I'd suggest putting together a style guide (I've used this Angular style guide as inspiration). You can also enforce your style guide with custom foodcritic rules. We've had success with this approach.