Bootstrap a Node

A node is any physical, virtual, or cloud machine that is configured to be maintained by a chef-client. A bootstrap is a process that installs the chef-client on a target system so that it can run as a chef-client and communicate with a Chef server. There are two ways to do this:

knife bootstrap

The knife bootstrap command is a common way to install the chef-client on a node. The default for this approach assumes that a node can access the Chef website so that it may download the chef-client package from that location.

The omnibus installer will detect the version of the operating system, and then install the appropriate version of the chef-client using a single command to install the chef-client and all of its dependencies, including an embedded version of Ruby, RubyGems, OpenSSL, key-value stores, parsers, libraries, and command line utilities.

The omnibus installer puts everything into a unique directory (/opt/chef/) so that the chef-client will not interfere with other applications that may be running on the target machine. Once installed, the chef-client requires a few more configuration steps before it can perform its first chef-client run on a node.

Run the bootstrap command

The knife bootstrap subcommand is used to run a bootstrap operation that installs the chef-client on the target node. The following steps describe how to bootstrap a node using knife.

  1. Identify the FQDN or IP address of the target node. The knife bootstrap command requires the FQDN or the IP address for the node in order to complete the bootstrap operation.

  2. Once the workstation machine is configured, it can be used to install the chef-client on one (or more) nodes across the organization using a knife bootstrap operation. The knife bootstrap command is used to SSH into the target machine, and then do what is needed to allow the chef-client to run on the node. It will install the chef-client executable (if necessary), generate keys, and register the node with the Chef server. The bootstrap operation requires the IP address or FQDN of the target system, the SSH credentials (username, password or identity file) for an account that has root access to the node, and (if the operating system is not Ubuntu, which is the default distribution used by knife bootstrap) the operating system running on the target system.

    In a command window, enter the following:

    $ knife bootstrap -x username -P password --sudo

    where is the IP address or the FQDN for the node. Use the --distro option to specify a non-default distribution. For more information about the options available to the knife bootstrap command for Ubuntu- and Linux-based platforms, see knife bootstrap. For Microsoft Windows, the knife windows plugin is required, see knife windows .

    And then while the bootstrap operation is running, the command window will show something like the following:

    Bootstrapping Chef on knife sudo password:
    Enter your password: [Fri, 07 Sep 2012 11:05:05 -0700] INFO: *** Chef 10.12.0 *** [Fri, 07 Sep 2012 11:05:07 -0700] INFO: Client key /etc/chef/client.pem is not present - registering [Fri, 07 Sep 2012 11:05:15 -0700] INFO: Setting the run_list to [] from JSON [Fri, 07 Sep 2012 11:05:15 -0700] INFO: Run List is [] [Fri, 07 Sep 2012 11:05:15 -0700] INFO: Run List expands to [] [Fri, 07 Sep 2012 11:05:15 -0700] INFO: Starting Chef Run for name_of_node [Fri, 07 Sep 2012 11:05:15 -0700] INFO: Running start handlers [Fri, 07 Sep 2012 11:05:15 -0700] INFO: Start handlers complete. [Fri, 07 Sep 2012 11:05:17 -0700] INFO: Loading cookbooks [] [Fri, 07 Sep 2012 11:05:17 -0700] WARN: Node name_of_node has an empty run list. [Fri, 07 Sep 2012 11:05:19 -0700] INFO: Chef Run complete in 3.986283452 seconds [Fri, 07 Sep 2012 11:05:19 -0700] INFO: Running report handlers [Fri, 07 Sep 2012 11:05:19 -0700] INFO: Report handlers complete
  3. After the bootstrap operation has finished, verify that the node is recognized by the Chef server. To show only the node that was just bootstrapped, run the following command:

    $ knife client show name_of_node

    where name_of_node is the name of the node that was just bootstrapped. The Chef server will return something similar to:

    admin:       false
    chef_type:   client
    json_class:  Chef::ApiClient
    name:        name_of_node

    and to show the full list of nodes (and workstations) that are registered with the Chef server, run the following command:

    knife client list

    The Chef server will return something similar to:


Unattended Installs

The chef-client can be installed using an unattended bootstrap. This allows the chef-client to be installed from itself, without using SSH. For example, machines are often created using environments like AWS Auto Scaling, AWS CloudFormation, Rackspace Auto Scale, and PXE. In this scenario, using tooling for attended, single-machine installs like knife bootstrap or knife CLOUD_PLUGIN create is not practical because the machines are created automatically and someone cannot always be on-hand to initiate the bootstrap process.

When the chef-client is installed using an unattended bootstrap, remember that the chef-client:

  • Must be able to authenticate to the Chef server
  • Must be able to configure a run-list
  • May require custom attributes, depending on the cookbooks that are being used
  • Must be able to access the chef-validator.pem so that it may create a new identity on the Chef server
  • Must have a unique node name; the chef-client will use the FQDN for the host system by default

When the chef-client is installed using an unattended bootstrap, it is typically built into an image that starts the chef-client on boot. The type of image used depends on the platform on which the unattended bootstrap will take place.

Use settings in the client.rb filechef_server_url, http_proxy, and so on—to ensure that configuration details are built into the unattended bootstrap process.

Setting the initial run-list

A node’s initial run-list is specified using a JSON file on the host system. When running the chef-client as an executable, use the -j option to tell the chef-client which JSON file to use. For example:

$ chef-client -j /etc/chef/file.json --environment _default

where file.json is similar to:

  "resolver": {
    "nameservers": [ "" ],
  "run_list": [ "recipe[resolver]" ]

and where _default is the name of the environment that is assigned to the node.


This approach may be used to update normal attributes, but should never be used to update any other attribute type, as all attributes updated using this option are treated as normal attributes.