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.

Attribute Type and Precedence

There are three types of attributes in order of precedence, highest to lowest.

• override
• normal
• default

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

A fourth attribute type, automatic, contains Ohai data and has the highest precedence. Chef doesn't provide any way to modify automatic attributes because any modifications you make will be overwritten with Ohai data again on the next run.

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"). The keys are also auto-vivified into accessor methods, which we'll talk about in a moment.

Setting Attributes

Chef 0.10.0 or above Environments attributes are only going to be available in Chef 0.10.0 or above.

Attributes may be set on the node from the following objects

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

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. Again, the exception to this are automatic attributes, as these are regenerated by Ohai every time Chef runs.

See examples here...

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.

Environment Attributes

Environments can set attributes, which is a kind of override attributes. This is done with the attributes method in an Environment's Ruby DSL file, or the attributes hashes in the Environment's JSON data. It is common to assign attributes that pertain to a particular environment. For example, the external load balancer's public DNS may be different in "production" than in "staging".

Role Attributes

Roles can only set default and override attributes, they cannot set normal attributes. This is done with the default_attributes and override_attributes methods in a Role's Ruby DSL file, or the default_attributes and override_attributes hashes in the Role's JSON data. It is common to assign attributes that pertain to a particular role. For example, a php_apache2_server role might use different tuning parameters for the same apache attributes than a mod_perl_apache2_server.

Node Attributes

Finally, the node object can be modified directly to set the attributes. Typically, this sets attributes at the normal priority level, and can be done by editing the node with knife or through the WebUI, or by passing JSON data to the node.

JSON Attributes

You can also specify node attributes with a JSON file. These are applied at the normal priority level.

For example, to set up some different ports for Apache to listen on:

Remember, that attributes passed via JSON file are merged with those stored on node and actually there is no way to override them in that way, however if there is a conflict, attributes from JSON file will win with those stored on node.

How to Use Attributes

Good candidates for Attributes are:

• Cross-Platform abstractions for an application such as the path to a config file.
• Default values for "tunable" settings such as memory assigned to processes or number of workers to spawn.
• Anything else you may want to persist (in node data) between Chef runs.

Usage Best Practices

The general pattern for attributes precedence is that cookbooks and roles should be setting defaults. If you need to change the values for a specific node, use, the normal attributes on the node. Overrides are there so roles can force a certain value even if the node already has a value there. There are certainly other ways to use it, but that is the pattern it was designed for.

Setting Attributes at the Same Precedence Level

A common use case is to set default attributes in a cookbook's attribute files, and also set the same default attributes, but with different values, using a role. In this scenario, the attributes set in the role will be deep merged on top of the attributes from the attributes file. The attributes set by the role will win if there is a conflict.

Setting a Value Only If the Attribute Has No Value

In attribute files, you can also set a value only if no value is currently set for that attribute using the _unless variants of the attribute priority methods: default_unless, set_unless, and override_unless. These can be handy in some use cases, but be careful! When you use these methods, the attributes applied to your nodes will become out-of-sync with the values in your cookbooks whenever you update your cookbooks. This means that building a new node with an identical set of recipes and roles as an existing node could result in a different configuration--a problem that can be frustrating to debug. For this reason, you should avoid using the _unless methods whenever possible.