Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Cookbooks and Attributes

Chef Cookbook Structure

Explore the layout of a Chef cookbook: metadata.rb, recipes, attributes, templates, files, libraries, resources, tests and Kitchen config, with a runnable layout checker.

A cookbook is the unit in which Chef code is written, tested, versioned and shared. It is a folder with a predictable layout, so Chef (and you) always know where to find recipes, templates and attributes. This lesson tours that layout file by file, shows the files chef generate cookbook creates and gives you a stand-in that checks a layout, since real cookbook folders need the Chef tools to work with.

The generated layout

Running chef generate cookbook webserver (read-only) produces something like this:

TEXT
webserver/
  Berksfile
  CHANGELOG.md
  LICENSE
  README.md
  chefignore
  kitchen.yml
  metadata.rb
  attributes/
    default.rb
  files/
    default/
  libraries/
  recipes/
    default.rb
  resources/
  templates/
    default/
  spec/ or test/
    integration/

Different Chef versions generate slightly different extras, but the core folders never change.

metadata.rb

The cookbook's identity card. Chef reads it before anything else.

Ruby
name 'webserver'
maintainer 'Platform Team'
maintainer_email '[email protected]'
license 'Apache-2.0'
description 'Installs and configures nginx'
version '1.2.0'
chef_version '>= 18.0'

supports 'ubuntu'
supports 'rocky'

depends 'logrotate', '~> 3.0'

Key fields: name, version (semantic versioning), depends for other cookbooks, supports for platforms and chef_version for the minimum client. The metadata and dependencies lesson goes further.

recipes/

Each .rb file is a recipe. default.rb is what recipe[webserver] runs. Other files are addressed as webserver::ssl. A good default.rb is small and calls others with include_recipe:

Ruby
include_recipe 'webserver::install'
include_recipe 'webserver::configure'
include_recipe 'webserver::service'

attributes/

Attribute files set defaults for the cookbook, for example in attributes/default.rb:

Ruby
default['webserver']['port'] = 80
default['webserver']['worker_processes'] = 2
default['webserver']['packages'] = %w(nginx)

Namespace every attribute with the cookbook name to avoid collisions. Attributes and Precedence covers the rules.

templates/ and files/

  • templates/ holds .erb files that Chef renders with variables (template resource), for example templates/default/nginx.conf.erb. The default folder is used when no platform-specific folder matches. You will master this in the templates chapter.
  • files/ holds static files copied as they are with cookbook_file (a logo, a certificate, a script).

Both folders support platform-specific subfolders (ubuntu, debian, ubuntu-24.04, default) that Chef searches from most specific to least.

libraries/, resources/ and definitions

  • libraries/ contains plain Ruby files loaded automatically before recipes. Put helper methods and classes here, for example a method that builds a connection string.
  • resources/ contains custom resources, each file defining one resource named after the cookbook and file (webserver_site). See Custom Resources.
  • Old cookbooks may have a definitions/ folder (macro-like blocks). They are deprecated in favor of custom resources.

Test files

Cookbooks include tests next to the code: kitchen.yml (Test Kitchen settings), test/integration/default/*_spec.rb or .rb InSpec controls, and optionally ChefSpec unit tests in spec/. The testing chapter returns to them.

Stand-in: a cookbook layout checker

The program below takes a list of file paths and reports whether the cookbook has the essentials. It is plain Ruby and not a Chef tool, but it makes the layout rules concrete.

Ruby Stand-in: check a cookbook layout

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.

The checker flags that the second cookbook lacks metadata.rb and a default recipe. Real Chef would refuse to upload a cookbook without metadata.

Generating more files

Rather than create folders by hand, use the generators (read-only):

Terminal
chef generate recipe webserver ssl
chef generate attribute webserver default
chef generate template webserver nginx.conf
chef generate file webserver logo.png
chef generate resource webserver site
chef generate helpers webserver nginx

Each command puts the file in the right folder and, where it can, adds a matching test.

Versioning and the changelog

Bump version in metadata.rb whenever a cookbook changes, because the server stores each version separately and nodes (or environments, see roles and environments) can pin to one. Keep a CHANGELOG.md so that others know what changed. Use semantic versioning: breaking change = major, feature = minor, fix = patch.

Ruby Stand-in: bumping a semantic version

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.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file is mandatory for a cookbook?

    The server and client need metadata.rb to identify the cookbook and its version.
  2. 2. What does recipe[webserver::ssl] load?

    cookbook::recipe maps to recipes/<recipe>.rb inside the cookbook.
  3. 3. Where do reusable helper methods and classes go?

    Files in libraries/ are loaded before recipes.
  4. 4. A breaking change in a cookbook should bump which part of the version?

    Semantic versioning increments the major number for breaking changes.

Summary

  • A cookbook has metadata.rb, recipes/, attributes/, templates/, files/, libraries/, resources/ and tests.
  • chef generate creates files in the right place.
  • cookbook::recipe maps to recipes/<recipe>.rb; default is implied.
  • Version cookbooks with semantic versioning and a changelog.

Next: Attributes and Precedence