Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 37 ยท Cookbooks and Attributes

Cookbook Metadata and Dependencies

Manage cookbook dependencies in Chef: depends in metadata.rb, version constraints, include_recipe, Berkshelf and the Chef Supermarket, with a runnable constraint resolver.

Few cookbooks stand alone. A web cookbook may rely on a cookbook that sets up logrotate, one that handles firewall rules, or a shared library cookbook your company wrote. Chef tracks these relationships in metadata.rb, resolves them to concrete versions and downloads them from a source such as the Chef Supermarket. This lesson explains dependencies, version constraints, include_recipe, Berkshelf and why you should be careful about which cookbooks you pull in. Real tool commands are read-only; a stand-in resolves version constraints.

Declaring dependencies

A cookbook lists what it needs in metadata.rb:

Ruby
name 'webserver'
version '1.2.0'

depends 'logrotate', '~> 3.0'
depends 'firewall', '>= 2.7.0'
depends 'acme_internal'

If you use another cookbook's recipes, resources or attributes, you must list it, otherwise a clean node fails because Chef does not download it. Listing a dependency also loads its attribute files and libraries before yours, which makes its attributes available in your recipes.

Version constraints

Constraint Meaning
= 1.2.3 exactly this version
>= 1.2 this or newer
~> 1.2 at least 1.2, below 2.0 ("pessimistic" operator)
~> 1.2.3 at least 1.2.3, below 1.3.0
(none) any version

The pessimistic operator is your best friend: ~> 3.0 accepts bug-fix and feature updates but blocks the next major release, which may break. Avoid unconstrained dependencies in shared cookbooks.

include_recipe

Dependencies make cookbooks available. To run another cookbook's recipe from your own, use include_recipe:

Ruby
include_recipe 'logrotate'
include_recipe 'firewall::default'

Chef runs the recipe at that point and only once, even if many recipes include it, so shared setup is safe to include everywhere. The included recipe's resources appear in the resource collection at the position of the call, which defines their order.

Berkshelf: resolving the tree

Berkshelf reads a Berksfile, finds every cookbook in the dependency tree (including dependencies of dependencies) and downloads versions that satisfy all constraints. A typical Berksfile (read-only):

Ruby
source 'https://supermarket.chef.io'

metadata

cookbook 'acme_internal', git: 'https://git.example.com/chef/acme_internal.git', tag: 'v2.0.0'

metadata pulls in the dependencies from metadata.rb. Commands:

Terminal
berks install     # resolve and download, writes Berksfile.lock
berks upload      # push all resolved cookbooks to the server
berks update      # re-resolve to the newest allowed versions

Berksfile.lock records the exact versions found, so teammates and CI get identical results. Commit it for application cookbooks. (Policyfiles, covered later, do the same job with a different file, Policyfile.rb, and are the newer recommended way.)

The Supermarket

The Chef Supermarket is the public site where cookbooks are shared. It is useful, but a cookbook from a stranger runs as root on your servers. Before relying on one, check its maintenance (recent releases), the supported platforms, its tests and its license, and consider vendoring (copying) the cookbook into your own repository. Many teams prefer small wrapper cookbooks: your own cookbook that depends on the community one, sets its attributes and includes its recipe, so upstream changes arrive deliberately.

Ruby
# metadata.rb of acme_nginx
depends 'nginx', '~> 12.0'

# recipes/default.rb
node.default['nginx']['worker_processes'] = 4
include_recipe 'nginx'

Stand-in: a version constraint checker

The stand-in implements =, >= and ~> and picks the newest version that satisfies a list of constraints, much like a dependency resolver does. It is not Berkshelf.

Ruby Stand-in: pick a version that satisfies constraints

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Look at ~> 3.0: it allows 3.0.0 to 3.4.1 but not 4.0.0, and the resolver picks 3.4.1. The same constraint written as ~> 3.1.0 narrows to patch releases of 3.1.

Dependency conflicts

If cookbook A needs logrotate ~> 3.0 and cookbook B needs logrotate ~> 2.0, nothing satisfies both and resolution fails. The cure is to update one cookbook, or fork one. The stand-in below shows the failure condition.

Ruby Stand-in: detect a conflicting pair

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Keep your dependency tree shallow. Each extra cookbook is something to test, upgrade and trust. Prefer a custom resource of your own over a huge community cookbook when you need only a small part of it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does depends 'logrotate', '~> 3.0' allow?

    The pessimistic operator accepts updates that do not change the major number.
  2. 2. When must you list a cookbook in depends?

    Without the dependency a clean node will not download the other cookbook.
  3. 3. What is Berksfile.lock for?

    The lock file makes dependency resolution reproducible.
  4. 4. What is a wrapper cookbook?

    Wrappers let you customize upstream cookbooks without editing them.

Summary

  • depends in metadata.rb declares cookbooks you need, with version constraints; prefer ~>.
  • include_recipe runs another cookbook's recipe once at that position.
  • Berkshelf (and Policyfiles) resolve and lock the dependency tree.
  • Vet community cookbooks and prefer wrapper cookbooks and a shallow tree.

Next: Custom Resources