Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Architecture and Setup

The Chef Client Run

Follow a Chef Infra Client run step by step: Ohai, authentication, building the node object, compile and converge phases, and the classic compile-time versus run-time gotcha.

Each time Chef Infra Client runs on a node, it goes through the same sequence of steps. Knowing that sequence explains many puzzling behaviors, above all why Ruby code in a recipe sometimes runs "too early". This lesson walks through a run, then focuses on the two phases at its heart, compile and converge, using a runnable stand-in. The real client cannot run here, so real code is read-only.

The steps of a run

A Chef Infra Client run

Ohai Collect node facts
Authenticate Sign in to the server
Build node Merge facts and policy
Sync Download cookbooks

First half: gather and fetch.

1 / 2
  1. Ohai collects facts about the machine (operating system, memory, network, ...). These become automatic attributes.
  2. The client authenticates to the Chef Infra Server (skipped in local mode).
  3. It builds the node object by merging the saved node data, the facts, the run list and role/environment data.
  4. It synchronizes cookbooks, downloading only the files that changed.
  5. Compile phase: every recipe in the expanded run list is evaluated as Ruby, which creates the resource collection.
  6. Converge phase: each resource in the collection is checked and applied, in order.
  7. It saves the node back to the server and runs handlers (notifications on success or failure).

Compile versus converge

This is the most important idea in the lesson. During compile, Chef evaluates your recipe Ruby code top to bottom, but package, file, service and other resources are only recorded, not executed. During converge Chef performs them. So plain Ruby code runs first, even if you wrote it after a resource.

Consider this real recipe, shown read-only:

Ruby
file '/tmp/greeting.txt' do
  content 'hello'
end

puts File.read('/tmp/greeting.txt')   # runs during compile

The puts runs during compile, before the file resource has created the file, so on a fresh node the read fails. The fix is to run Ruby at converge time with a ruby_block (the next sections and Ruby in Recipes cover that).

Stand-in: two phases

The stand-in below reproduces the gotcha with a fake file system. Compile runs the block, which prints immediately and records resources. Converge applies them afterwards. This is not real Chef, but the order of the output matches how Chef behaves.

Ruby Stand-in: compile prints first, converge acts later

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.

The "file exists?" line prints false because converge has not happened yet. Inside the ruby_block, which also runs at converge, the content is there. Real Chef's ruby_block works the same way.

Making values lazy

A related problem: a property value is computed at compile time. If it depends on something created by an earlier resource, wrap it in lazy { ... } so Chef evaluates it at converge time. Real code, read-only:

Ruby
file '/etc/app/version' do
  content lazy { IO.read('/opt/app/VERSION') }
end

The stand-in shows the difference between eager and lazy evaluation of the same expression.

Ruby Stand-in: eager versus lazy values

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.

Chef's lazy { } is a close relative of the lambda used here.

Handlers and reporting

At the end the client saves the node and can run handlers, Ruby classes that react to a run's success or failure, for instance by sending a message to a chat room. The run also produces a summary such as "Chef Infra Client finished, 3/20 resources updated". If any resource raises an error, the run stops (unless you set ignore_failure true on that resource) and the node is marked as failed.

When a recipe behaves oddly, ask "does this line run at compile time or at converge time?" That single question solves a large share of beginner bugs.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens to a package resource during the compile phase?

    Compile only builds the collection. Applying resources happens during converge.
  2. 2. A plain puts File.read(path) after a file resource runs:

    Plain Ruby in a recipe executes while the recipe is compiled, so it runs before any resource is converged.
  3. 3. Which tool defers Ruby code until converge time?

    A ruby_block is a resource, so its code runs when Chef converges it, in order.
  4. 4. What does lazy { } do for a property value?

    lazy delays evaluation, so the value can depend on earlier resources.

Summary

  • A run: Ohai, authenticate, build node, sync cookbooks, compile, converge, save and report.
  • Compile builds the resource collection; converge applies it.
  • Plain Ruby runs at compile time; use ruby_block and lazy for converge-time logic.
  • Handlers react to success or failure at the end.

Next: Ohai and the Node Object