Chef Infra Client executes a run in two phases, compile and converge. What happens in each, and why does plain Ruby written inside a recipe so often run earlier than its author expected?

## Two passes, not one Chef Infra Client does not stream a recipe line by line into changes on the machine. Each run has a clear shape: 1. **Ohai** collects facts about the node — platform, network, memory, filesystems — into automatic attributes. 2. **Compile phase.** Chef expands the run list, loads each cookbook's libraries, attribute files and resources, then evaluates the recipes as Ruby. Every resource block it meets is instantiated and appended to the **resource collection**. Nothing is applied. 3. **Converge phase.** Chef walks the resource collection in order. For each resource it resolves the provider, loads current state, and acts only if the node diverges from the declaration. 4. Handlers and reporting run at the end. The important consequence: by the time *anything* has changed on the node, the entire body of every recipe has already been read and evaluated. ## Why the surprise happens A recipe file is Ruby, and this is deliberately powerful — you can loop, branch, and call library methods to build resources dynamically. But it means only the resource blocks are deferred. Everything else is plain Ruby that executes immediately, in compile. ```ruby # Compile phase: this line runs BEFORE the template below is written if ::File.exist?('/etc/app/app.conf') Chef::Log.info('config already present') end template '/etc/app/app.conf' do # queued, not written yet source 'app.conf.erb' end ``` On a fresh node the `File.exist?` check is false even on the run that creates the file, and it is still false on the *next* run at the moment it executes — no, on the next run the file exists, which is worse: the recipe now behaves differently between the first and second run for reasons the author cannot see in the source order. Classic variants of the same mistake: - Reading a password out of a file that an earlier resource in the same recipe generates. - Calling `shell_out('myapp --version')` on a binary the recipe installs. - Interpolating `node['app']['port']` into a property when that attribute is set by a `ruby_block` later in the run. ## `lazy` — defer one property When only a single property value needs the converge-time answer, wrap it in `lazy`. The block is evaluated when the provider reads the property, not when the resource is declared. ```ruby template '/etc/app/generated.conf' do source 'generated.conf.erb' variables(lazy { { secret: ::File.read('/etc/app/secret') } }) end ``` ## `ruby_block` — defer a whole chunk When you need real logic to run in the middle of the converge, put it in a `ruby_block` resource. Because it is a resource, it takes its place in the collection and runs at that point in the order — and it can be notified, and it can notify. ```ruby execute 'generate-secret' do command '/usr/local/bin/gen-secret > /etc/app/secret' creates '/etc/app/secret' end ruby_block 'read-secret-into-node' do block do node.run_state['app_secret'] = ::File.read('/etc/app/secret').strip end end template '/etc/app/app.conf' do source 'app.conf.erb' variables(lazy { { secret: node.run_state['app_secret'] } }) end ``` Note `node.run_state` rather than a normal attribute: run_state is a scratch space for the current run and is not saved back to the Chef Infra Server, which is what you want for a secret. ## Compile-time execution, on purpose Occasionally you genuinely need a resource to act during compile — the canonical case is installing a gem that a later library or resource must `require`. Chef's `chef_gem` resource is designed for exactly that and runs against the client's own Ruby. The general escape hatch is calling `.run_action(:something)` on a resource to force it immediately, but treat it as a smell: it breaks the mental model that order in the collection is order of execution, and it makes the recipe hard to reason about for everyone after you. ## Why interviewers ask this The two-phase model is the single biggest difference between reading a Chef recipe as a script and reading it as a declaration. Candidates who have only skimmed cookbooks describe a run as "it goes through the recipe and does each thing" — which is right about the ordering and wrong about the timing, and that gap is what produces the bug reports. Being able to say "that check runs at compile time, so wrap it in a ruby_block" is the fastest possible demonstration that you have actually debugged a Chef run. ## How you see it The run output lists the resource collection as it converges, with each resource marked up to date or updated. Running `chef-client --why-run` (also spelled `-W`) performs a compile and then reports what converge *would* change without changing it — useful, though limited, because resources whose behaviour depends on earlier resources having run cannot be predicted accurately. Chef's own logs distinguish the phases, and `Chef::Log.info` calls placed in bare recipe code versus inside a `ruby_block` are a quick way to prove the ordering to yourself.