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 four types of attributes in order of precedence, highest to lowest.

• automatic
• 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. Review Automatic Attributes for those reserved namespaces.

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.

Attribute Persistence

At the beginning of each chef-client run, default, override, and automatic attributes are completely reset.
They are then rebuilt using the currently applicable cookbooks, recipes, roles, environment and Ohai data.
Thus, default and override attributes set in cookbook attribute files, roles, recipes, or environments will disappear once the recipe, role, or environment is removed from the node and chef-client is run on the node.

Normal attributes are not reset.
Rather, on each chef-client run, any new attributes passed to chef-client in a JSON file are merged with the existing normal attributes in the node's data(using Deep Merge).
This means that any normal attribute set in a recipe or cookbook attribute file will remain even after the cookbook or role has been removed from the node's run list.

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:

1. default attributes applied in an attributes file
2. default attributes applied in an environment
3. default attributes applied in a role
4. default attributes applied on a node directly in a recipe
5. normal or set attributes applied in an attributes file
6. normal or set attributes applied on a node directly in a recipe
7. override attributes applied in an attributes file
8. override attributes applied in a role
9. override attributes applied in an environment
10. override attributes applied on a node directly in a recipe
11. automatic attributes generated by Ohai

default attributes applied in an attributes file have the lowest priority and override attributes applied on a node directly in a recipe automatic attributes generated by Ohai 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...

Again, 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.

Environment Attributes

Environments can set default and override attributes.

This is done with the default_attributes and override_attributes methods (respectively) in an Environment's Ruby DSL file, or the default_attributes and override_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.

knife node edit <fqdn>

This example adds the company attribute to a node

{
  "name": "somenode.somewhere.local",
  "normal": {
    "company": "OpsCode",
    "tags": [

    ]
  },
  "chef_environment": "_default",
  "run_list": [
  ]
}

JSON Attributes

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

chef-client --help
[...]
    -j JSON_ATTRIBS                  Load attributes from a JSON file or URL
        --json-attributes

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

{ "apache": { "listen_ports": ["81", "8080"] } }

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.

Automatic Attributes

This fourth attribute type cannot be modified, as any modifications you make will be overwritten with Ohai data again on the next run.

How to Use Attributes

Atrributes can be used in recipies. E.g. if you want to insert a numeric id into a configuration file, it can be set as a node attribute and used as follows:

# Check if bbid isn't the default value
if (node.bbid != "none") then

  # Install the client
  package "boxbackup-client" do
    action  :install
  end

  # Create a configuration file with the nodeid in it
  template "/etc/boxbackup/nodeid.txt" do
    source "nodeid.txt.erb"
    variables(
      :nodeid => node.bbid
    )
  end

end

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.

Image Modified Chef Essentials

Image Modified Automatic Attributes