Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 37 ยท Cookbooks and Attributes

Chef Attributes and Precedence

Learn Chef attributes: attribute files, default, force_default, normal, override and automatic levels, the 15-level precedence order, deep merging, and a runnable precedence model.

Attributes are the data of Chef: ports, package names, paths, feature flags, versions. They let one cookbook serve many nodes. The difficulty is that the same attribute can be set in several places (a cookbook, a role, an environment, the node itself, Ohai), so Chef has precise precedence rules deciding which value wins. This lesson explains the levels and then lets you run a model of the merge in Ruby. The real attribute system needs a node object, so real syntax is read-only.

Setting attributes

Inside an attribute file or a recipe you set an attribute by choosing a level and a path:

Ruby
default['webserver']['port'] = 80
default['webserver']['packages'] = %w(nginx)
override['webserver']['port'] = 8080
normal['webserver']['owner'] = 'deploy'

You read it from anywhere as node['webserver']['port']. Chef merges all levels into one view and the highest precedence wins.

The levels

There are five kinds of setting:

  • default: the normal choice for cookbook authors; easy to override.
  • force_default: a default that wins over normal too (rarely needed).
  • normal: set directly on a node (for example from first-boot.json) and persisted on it.
  • override: for settings that must win over defaults, usually in roles and environments.
  • force_override: wins over override (rarely needed).
  • automatic: set by Ohai; the highest precedence, read-only in practice.

Together with where they are set (attribute file, recipe, role, environment), they form 15 levels from lowest to highest:

# Level
1 default in a cookbook 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 (or set on the node directly)
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)

Higher numbers win. Check the official precedence table for your Chef version if exact order matters in your design, because it is the sort of detail that can change. A practical summary is enough for daily work: cookbook defaults are weakest, roles and environments adjust them, overrides are stronger, Ohai facts always win.

flowchart LR
  A["default (cookbook)"] --> B["default (role/env)"] --> C["normal"] --> D["override (role/env)"] --> E["automatic (Ohai)"]

Each step to the right beats the ones before it.

Deep merging

Hashes are merged, not replaced. If a cookbook sets default['app']['port'] = 80 and a role sets default['app']['workers'] = 4, the node sees both keys. Only when two levels set the same key does precedence choose. Scalar values are replaced by the highest level, while arrays need extra care, so always check the final value. Because merging can surprise you, test the final result with knife node show -l NODE or in a recipe Chef::Log.info(node['app'].to_hash).

Stand-in: the precedence resolver

The stand-in below stores settings with a level name and a source, merges nested hashes and resolves each key by the highest level. It uses a simplified order and is not Chef's real implementation, but it matches the behavior you need to predict.

Ruby Stand-in: resolve attribute 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.

Read the output: the environment override beats both defaults for port, the normal level beats the default for workers, and Ohai wins for platform no matter what a recipe tries to set.

A small deep-merge model

Now the merge part. Two hashes from different levels combine; the higher one wins on conflicts.

Ruby Stand-in: deep merge of hashes

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.

Every key survives, and level is debug because the last (highest) layer set it.

Good attribute design

  • Namespace under your cookbook name: node['webserver']['port'], never node['port'].
  • Use default in cookbooks. Reserve override for roles and environments that truly need to win; a cookbook using override makes life hard for its users.
  • Avoid normal unless you need persistence: normal attributes stay on the node even after you delete the code that set them, a source of hidden state. Prefer default plus a role.
  • Do not set attributes from the node's own state (circular logic), and keep attribute files free of side effects.
  • Document every attribute in the README with its default.

Reading node['x']['y'] when node['x'] does not exist raises an error (NoMethodError on nil). Use node.dig('x', 'y') or ensure the parent is defined in an attribute file.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which level is the highest, so cannot be overridden by recipes?

    Automatic attributes come from Ohai and have the highest precedence.
  2. 2. A cookbook sets default['app']['port'] = 80 and a role sets default['app']['port'] = 8080. What does the node see?

    The role-level default has higher precedence than the cookbook attribute-file default.
  3. 3. How are hashes from different levels combined?

    Chef merges nested hashes, so keys set at different levels all appear.
  4. 4. Which is a good practice for cookbook authors?

    default is easy to override and namespacing avoids collisions.

Summary

  • Attributes are set at levels (default, force_default, normal, override, force_override) and by location (file, recipe, role, environment); Ohai sets automatic ones.
  • Higher precedence wins; hashes are deep-merged.
  • Cookbooks should use namespaced default attributes; roles and environments adjust them.
  • Avoid normal and force levels unless you have a clear reason.

Next: Metadata and Dependencies