About Cookbooks
A cookbook is the fundamental unit of configuration and policy distribution in Chef Infra.
A cookbook defines a scenario and contains everything that is required to support that scenario:
- Recipes that specify which Chef Infra built-in resources to use, as well as the order in which they are to be applied
- Attribute values, which allow environment-based configurations such as
devorproduction. - Custom Resources for extending Chef Infra beyond the built-in resources.
- Files and Templates for distributing information to systems.
- Custom Ohai Plugins for extending system configuration collection beyond the Ohai defaults.
- The
metadata.rbfile, which describes the cookbook itself and any dependencies it may have.
Chef Infra Client runs a recipe only when instructed. When Chef Infra Client runs the same recipe more than once, the results will be the same system state each time. When a recipe is run against a system, but nothing has changed on either the system or in the recipe, Chef Infra Client will not change anything.
Components
A cookbook is comprised of recipes and other optional components as files or directories.
| Component | File/Directory Name | Description |
|---|---|---|
| Recipes | recipes/ | A recipe is the most fundamental configuration element within the organization. A recipe:
|
| Attributes | attributes/ | An attribute can be defined in a cookbook (or a recipe) and then used to
override the default settings on a node. When a cookbook is loaded
during a Chef Infra Client run, these attributes are compared to the
attributes that are already present on the node. Attributes that are
defined in attribute files are first loaded according to cookbook order.
For each cookbook, attributes in the default.rb file are loaded first,
and then additional attribute files (if present) are loaded in lexical
sort order. When the cookbook attributes take precedence over the
default attributes, Chef Infra Client applies those new settings and
values during a Chef Infra Client run on the node. |
| Files | files/ | A file distribution is a specific type of resource that tells a cookbook how to distribute files, including by node, by platform, or by file version. |
| Libraries | libraries/ | A library allows the use of arbitrary Ruby code in a cookbook, either as a way to extend the Chef Infra Client language or to implement a new class. |
| Custom Resources | resources/ | A custom resource is an abstract approach for defining a set of actions and (for each action) a set of properties and validation parameters. |
| Templates | templates/ | A template is a file written in markup language that uses Ruby statements to solve complex configuration scenarios. |
| Ohai Plugins | ohai/ | Custom Ohai plugins can be written to load additional information about your nodes to be used in recipes. This requires Chef Infra Server 12.18.14 or later. |
| Metadata | metadata.rb | This file contains information about the cookbook such as the cookbook name, description, and version. |
Community Cookbooks
Chef maintains a large collection of cookbooks. In addition, there are thousands of cookbooks created and maintained by the community:
| Components | Description |
|---|---|
| Cookbooks Maintained by Chef | Chef maintains a collection of cookbooks that are widely used by the community. |
| Cookbooks Maintained by Sous Chefs | Sous Chefs is a community organization that collaborates to maintain many of the most used Chef cookbooks. |
| Cookbooks Maintained by the Community | The community has authored thousands of cookbooks, ranging from niche cookbooks that are used by only a few organizations to popular cookbooks used by almost everyone. |
Generate a Cookbook
Use the chef generate cookbook subcommand to generate a cookbook.
A cookbook generated withchef generate cookbook custom_web creates a cookbook named custom_web with the directory structure:
. cookbooks
└── custom_web
├── CHANGELOG.md
├── LICENSE
├── Policyfile.rb
├── README.md
├── chefignore
├── compliance
│ ├── README.md
│ ├── inputs
│ ├── profiles
│ └── waivers
├── kitchen.yml
├── metadata.rb
├── recipes
│ └── default.rb
└── test
└── integration
└── default
└── default_test.rb