Cookbook Attributes

Overview

Attributes are Node data such as the IP address, hostname, loaded kernel modules, version of programming languages available on the system and more. New attributes can be dynamically added to the node in a variety of ways.

During the Chef run, the Chef Client saves these node attributes on the Chef Server where they are indexed for Search. When the Chef Client runs again, it will retrieve the attributes that were saved previously and merge in attributes based on the priority rules described below.

Setting Attributes

Attributes may be set on the node from the following objects

• cookbooks
• environments (Chef 0.10.0 or above only)
• roles
• nodes

Precedence

The precedence of the attributes is as follows, from low to high:

• default attributes applied in an attributes file
• default attributes applied in an environment
• default attributes applied in a role
• default attributes applied on a node directly in a recipe
• normal or set attributes applied in an attributes file
• normal or set attributes applied on a node directly in a recipe
• override attributes applied in an attributes file
• override attributes applied in a role
• override attributes applied in an environment
• override attributes applied on a node directly in a recipe

default attributes applied in an attributes file have the lowest priority and override attributes applied on a node directly in a recipe have the highest priority.

Write your cookbooks with default attributes, but override these with role-specific or node-specific values as necessary.
See examples here...

The exception to this are Automatic Attributes. They have the highest precedence and may not be modified, as they are regenerated by Ohai every time Chef runs.

Notation

Attributes are a special key-value store called a Mash within the Ruby DSL context. A Mash is just a Hash where the key can be either a Ruby symbol (:key) or a string ("key"). It's easier to stick with string notation if you are just starting out with Chef and/or Ruby. This allows you to just "quote it", rather than also having to learn about special cases, name space overlap (and method_missing), character constraints, and escaping work at the beginning.

That way, by the time you may want to use symbols stylistically or contextually, you can learn to wield them with an existing base of knowledge. Our examples and detail on attributes use a string notation for that reason. If you already know your way around symbols in ruby, you may of course use them.

Cookbook Attributes

Cookbook attribute files are found in the attributes subdirectory of the cookbook. They are evaluated in the context of the Node object and Node methods are used to set attribute values.

e.g. from Opscode's Apache cookbook:

The use of the node object is implicit here. The following is equivalent:

Attributes can be set in a recipe as well, but node must be used.

Cookbook Attribute Methods

Use the following methods within a cookbook's attributes file or in a recipe. They correspond to the attribute type of the same name (set is an alias for normal).

• override
• default
• normal (or set)

Additionally, there are _unless methods available. See the end of this document for information on conditionally setting attributes

Another handy method available related to attributes is the attribute? method. This will check for the existence of an attribute, so you can do processing in an attributes file or recipe only if a specific attribute exists.

In the recipe, we need to use the method on the node object. In the attributes file, the node object is implicit. In either, we can also look for a sub-key of an attribute by chaining the attribute as methods:

Cookbook Attribute File Ordering

When Chef loads cookbook attribute files, it does so in alphabetical order for all the cookbooks. If you need to ensure that one attribute file is loaded before another (for example, if your Rails cookbook requires that the Apache attributes are available first) you can use the include_attribute method, like so:

This loads apache/attributes/default.rb before continuing the processing of the current attribute file.

The syntax for this follows the same "double colon" pattern as include_recipe, so a statement like:

This loads the attributes/tunables.rb file in a rails cookbook.

Reloading Attribute Files From Recipes

Attributes sometimes depend on actions taken from within recipes, so it may be necessary to reload a given attribute from within a recipe. For example: if you have an attribute that reads firewall rules, and a recipe that installs a firewall package, the firewall attributes will not be set the first time you execute the cookbook. Since include_attribute is not available from inside recipes, you will need to manually reload your firewall::default attribute:

Attribute Accessor Methods

Attribute accessor methods are automatically created and the method invocation can be used interchangeably with the keys. The following is equivalent to the usage above:

This is a matter of style, and may be seen when "retrieving" the value of an attribute.

Cookbooks

Setting Attributes (Examples)