Definitions

Definitions declarations must be placed in a definitions folder at the root of your cookbook. Do not declare them into a cookbook.

Definitions aren't resources

They are replaced by the resources they contain. You cannot notify a definition to take an action - you can only notify the resources it creates. If you do need to send actions to the resource, you should look in to creating a new Provider.

There are three components to a definition:
1. The resource name
2. The Prototype Parameters
3. The Params hash

You start with define, followed by the name of the new resource (apache_site). What follows is the Prototype Arguments for the definition - these are used to set default values for parameters within the definition.

Those parameters are then accessed within your definition via the params hash. Since this is a hash, each parameter must have a value. If no default value is specified, use nil.

Hey, CGI programmers... The params hash should look familiar to you - it's basically the exact same model we've been following ever since the CGI.pm days.

Example

This definition file creates a new resource apache_site:

We utilize it by placing the definition in the recipe:

We take the attributes of our new apache_site resource, and make them accessible via the params hash. This will be true of any attribute we set - you do not have to prototype all your parameters. Within the context of the Chef run, this definition will be replaced by all the resources you specify within the definition - in the "enabled" case, it is expanded to:

You can have as many resources in a definition as you want.

You can also pass data from various recipes to one definition.

Passing data from various recipes to one definition is possible. For example, you'd like to update your /etc/aliases, /etc/sudoers, or something similar, with entries from multiple recipes in a single chef run. Reopening resources is the way do this currently. Here's an example definition for adding email aliases (via Mithrandir on #chef):

Use Case Scenario

I've two applications to deploy/run using chef on a single node under the same domain/subdomain. One is a Rails app and another is a Wordpress blog app. The Rails app will reside as the main app at say `example.com` and the wordpress at `blog.example.com`. And lets assume that I'll be using Apache2 or Nginx as the webserver to handle the VirtualHost. I can create 2 separate run_list adding different roles to it. Later, when I have to add another app on the same domain, e.g. `forum.example.com` on the same node, I can create a separate run_list for this. But how do I update/ammend the VirtualHost of the web-server since its only one per node?

Definitions are a feature of Chef cookbooks that allow one to create "macros" for resources so they can be reused. The `web_app` definition exists in our apache2 cookbook, and can be used like this:

When Chef processes the recipe containing this, it sees web_app and looks to see if it recognizes it as a "resource". It will find it as loaded from the Opscode apache2 cookbook, and then process the template according to how the definition was written.

It is important to note that definitions aren't actually resources, and to Chef they are replaced by the resources they contain. They cannot be signaled directly with a notification, though the contained resources can.

We also have a (relatively old) blog post about this specific definition.

Setting Attributes (Examples)

File Distribution