Roles in Chef provide a mechanism for easily composing sets of functionality for each of your nodes through recipes and attributes. Nodes can have multiple roles applied, and they will be expanded in place, providing for a complete recipe list for that node. For example, let's say I have a list of recipes that should be applied on all my Ubuntu servers, and a list that is specific to machines that are Web Servers. This would map cleanly to two roles: 'ubuntu' and 'web_server'. Each role would specify the list of recipes it requires, in the order they should be applied. Where there is overlap (i.e., a recipe appears twice) it will be run when the first role is expanded (not run twice.) You can create roles in Chef in 4 different ways: through the creation of role files in your chef repository (that utilize a ruby DSL, which gets compiled to JSON,) the creation of the JSON files directly in your chef repository, through the Management Console, or through the REST API. We will cover each option here. Once you have created a role, you can add it to a node through the Management Console by dragging it from the Roles list to the client's "run list", or you can add it with a JSON file. Roles work with chef-solo too! You can use Roles with Chef Solo as well as the Client/Server. See the Chef Solo documentation. Choose Your Workflow There are two workflows you can use to manage your roles: you can either write your roles as ruby or JSON files and push them to the server, or you can create roles with Knife or the Management Console and edit them as you go along. If you manage roles with files: You can use the ruby DSL or JSON Your roles will be useable with chef-solo You can dynamically generate role data using the ruby DSL You can keep your roles in your version control system and have a history of who changed what and when. You should not edit roles with the Management Console, as your edits will be overwritten next time you upload from the file. If you manage roles with knife and the Management Console: You can edit a role's run list visually with the Management Console You can make changes to a role "on the fly" The canonical source of a role's data will be the Chef Server, which makes it difficult to keep in version control You cannot use the ruby DSL. You cannot use your roles with chef-solo These workflows are mutually exclusive: if you upload a role to your Chef server from a file, then edit it with the Management Console, and then edit the file and upload again, the changes you made with the Management Console will be lost. The Ruby DSL Roles created through this mechanism get compiled to JSON, and then are loaded in to the Chef Server. (We never execute ruby code directly on the chef server!) Each time you rake install your Chef Repository, we will re-compile the corresponding JSON and store it in the chef server. You should create these files in the 'roles' subdirectory of your chef repository - if you are using the opscode canonical Chef Repository as a baseline, the latest version includes this directory and rake tasks to manipulate roles as documented on the repository page. If your repository doesn't have this directory, create it now. Each DSL file should have a .rb suffix.

Table of Contents Choose Your Workflow The Ruby DSL name description run_list default_attributes override_attributes As JSON json_class chef_type Managing Roles through Knife Creating a role with Knife Editing a role with Knife Viewing a role with Knife Listing roles with Knife Deleting a role with Knife Managing Roles through the Management Console The REST API

A complete role file looks like this:

We'll go over each section below.

name

Each role must have a unique name, which is made up of [A-Z][a-z][0-9] and [_-]. Spaces are not allowed.

description

A short description of what functionality is covered by this role.

run_list

In Chef 0.8.x, the recipes attribute is replaced with a run_list, which is identical to the one you specify for Node.

This is the list of recipes or roles to apply for this role, in the order they should be applied.

Would apply the "apache2" recipe, the "apache2::mod_ssl" recipe, and then anything required by the role "monitor".

Note: You may also see recipes used in place of run_list. These are equivalent in function, though recipes is deprecated. Use run_list instead.

default_attributes

An optional set of attributes that should be applied to all nodes with this role, assuming the node does not already have a value for that attribute. Use this to set site-wide defaults that can be overridden on a node-specific basis. The merge is 'deep', meaning that we will preserve nested attributes properly.

In the above example, all nodes with this role would have node[:apache2][:listen_ports] set to '80' and '443', assuming they do not already have a value.

If more than one role attempts to set a default value for the same attribute, the last role applied will win.

override_attributes

An optional set of attributes that should be applied to all nodes with this role, regardless of whether a node already has a value for that attribute. Useful for setting site-wide values that will always be set. The merge is 'deep', meaning that we will preserve nested attributes properly.

In the example above, node[:apache2][:max_children] will always be set to '50'.

If more than one role attempts to set an override value for the same attribute, the last role applied will win.

To override a nested attribute, use the following syntax:

Multiple attributes can be overridden like this:

As JSON

The JSON format for roles maps directly to the Ruby DSL above. For the role we describe in that section, the corresponding JSON is:

The two additional fields are described below.

json_class

This should always be set to Chef::Role. This is used internally by Chef to auto-inflate this type of object. It should be ignored if you are re-building objects outside of Ruby, and its value may change in the future.

chef_type

This should always be set to role. This is the field you should rely on if you are building a system to consume Roles outside of Ruby.

Managing Roles through Knife

Knife is Chef's command line tool. Roles can be managed through Knife.

Creating a role with Knife

1. set EDITOR environment variable, for example:

2. create a new role, for example:

3. enter the data of the role in JSON, for example:

4. Save it. If there isn't an existing role with the same name, you will see a warning message about that, which is normal. For example:

Editing a role with Knife

1. set EDITOR environment variable, for example:

2. edit a role, for example:

3. Update the JSON in the editor.
4. Save it.

Viewing a role with Knife

Listing roles with Knife

Deleting a role with Knife

Managing Roles through the Management Console

You can create and manage roles through the Management Console. Please refer to the Managing Roles through the Management Console articles for information about this topic.

The REST API

You can also create and manage roles directly in a running Chef Server via the REST API. Please refer to the Server API article for information.