Cookbooks

Cookbooks are the way Chef and Hosted Chef users package up, distribute, and share configuration information. They encapsulate all the resources needed to automate your infrastructure, and are easily sharable with other Chef users as well.

They contain recipes, attribute files, templates, and other configuration artifacts.

When Chef-Client runs, recipes listed in the node's run list are transfered to the node, along with the other contents of the cookbook containing the recipe. These recipes are then applied to the node, bringing it into the proper configuration.

Typically, a single cookbook contains the information necessary to configure a single service or single part of the system. For instance, one may have a "users" cookbook for configuring the users who should have access to the system and an "apache" cookbook for configuring the apache web server.

Cookbooks can be authored by anyone with basic programming skills, and they can be written without storing any details about a particular deployed environment. This means they can be shared safely and reused across organization and company boundaries. Opscode encourages users to publish their cookbooks on the Opscode Community Site, where there are already over 300 cookbooks to choose from. As a result, you can install and configure many commonly used technologies without ever having to write a new cookbook.

If your Chef repository is using git (see Creating a Chef Repository for details), you can quickly obtain and use cookbooks written by the community using Chef's command line tool, Knife. For instance, to download the simple "getting-started" cookbook, run the following from a chef repository:

To upload it to a Chef Server or Hosted Chef:

And, to add the "default" recipe inside this cookbook to the run list of a node:

Chef also provides tools to make it easier to create new cookbooks. For instance, to create the basic structure of a new cookbook within your Chef Repository, you can use knife:

Recipes

Recipes are Ruby files in which you use Chef's Domain Specific Language (DSL) to define how particular parts of a node should be configured. As will be seen in later sections, you can use data, combined with the ability to use ruby code within recipes to dynamically change a node's configuration.

Cookbooks can contain multiple recipes, with the recipes added to a run list by their full name using the form COOKBOOK_NAME::RECIPE_NAME. Only roles and recipes are added to a run list.

Chef however provides a shortcut notation to name recipes and cookbooks in a run list command. (This is useful for the recipe that serves as a base configuration for a set of nodes.)

When you add COOKBOOK_NAME to a run list, Chef assumes that you want the recipe named "default" within the named cookbook. To see an example of this, we could modify the knife command used above to add a recipe to a node's run list. Using this shortcut, we can simplify the command given above:

In this updated example, you've added the "default" recipe within the "getting-started" cookbook to the run_list of "my_node", just as before.

Resources and Providers

Resources are the building blocks you will use to to create a properly configured node. They are cross platform abstraction of that which you are configuring on the node - discrete chunks of a system's configuration that are placed in recipes and applied to your nodes.

The key feature of resources is that they allow you to focus on describing the node's configuration rather than the specifics of how a given task is accomplished.

For example, the following resource adds a user to a node:

This resource describes a user, "sam", that we would like to create on our node. The actual creation is performed by a Provider which executes the necessary commands to create a new user.

An individual resource can have multiple providers, each of which knows how to perform the necessary task on a different platform. Chef-client will choose the best provider for the node's platform. Thus, this single resource description can be used to create the user "sam" on a Linux system and a FreeBSD system, without any modification.

The user resource above is structured like all resource descriptions in the Chef Domain Specific Language (DSL):

A resource type corresponds to the kind of resource that you need to configure. Many different resources are defined by the Chef DSL. A full list of these resources can be found on the Resources page. As you advance to more complex uses of Chef, you can even extend the Chef DSL with your own resources.

The resource name is a string that identifies this specific instance of a resource. For a given node's configuration you may need to define many user resources, each of which will have their own name and can be referred to by other resources. The resource name is also, by default, used as the value for one of the resource's "resource attributes". For example, in the user resource defined above, the name "sam" will be used as the username for the user chef-client will create.

Resource attributes and the associated values describe the desired state of the resource. Each resource has different attributes that are meaningful in the context of the given resource. The "action" attribute is an attribute used by all resources and defines what ought to be done with the resource. In our example above, we used the "create" action to indicate we want the user to be created. When sam leaves our organization, we may change this action to ":delete" to remove her user.

The available resource attributes and their default values are described in detail for each resource on the Resources page.

When chef-client loads the recipes in its run list,

1. It runs each recipe as a piece of ruby code.
2. Each time a resource is used, it is added to a collection of resources for that node.
3. The providers of these resources then decide whether or not action is needed to fulfill the resources' description.

In this way, a core principal of Chef is achieved: idempotency. Idempotency ensure that a resource can be applied to a machine multiple times and always have the same result: a properly configured machine.

Attributes and Templates

Attributes provide a nested key-value store of data about a node and its configuration. Some attributes are collected automatically at the start of each chef-client run and include information such as the nodes IP address, hostname, or loaded kernel modules. Other attributes are added from other sources such as cookbooks. (Roles and Environments can also set attributes, two features of Chef that are talked about in other sections.)

Attributes allow you to change configuration based on the characteristics of a node and set sane defaults for service configurations while also allowing them to be easily changed. One way to set attributes is from an attribute files within a cookbook.

For example the following sets some sane defaults for the location of a particular configuration file:

This attribute could then be used directly in a resource controlling the configuration file:

This defines a Template, which is a feature of Chef that allows you to create general files whose contents can be generated dynamically. If this configuration file was referenced multiple times in a recipe, changing its location is now a matter of changing a single attribute.

Node attributes also contain information about the node that can be used in recipes:

This would allow a recipe to do some set of configuration tasks only if it was running on Amazon's EC2 cloud. For complete documentation on Attributes see Attributes.

Roles

Configuring a single node may involve many different cookbooks. In order to group similar features of similar nodes, Chef provides Roles. Roles contain a run list (just like a node) and attributes pertaining to a specific function. For example, you may create a "webserver" role that would contain a run list with all of the services needed on a typical webserver within your infrastructure. A node's run list can contain these roles.

When a node's run list contains a role, the run list from the role itself is expanded and added to the node's run list, ensuring that all of the recipes for a given role are applied to the node.

Roles can also set attributes. Setting attributes in a roles allows you to override the default attribute of a general-purpose cookbook with values more appropriate for a node with a particular role.

Environments

Environments in Chef provide a mechanism for managing different environments such as production, staging, development, and testing, etc within one Chef Server or Hosted Chef organization. With environments, you can specify per environment run lists in roles, per environment cookbook version constraints, and environment attributes. Roles differ in that they are groupings of systems that perform a like function and which can span environments - for example: application server, web server, database server. Thus you can have per-environment run lists within roles - for example: in your development environment you want your application server to connect to a different load balancer than you do in your test environment, and this can be managed within a single recipe.

You can create and manage environments in multiple ways, thereby tailoring their use to your needs and infrastructure. See Environments for more details.

Summary

• Cookbooks contain recipes, attribute files, and other configuration information.
• Resources are the building blocks of recipes and describe a discrete piece of a Node's configuration.
• Resources are idempotent. Applying the same resource to a node twice should have the same result.
• Providers take the necessary actions required to ensure the Node's state matches the resource description.
• Attributes provide tunable parameters that can be used within a recipe as well as information about the node.
• Roles provide a way to describe a particular function or type of node. Roles have run_lists and attributes.
• Environments provide the means of managing different infrastructure spaces within one Chef instance.

Onward!

Now on to two of Chef's most Powerful Features:

• Next Steps: Introduction to Search and Data Bags

Advanced Reading

• Cookbooks
• Resources
• Providers
• Attributes
• Roles
• Templates
• Environments

Core Components

Introduction to Search and Data Bags