Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 37 ยท Architecture and Setup

Chef Infra Server and Bootstrapping

Learn how a node joins Chef: the Infra Server and organizations, knife bootstrap, client.rb, client keys, first-boot.json and run lists, with a runnable Ruby model.

A new machine knows nothing about Chef. Bootstrapping is the process that installs Chef Infra Client on it, gives it an identity, connects it to a Chef Infra Server and runs its first converge. This lesson explains each step and the files it creates. The real commands need servers and SSH, so they are read-only. A Ruby stand-in models the registration and first-boot data so you can practice reading them.

Setting up the server side

Before any node can join, someone creates an organization and a user on the Chef Infra Server. Chef-hosted and self-hosted servers both work the same from the node's point of view. On a self-hosted server the commands look like this (read-only):

Terminal
chef-server-ctl user-create alice Alice Smith [email protected] 'S3cret!pw' --filename alice.pem
chef-server-ctl org-create acme 'Acme Inc' --association_user alice --filename acme-validator.pem

You get two key files: a user key (alice.pem) and, on older setups, an organization validator key. Your workstation then keeps a config.rb for knife (usually in ~/.chef/):

Ruby
current_dir = File.dirname(__FILE__)
node_name   'alice'
client_key  "#{current_dir}/alice.pem"
chef_server_url 'https://chef.example.com/organizations/acme'
cookbook_path   ["#{current_dir}/../cookbooks"]

After that, knife ssl check and knife node list confirm that the connection works.

What knife bootstrap does

One command turns a bare machine into a managed node (read-only):

Terminal
knife bootstrap 203.0.113.10 \
  --ssh-user ubuntu --sudo \
  --node-name web1 \
  --run-list 'recipe[base],recipe[webserver]' \
  --environment production

Behind that command, knife connects over SSH (or WinRM for Windows) and:

  1. Installs Chef Infra Client.
  2. Writes /etc/chef/client.rb with the server URL and node name.
  3. Registers the node and stores its private key in /etc/chef/client.pem.
  4. Writes /etc/chef/first-boot.json with the run list.
  5. Runs chef-client -j /etc/chef/first-boot.json once.

From then on the node runs the client on a schedule (usually a service or cron job) and is configured in the pull model.

sequenceDiagram
  participant K as knife (workstation)
  participant N as New node
  participant S as Chef Infra Server
  K->>N: SSH: install client, write client.rb and first-boot.json
  N->>S: Register (create client and node, get key)
  N->>S: Download cookbooks for the run list
  N->>N: Converge
  N->>S: Save node data

The workstation only starts things; after that the node and server talk directly.

The files on the node

first-boot.json is where the first run list lives (read-only):

JSON
{
  "run_list": ["recipe[base]", "recipe[webserver]"],
  "webserver": { "port": 8080 }
}

Everything in that file besides run_list becomes normal attributes on the node. Treat them carefully, because normal attributes persist on the node across runs.

Alternatives to a server

You do not always need a server. Local mode (chef-client -z) reads cookbooks from disk. Policyfiles can be compiled into a single archive that you copy to a node and run with chef-client -z. Many teams also use chef-run, a push-style tool in Chef Workstation. A server remains the best fit when you want search, central node records and many nodes pulling regularly.

Stand-in: model a bootstrap

This stand-in builds the first-boot.json text, registers a node on a fake server and prints the result. It is not real Chef, but it shows how the pieces connect and how JSON gets split into run list and attributes.

Ruby Stand-in: bootstrap a node

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Splitting run_list from the rest of the JSON is exactly what Chef does with -j. The other keys land as normal attributes.

Reading a run list

Run lists are strings in a precise notation. Parsing one is a good way to remember it.

Ruby Stand-in: parse run list entries

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Roles are covered in the roles chapter; the important point now is that entries are applied in order.

If knife bootstrap fails with an SSL error, the cause is usually a self-signed server certificate. Fix it with knife ssl fetch (and trust the certificate) rather than disabling verification.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the purpose of knife bootstrap?

    Bootstrap installs the client, writes its config and key, and does the first run with the given run list.
  2. 2. Where does the node keep its private key?

    client.pem in /etc/chef holds the node's key, used to sign requests.
  3. 3. In first-boot.json, what happens to keys other than run_list?

    Extra JSON becomes normal-level attributes, which persist on the node.
  4. 4. In recipe[webserver::ssl], what is ssl?

    The format is cookbook::recipe.

Summary

  • An organization and a user exist on the server before nodes join.
  • knife bootstrap installs the client, writes client.rb, client.pem and first-boot.json, and runs once.
  • Nodes then pull on a schedule.
  • Local mode and Policyfile archives allow server-less setups.

Next: Resources and Actions