Skip to main content

About Nodes

A node is any device—physical, virtual, cloud, network device, etc.—that is under management by Chef Infra.

The types of nodes that can be managed by Chef include, but are not limited to, the following:

Node TypeDescription

A physical node is typically a server or a virtual machine, but it can be any active device attached to a network that's capable of sending, receiving, and forwarding information over a communications channel. In other words, a physical node is any active device attached to a network that can run a Chef Infra Client and also allow that Chef Infra Client to communicate with a Chef Infra Server.

A cloud-based node is hosted in an external cloud-based service, such as Amazon Web Services (AWS), OpenStack, Rackspace, Google Compute Engine, or Microsoft Azure. Plugins are available for knife that provide support for external cloud-based services. knife can use these plugins to create instances on cloud-based services. Once created, Chef Infra Client can be used to deploy, configure, and maintain those instances.

A virtual node is a machine that runs only as a software implementation, but otherwise behaves much like a physical machine.

A network node is any networking device---a switch, a router---that's being managed by a Chef Infra Client, such as networking devices by Juniper Networks, Arista, Cisco, and F5. Use Chef to automate common network configurations, such as physical and logical Ethernet link properties and VLANs, on these devices.

Containers are an approach to virtualization that allows a single operating system to host many working configurations, where each working configuration---a container---is assigned a single responsibility that's isolated from all other responsibilities. Containers are popular as a way to manage distributed and scalable applications and services.

The key components of nodes that are under management by Chef include:



Chef Infra Client is an agent that runs locally on every node that is under management by Chef Infra Server. When Chef Infra Client runs, it performs all of the steps required for bringing a node into the expected state, including:

  • Registering and authenticating the node with Chef Infra Server
  • Synchronizing cookbooks from the Chef Infra Server to the node
  • Compiling the resource collection by loading each of the required cookbooks, including recipes, attributes, and all other dependencies
  • Taking the appropriate and required actions to configure the node based on recipes and attributes
  • Reporting summary information on the run to Chef Automate
Chef Infra Client authenticates with the Chef Infra Server using RSA public key-pairs each time a Chef Infra Client needs access to data that is stored on the Chef Infra Server. This prevents any node from accessing data that it shouldn’t and it ensures that only nodes that are properly registered with the Chef Infra Server can be managed.


Ohai is a tool for collecting system configuration data, which it then provides to Chef Infra Client to use in cookbooks. Chef Infra Client runs Ohai at the start of every Chef Infra run to determine system state. The attributes that Ohai collects are called automatic attributes. Chef Infra Client uses these attributes to ensure that nodes are in the desired state after each configuration run.

The types of attributes Ohai collects include but are not limited to:

  • Operating System
  • Network
  • Memory
  • Disk
  • CPU
  • Kernel
  • Host names
  • Fully qualified domain names
  • Virtualization
  • Cloud provider metadata

Ohai includes required and optional plugins to detect common configuration information. Ohai has a plugin model and language to write custom plugins to collect additional system state information.

Node Names

The name of a node is required as part of the authentication process to the Chef Infra Server. The name of each node must be unique within an organization, but otherwise can be any string that matches the following regular expression:


The name of a node can be obtained from the node_name attribute in the client.rb file or by allowing Ohai to collect this data during a Chef Infra Client run. When Ohai collects this data during a Chef Infra Client run, it uses the node’s FQDN, which is always unique within an organization, as the name of the node.

Using the FQDN as the node name, and then allowing Ohai to collect this information during each Chef Infra Client run, is the recommended approach and the easiest way to ensure that the names of all nodes across the organization are unique.

Node Objects

For Chef Infra Client, two important aspects of nodes are groups of attributes and run-lists. An attribute is a specific piece of data about the node, such as a network interface, a file system, the number of clients a service running on a node is capable of accepting, and so on. A run-list is an ordered list of recipes and/or roles that are run in an exact order. The node object consists of the run-list and node attributes, which is a JSON file that is stored on the Chef Infra Server. Chef Infra Client gets a copy of the node object from the Chef Infra Server during each Chef Infra Client run and places an updated copy on the Chef Infra Server at the end of each Chef Infra Client run.

An attribute is a specific detail about a node. Attributes are used by Chef Infra Client to understand:

  • The current state of the node
  • What the state of the node was at the end of the previous Chef Infra Client run
  • What the state of the node should be at the end of the current Chef Infra Client run

Attributes are defined by:

  • The node as saved on the Chef Infra Server
  • Attributes passed using JSON on the command line
  • Cookbooks (in attribute files and/or recipes)
  • Policyfiles

During every Chef Infra Client run, Chef Infra Client builds the attribute list using:

  • Attributes passed using JSON on the command line
  • Data about the node collected by Ohai.
  • The node object that was saved to the Chef Infra Server at the end of the previous Chef Infra Client run.
  • The rebuilt node object from the current Chef Infra Client run, after it is updated for changes to cookbooks (attribute files and/or recipes) and/or Policyfiles, and updated for any changes to the state of the node itself.

After the node object is rebuilt, all of the attributes are compared, and then the node is updated based on attribute precedence. At the end of every Chef Infra Client run, the node object that defines the current state of the node is uploaded to the Chef Infra Server so that it can be indexed for search.


An attribute is a specific detail about a node, such as an IP address, a host name, a list of loaded kernel modules, the version(s) of available programming languages that are available, and so on. An attribute may be unique to a specific node or it can be identical across every node in the organization. Attributes are most commonly set from a cookbook, by using knife, or are retrieved by Ohai from each node before every Chef Infra Client run. All attributes are indexed for search on the Chef Infra Server. Good candidates for attributes include:

  • any cross-platform abstraction for an application, such as the path to a configuration file
  • default values for tunable settings, such as the amount of memory assigned to a process or the number of workers to spawn
  • anything that may need to be persisted in node data between Chef Infra Client runs

In general, attribute precedence is set to enable cookbooks and roles to define attribute defaults, for normal attributes to define the values that should be specific for a node, and for override attributes to force a certain value, even when a node already has that value specified.

One approach is to set attributes at the same precedence level by setting attributes in a cookbook’s attribute files, and then also setting the same default attributes (but with different values) using a role. The attributes set in the role will be deep merged on top of the attributes from the attribute file, and the attributes set by the role will take precedence over the attributes specified in the cookbook’s attribute files.

See Attributes for detailed information on the different types of node attributes and how they are used to set policy on nodes.


A run-list defines all of the information necessary for Chef to configure a node into the desired state. A run-list is:

  • An ordered list of roles and/or recipes that are run in the exact order defined in the run-list; if a recipe appears more than once in the run-list, Chef Infra Client will not run it twice
  • Always specific to the node on which it runs; nodes may have a run-list that is identical to the run-list used by other nodes
  • Stored as part of the node object on the Chef server
  • Maintained using knife and then uploaded from the workstation to the Chef Infra Server, or maintained using Chef Automate

Run-list Format

A run-list must be in one of the following formats: fully qualified, cookbook, or default. Both roles and recipes must be in quotes, for example:




Use a comma to separate roles and recipes when adding more than one item the run-list:


Managing Nodes

You can manage nodes directly using Knife, Chef Automate, or by using command-line tools that are specific to Chef Infra Client.

  • Knife can be used to create, edit, view, list, tag, and delete nodes.
  • Knife plug-ins can be used to create, edit, and manage nodes that are located on cloud providers.
  • Chef Infra Client can be used to manage node data using the command line and JSON files. Each JSON file contains a hash, the elements of which are added as node attributes. In addition, the run_list setting allows roles and/or recipes to be added to the node.
  • The command line can also be used to edit JSON files and files that are related to third-party services, such as Amazon EC2, where the JSON files can contain metadata fore each instance that is stored in a file on-disk and then read by Chef Infra Client as required.
Edit this page on GitHub

Thank you for your feedback!


Search Results