Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Section
Column
width3%
 
Column
Panel

This content has been moved to docs.opscode.com

See the following links:

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.

Column
width2%
 
Column
width30%
Panel
bgColor#d7d4c3
Table of Contents
printableno
maxLevel3
minLevel1
Note
titleEarly Bird Pricing for #ChefConf ends March 10th

Presentations on best practices for using Chef in IT operations, cloud architecture, and application development from over 30 companies, including Facebook, General Electric, Nordstrom, Forrester Research, Riot GamesAncestry.com, Edmunds, Kickstarter, Message Bus, Nordstrom, Riot Games and Splunk.

April 24-26, 2013 San Francisco, California

Register today

 

 

Warning
titleAttributes that Aren't

A number of pieces of data related to a node are methods rather than attributes. As such, they cannot be accessed using the syntax for attributes, but rather must be accessed as method. Important node methods include:

Code Block

node.name
node.run_list
node.chef_environment
Column
width5%
 
Section
Column
width3%
 
Column

Attribute Persistence

Float
right
background#f4f2e6
width360px
background#f4f2e6
margin8px
padding2px
Center
Info
title0.10.x behavior

The behavior described in this section refers to the behavior of Chef 0.10+.

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.

Include Page
Attributes Cookbook
nopaneltrue

Environment Attributes

Float
right
background#f4f2e6
width360px
background#f4f2e6
margin8px
padding2px
Center
Tip
titleChef 0.10.0 or above

Environments attributes are only available in Chef 0.10.0 or above.

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

Float
right
width340px
background#eeeeee
marginwidth10px340px
paddingmargin10px
border4px solid #d7d4c3
padding10px
Center
You can have deep merged Attributes
Center
Deep merging allows you to layer 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.

Code Block
knife node edit <fqdn>

This example adds the company attribute to a node

Code Block
{
  "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.

Code Block

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:

Code Block
javascript
titleJSON attribute example
linenosfalse

{ "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

Tip
titleGood Candidates for Attributes
  • 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.

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:

Code Block
# 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.


Column
width5%
 
Section

Column
width45%

Image Modified Chef Essentials

Column
width40%
 
Column
width15%

Image Modified Automatic Attributes