Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 37 ยท Roles, Environments and Policyfiles

Attribute Precedence with Roles and Environments

Learn the 15 Chef attribute precedence levels, how roles and environments fit in, how hashes are deep merged, and how to debug where a value came from.

A single attribute such as node['nginx']['worker_processes'] can be set in many places: the cookbook, a recipe, a role, an environment, even Ohai (the tool that detects facts about the machine). When two places disagree, Chef must choose. The rules for choosing are called attribute precedence, and they are one of the most common sources of "why does my node have this value?" questions.

This lesson gives you the full list, a mental model that makes it easy to remember, and a runnable stand-in that merges the levels the way Chef does. You will also learn the tools for finding where a value really came from.

Real Chef is not available on this site, so the cookbook and knife code is read-only. The merging stand-in is plain Ruby and models the ordering and hash merging described here.

Two ideas: type and source

Every attribute assignment has a type (default, normal, override, plus force_default, force_override and automatic) and a source (an attribute file, a recipe, a role, an environment, Ohai). Precedence is mostly decided by type; within the same type, the source matters.

Ruby
# in an attributes/default.rb file
default['myapp']['port'] = 8080

# in a recipe
node.default['myapp']['port'] = 9090
node.override['myapp']['debug'] = true

A short summary:

  • default: a polite suggestion. Anyone can replace it.
  • normal: a value stored on the node and kept between runs (set with knife node edit or -j).
  • override: a strong demand. It beats everything except force_override and automatic.
  • automatic: facts from Ohai, such as node['platform']. You cannot change these.

The 15 levels, lowest to highest

# Type and source
1 default in the cookbook's attribute file
2 default in a recipe
3 default in an environment
4 default in a role
5 force_default in an attribute file
6 force_default in a recipe
7 normal in an attribute file
8 normal in a recipe
9 override in an attribute file
10 override in a recipe
11 override in a role
12 override in an environment
13 force_override in an attribute file
14 force_override in a recipe
15 automatic (Ohai)

The higher number wins. Notice the interesting twist: for default, the role beats the environment; for override, the environment beats the role. So a role is the better place to set a default that a cookbook author should be able to override, while an environment override is hard to beat.

Remember it in three steps: type first (default < normal < override < automatic), then, inside default and override, attribute files < recipes < environments/roles.

Merging hashes

Attributes are nested hashes. Chef does not pick one whole hash; it deep merges them. If the cookbook default sets nginx.worker_processes and the role sets nginx.gzip, the node gets both keys. Only when the same key is set at several levels does the higher level win.

Ruby Stand-in: merge attribute levels by precedence

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.

You can read the story in the output: each step adds a new source and the visible value moves up or stays the same according to the table. The worker_processes value ends as 3 because an environment override outranks the node's normal attribute.

Why normal attributes are a trap

A normal attribute is saved in the node object on the server. If you set node.normal['myapp']['port'] = 9090 in a recipe once, the value stays after you delete that line, because it is stored. This leads to servers that behave differently from what the cookbook says. Most teams avoid normal in recipes and use default (for suggestions) or override (for requirements). Remember too that node['x'] reads the merged value, while node.default['x'] = ... writes to a specific level.

Chef also keeps the types separate: setting node['x'] = 1 (no type) is an error in newer Chef versions when the key already exists at another level. Always name the type when writing.

Tools for debugging

Terminal
knife node show web01 -l                    # full node object, with every level
knife node show web01 -a nginx.worker_processes

In a recipe or in chef-shell you can ask the node where a value came from:

Ruby
Chef::Log.info(node.debug_value('nginx', 'worker_processes').inspect)

debug_value lists every level and shows which one is the effective value. When a node surprises you, run it and read the list from top to bottom.

Design guidance

  • Cookbook attribute files: set defaults only. They define the interface of the cookbook.
  • Roles and environments: set default or override for values that differ by group; prefer environments for stage differences and roles for kind-of-server differences.
  • Avoid force_ types except in emergencies; they ignore the normal ordering.
  • Never rely on subtle ordering between a role default and an environment default. If two places fight, move the value to one place.
  • Write the final merged values to a log line while debugging a new cookbook.
flowchart LR
  A["cookbook attributes"] --> M["deep merge by level"]
  B["role"] --> M
  C["environment"] --> M
  D["node (normal)"] --> M
  E["Ohai (automatic)"] --> M
  M --> N["node['key'] used by recipes and templates"]

Recipes only ever read the merged result.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which wins between a default in a role and a default in an environment?

    At the default level the role ranks above the environment (level 4 versus level 3).
  2. 2. Which wins between an override in a role and an override in an environment?

    For overrides the order flips: the environment override (level 12) ranks above the role override (level 11).
  3. 3. Why are normal attributes risky in recipes?

    Normal attributes are saved with the node, so removing the recipe line does not remove the stored value.
  4. 4. How does Chef combine two hashes set at different levels?

    Hashes are merged key by key. Only conflicting keys are decided by precedence.
  5. 5. Which tool shows the levels that contributed to a value?

    debug_value lists each level and the value found there, which shows the winner.

Summary

  • Attributes have types (default, normal, override, force variants, automatic) and sources; 15 levels decide the winner.
  • Role beats environment for defaults, environment beats role for overrides.
  • Hashes are deep merged, so different levels can each add keys.
  • Use default in cookbooks, avoid normal in recipes and force_* almost always.
  • Debug with knife node show -l and node.debug_value.

Next: Policyfiles and Dependency Locking