Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Roles, Environments and Policyfiles

Roles and Run Lists

Learn how Chef roles bundle recipes and attributes, how run lists expand and run in order, the wrapper cookbook alternative, and expand a run list in Ruby.

You now know how a recipe configures one thing. A real server runs many of them: a base configuration for every machine, then a web server, then the application. A run list is the ordered list of recipes and roles that Chef applies to a node. A role is a named bundle of run-list entries and attributes, such as "every web server".

Roles were the classic way to describe what a server is. Today many teams prefer Policyfiles or wrapper cookbooks, but roles are everywhere in existing Chef code, and the ideas they teach (expansion, ordering, merging attributes) carry over. This lesson explains them with the real syntax and a runnable Ruby model of run-list expansion.

Chef cannot run on this site, so the role files and knife commands are read-only. The runnable code is a plain Ruby stand-in that expands a run list the way Chef does.

Run lists

A run list contains recipes and roles:

TEXT
recipe[base], role[web], recipe[myapp::deploy]
  • recipe[base] is base::default. recipe[myapp::deploy] is the deploy recipe of the myapp cookbook.
  • role[web] is replaced by the role's own run list.
  • Entries run in order, left to right, and a recipe runs only once per run even if two roles include it.

You can set the run list at bootstrap time or later:

Terminal
knife bootstrap 10.0.0.5 -N web01 -r 'recipe[base],role[web]'
knife node run_list add web01 'recipe[myapp::deploy]'
knife node show web01 -r

Defining a role

Roles are written in Ruby or JSON. The Ruby form is easier to read:

Ruby
name 'web'
description 'Nginx web server'
run_list 'recipe[nginx]', 'recipe[myapp::vhost]'
default_attributes(
  'nginx' => { 'worker_processes' => 2 }
)
override_attributes(
  'nginx' => { 'gzip' => 'on' }
)

Upload it with knife role from file roles/web.rb. A role has two attribute levels, default_attributes and override_attributes. The next lessons explain how they rank against other attribute sources.

Nested roles and expansion

Roles can include other roles, which lets you build layers:

flowchart TD
  N["node run list: role[webapp]"] --> R["role[webapp]"]
  R --> A["role[base]"]
  R --> B["recipe[nginx]"]
  R --> C["recipe[myapp]"]
  A --> D["recipe[users]"]
  A --> E["recipe[ntp]"]

Chef expands roles into one flat list of recipes: users, ntp, nginx, myapp.

When Chef starts a run, it expands the run list: it replaces each role with its entries, depth first, and drops duplicates (the first occurrence wins). The result is the flat expanded run list, which you can see in knife node show -l.

Ruby Stand-in: expand a run list

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 output lists apt::default, users::default, ntp::default, nginx::default, myapp::default and monitoring::agent. Notice ntp appears only once even though two entries requested it. The error for an unknown role mirrors Chef, which stops the run when it cannot resolve a role.

Roles in practice: the good and the bad

Roles are quick to set up but have weaknesses at scale:

  • They are global and mutable. Editing role[web] on the server changes every web node on the next run, with no version and no staging. A typo can break the fleet.
  • They live on the server, not in the cookbook. You need an upload step, and a node can reference a role that does not exist yet.
  • Attributes mix with cookbook logic. Overriding attributes in roles can surprise people who only read cookbooks.

A popular alternative is the role cookbook (also called a wrapper): a normal cookbook whose default recipe includes other recipes and sets attributes.

Ruby
# cookbooks/role_web/recipes/default.rb
include_recipe 'base'
node.default['nginx']['worker_processes'] = 2
include_recipe 'nginx'
include_recipe 'myapp::vhost'
Ruby
# cookbooks/role_web/metadata.rb
name 'role_web'
version '1.4.0'
depends 'base'
depends 'nginx', '~> 12.0'
depends 'myapp'

Now "web server" is versioned and tested like any cookbook, and Policyfiles (a later lesson) can lock it.

Run list checklist

  1. Put shared basics (base, users, time sync, monitoring) first.
  2. Keep roles small and single-purpose; combine them in a node's run list.
  3. Avoid using a role only to set one attribute; consider an environment or a wrapper.
  4. Check the expansion with knife node show NODE -l before a big change.
  5. Use chef-client --why-run to preview a new run list on a test node.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does recipe[myapp::deploy] refer to?

    The part before the double colon is the cookbook, the part after it is the recipe file name.
  2. 2. What happens if two roles both include recipe[ntp]?

    Chef removes duplicates in the expanded run list; the first occurrence determines the position.
  3. 3. What is a major drawback of server-side roles at scale?

    A role edit on the server takes effect on the next run of every node that uses it, with no version pinning.
  4. 4. Where do you see the flat list of recipes after expansion?

    knife node show with the long flag prints the expanded run list among other node data.

Summary

  • A run list is an ordered list of recipe[...] and role[...] entries for a node.
  • Roles bundle a run list and attributes; Chef expands nested roles into a flat list and runs each recipe once.
  • Roles are easy but global and unversioned; role cookbooks (wrappers) and Policyfiles are safer.
  • Order matters: put the base layer first and preview changes with --why-run.

Next: Environments and Version Constraints