You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
170 lines
8.2 KiB
170 lines
8.2 KiB
---
|
|
layout: post
|
|
title: Writing Wrapper Cookbooks
|
|
category: chef_infra
|
|
tags: [chef, cookbooks]
|
|
summary: It's been a while since a blog post was released regarding wrapper cookbooks. Let's revisit the topic.
|
|
---
|
|
|
|
## What is a Wrapper Cookbook?
|
|
Simply put, a wrapper cookbook is just a regular cookbook that includes recipes from other cookbooks.
|
|
|
|
Common use cases for wrapper cookbooks include:
|
|
|
|
- Modifying the behavior of a community cookbook from the [Chef Supermarket](https://supermarket.chef.io)
|
|
- Bundling several base cookbooks into a single cookbook
|
|
- Version controlling a node's run list and attribute definitions
|
|
|
|
---
|
|
|
|
## Writing a Wrapper Cookbook
|
|
To include another cookbook in your wrapper cookbook you must do a minimum of two things:
|
|
|
|
- Add dependencies to your wrapper cookbook's `metadata.rb`
|
|
- Add an `include_recipe` line to your wrapper cookbook's `recipes/default.rb`
|
|
|
|
### Including Dependencies
|
|
Including dependencies is a simple as adding the following to your `metadata.rb`:
|
|
|
|
```ruby
|
|
depends 'public_cookbook'
|
|
```
|
|
|
|
You can also optionally perform version pinning like so:
|
|
|
|
```ruby
|
|
depends 'public_cookbook', '= 1.4.5'
|
|
```
|
|
|
|
For more information about version pinning see the `metadata.rb` page on the [Chef Docs site](https://docs.chef.io/config_rb_metadata.html).
|
|
|
|
### Setting Attributes
|
|
Setting attributes in your wrapper cookbook is a common way to modify the behavior of the cookbook you are wrapping. Well written community cookbooks support modifying their behavior in this manner and will document its attributes within their `README.md`.
|
|
|
|
These attributes can be added in your wrapper cookbook's `attributes/default.rb` and/or in your default recipe before your `include_recipe` line.
|
|
|
|
> I decide where to place the attributes as follows: If the attributes are computed using other attributes or set via logic (e.g `case`, `if`, `unless`) place them in `recipes/default.rb` otherwise place them in `attributes/default.rb`
|
|
|
|
### Completing the Wrap
|
|
In order to add the functionality from your wrapped cookbook, you will need to include that cookbook in your wrapper cookbook's default recipe.
|
|
|
|
This is usually done with the help of the `include_recipe` method, like so:
|
|
|
|
```ruby
|
|
include_recipe 'public_cookbook::default'
|
|
```
|
|
|
|
Once you have completed this your cookbook is ready for use.
|
|
|
|
---
|
|
|
|
## Sample Use Cases
|
|
For the examples below let's assume we want to use the [IIS cookbook](https://supermarket.chef.io/cookbooks/iis) from the [Chef Supermarket](https://supermarket.chef.io)
|
|
|
|
### Creating the wrapper
|
|
By running the following `chef` [command](https://docs.chef.io/ctl_chef.html#chef-generate-cookbook) we can generate our wrapper cookbook:
|
|
|
|
```bash
|
|
chef generate cookbook my_company_iis
|
|
```
|
|
|
|
From here we add the following to our `metadata.rb`
|
|
|
|
```ruby
|
|
depends 'iis'
|
|
```
|
|
|
|
Then we can add the necessary `include_recipe` line to our `recipes/default.rb`
|
|
|
|
```ruby
|
|
include_recipe 'iis::default'
|
|
```
|
|
|
|
Doing the actions above will create a wrapper cookbook that will use the IIS cookbook to:
|
|
|
|
- Install IIS
|
|
- Ensure the `w3svc` is enabled and started
|
|
- Serve the `Default Web Site`
|
|
|
|
### Modifying Public Cookbook Behavior
|
|
The above example is great, but let's assume that your company hosts its websites on `D:` instead of `C:`. We can change this by modifying the attributes that the IIS cookbook consumes.
|
|
|
|
To host websites out of `D:` add the following to your wrapper cookbook's `attributes/default.rb`
|
|
|
|
```ruby
|
|
default['iis']['pubroot'] = 'D:\\inetpub'
|
|
default['iis']['docroot'] = 'D:\\inetpub\\wwwroot'
|
|
default['iis']['log_dir'] = 'D:\\inetpub\\logs\\LogFiles'
|
|
default['iis']['cache_dir'] = 'D:\\inetpub\\temp'
|
|
```
|
|
|
|
Adding this to your wrapper cookbook's attributes file will modify the behavior of the IIS cookbook.
|
|
|
|
### Application Cookbooks
|
|
By completing the above you have now created a base cookbook that will install IIS in the fashion that your company desires. Now we can expand on this by utilizing an additional wrapper cookbook.
|
|
|
|
Let's say we did the same as above but also created a `my_company_app` cookbook and included our `my_company_iis` cookbook with a hard version pinning. By doing this we can give the developer of `my_company_app` the freedom to have IIS installed to company specifications, but without worrying about how things work behind the scenes.
|
|
|
|
This allows one team to focus on coding the logic that deploys their web application without also having to code the logic for installing IIS to company specifications.
|
|
|
|
### Role Cookbooks
|
|
Eventually you will have multiple base cookbooks and you may want to combine them into a single logical unit, so that can be tested together. Take for example a cookbook called `role_my_company_website`. This cookbook's default recipe might look like the following:
|
|
|
|
```ruby
|
|
include_recipe 'my_company_windows_base::default'
|
|
include_recipe 'my_company_audit::default'
|
|
include_recipe 'my_company_iis::default'
|
|
include_recipe 'my_company_website::default'
|
|
```
|
|
|
|
Then in this cookbook's `metadata.rb` you would have hard version pinnings for each of the dependant cookbooks.
|
|
|
|
By doing this you can now apply `role_my_company_website` to a node and test it as a cumulative collection of all its underlying cookbooks. Then, if all the dependant cookbooks have proper tests, you only have to worry about testing the output of `role_my_company_website` without having to test each of its underlying components.
|
|
|
|
This reduces the amount of repeated work and produces an artifact that is:
|
|
|
|
- Easy to understand
|
|
- Version controlled
|
|
- Independently testable
|
|
|
|
This also leads to a cookbook that succinctly describes a particular node in your Chef managed ecosystem. You could use this succinct description of node function to your advantage. For example, your load balancer cookbook could find all nodes that have the `run_list` of `recipes['role_my_company_website']` and automatically add them to it's backend server list.
|
|
|
|
---
|
|
|
|
## Advanced Use Cases
|
|
You may run into a scenario where a community cookbook performs 99% of what you require, but also does something you don't want it to do, as well.
|
|
|
|
Ideally, you should submit a pull request to the cookbook's maintainer that makes the default behavior tunable, but in a pinch you can do things such as modifying the resource collection during the compile phase.
|
|
|
|
### Modifying the Resource Collection
|
|
Take for example, a cookbook that lays down a file on the file system via a template, but that cookbook's template doesn't suit your needs.
|
|
|
|
In your recipe you can use the `edit_resource` helper method provided by Chef's [Recipe DSL](https://docs.chef.io/dsl_recipe.html#edit-resource) to modify their template resource to point to a template in your wrapper cookbook instead.
|
|
|
|
In practice it looks like this:
|
|
|
|
```ruby
|
|
include_recipe 'bad_cookbook::default'
|
|
|
|
edit_resource(:template, 'C:\\important\\template\\path.ini') do
|
|
source 'my_beautiful_template.erb'
|
|
cookbook 'my_awesome_wrapper'
|
|
end
|
|
```
|
|
|
|
Adding this to your wrapper cookbook's default recipe would allow you to use their cookbook as intended with the exception that your template will be used and not theirs.
|
|
|
|
---
|
|
|
|
## Summary
|
|
While simple on the surface, wrapper cookbooks provide critical functions to healthy Chef adoption. With the building blocks of attributes, includes, and version pinning you are able to perform many functions in a safe, repeatable, and efficient manner.
|
|
|
|
With wrapper cookbooks, you can modify the default behavior of community cookbooks without writing any additional code than a mere variable assignment. You can create reusable base cookbooks that can be consumed by developers' application cookbooks without requiring them to have in-depth operations knowledge. You can even condense multiple independent cookbooks into a single version controlled, and independently testable, artifact that succinctly describes a specific node's function in your ecosystem.
|
|
|
|
Now take this knowledge of wrapper cookbooks and go create something beautiful!
|
|
|
|
## Extra Resources
|
|
- [Doing Wrapper Cookbooks Right](https://blog.chef.io/2013/12/03/doing-wrapper-cookbooks-right/)
|
|
- [Example Audit Cookbook Wrapper](http://blog.jerryaldrichiii.com/chef/2017/03/20/using-the-audit-cookbook.html)
|
|
- [Changing Chef Resources at Runtime](https://sethvargo.com/changing-chef-resources-at-runtime/)
|
|
- [RIP chef-rewind](https://coderanger.net/rewind/)
|
|
|