Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Your First Chef Recipe

Write and understand your first Chef recipe with package, file and service resources, learn the resource syntax, and run a Ruby stand-in that models resource order.

A recipe is just a Ruby file with resources in it. In this lesson you read a first, complete recipe line by line, learn the shape every resource shares, and then rebuild the idea in a runnable Ruby stand-in so that you can see how a recipe becomes a list of actions.

A complete first recipe

This recipe sets up a tiny web page. It is real Chef code, shown read-only because the site cannot install packages. Chef would run it on a Linux node.

Ruby
package 'nginx' do
  action :install
end

file '/var/www/html/index.html' do
  content '<h1>Hello from Chef</h1>'
  owner 'root'
  group 'root'
  mode '0644'
end

service 'nginx' do
  action [:enable, :start]
end

Three resources, applied top to bottom: install nginx, write the page, make sure nginx starts now and at boot. If you run it again, nothing happens, because everything already matches.

The shape of a resource

Every resource has the same anatomy:

Ruby
resource_type 'name' do
  property value
  property value
  action :action_name
end
  • resource_type says what kind of thing it is (package, file, service, directory).
  • name identifies the thing, and often is the thing: a package name, a file path. It is the resource's name property.
  • The block holds properties that describe the desired state. A property is a setting such as content, owner or mode.
  • action says what to do. Every resource has a default action, so action :install for package can be omitted. file defaults to :create.

Because the resource name is the main property, these two are identical:

Ruby
package 'git'

package 'git' do
  package_name 'git'
  action :install
end

The short form is what you will write most of the time.

Reading it as a sentence

A useful habit is to read each resource as a sentence. "The package nginx is installed." "The file /var/www/html/index.html exists with this content, owned by root, mode 0644." "The service nginx is enabled and started." If a resource does not read like a sentence about the desired state, you are probably describing steps instead, and that is a sign to look for a better resource.

Stand-in: a recipe as a list of resource objects

In real Chef, evaluating a recipe does not change anything straight away. Each resource line creates an object and adds it to a list called the resource collection. Only afterwards does Chef walk the list and converge each item. This two-step idea is central, and the stand-in below models it with a method that collects resources from a block. It is not real Chef.

Ruby Stand-in: a recipe builds a resource collection

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 trick is instance_eval: it runs your block with self set to the recipe object, so a bare word like package calls our method. Chef's real DSL uses the same Ruby feature, which is why recipes look like a custom language yet remain valid Ruby.

Converging the collection

Now add the second step. The stand-in walks the collection and "applies" each resource, skipping the ones that already match.

Ruby Stand-in: converge the collection

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.

Real Chef checks the properties too (a file with the wrong content is not up to date), but the compare-then-act loop is the same.

Do not run a recipe with ruby recipe.rb. A recipe only makes sense inside Chef, which provides the resource methods. To try one safely, use Test Kitchen or chef-client --local-mode, as shown in the workstation lesson.

Common beginner mistakes

  • Starting a service before installing it. Order matters: package first, service last.
  • Using execute for everything. execute 'apt-get install nginx' works but is not declarative. Use the package resource so Chef can tell whether it is already installed.
  • Forgetting quotes. Resource names are strings: package 'nginx', not package nginx.
  • Hard-coded values. Ports and versions belong in attributes, covered in the cookbook chapter.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In package 'nginx' do ... end, what is 'nginx'?

    The string after the type is the resource's name property. For package it is the name of the package.
  2. 2. What does a resource's action describe?

    Actions such as :install, :start or :create state the operation Chef should perform if the state differs.
  3. 3. Why is execute 'apt-get install nginx' usually worse than package 'nginx'?

    A dedicated resource knows how to check the current state. A raw command has to be guarded manually.
  4. 4. In the stand-in, why does instance_eval make package 'nginx' work inside the block?

    instance_eval evaluates a block with a different self. Chef's DSL relies on the same Ruby feature.

Summary

  • A recipe is Ruby code that declares resources in order.
  • Each resource has a type, a name, properties and an action.
  • Evaluating a recipe builds a resource collection; applying it happens afterwards.
  • Prefer dedicated resources over raw commands.

Next: Chef Workstation and Tools