Table Of Contents

About LWRPs

A LWRP is a part of a cookbook that is used to extend the chef-client in a way that allows custom actions to be defined, and then used in recipes in much the same way as any platform resource. A LWRP has two principal components:

  • A lightweight resource that defines a set of actions and attributes
  • A lightweight provider that tells the chef-client how to handle each action, what to do if certain conditions are met, and so on

In addition, most lightweight providers are built using platform resources and some lightweight providers are built using custom Ruby code

Once created, a LWRP becomes a Ruby class within the organization. During each chef-client run, the chef-client will read the lightweight resources from recipes and process them alongside all of the other resources. When it is time to configure the node, the chef-client will use the corresponding lightweight provider to determine the steps required to bring the system into the desired state.

Where the lightweight resource represents a piece of the system, its current state, and the action that is needed to move it to the desired state, a lightweight provider defines the steps that are required to bring that piece of the system from its current state to the desired state. A LWRP behaves similar to platform resources and providers:

  • A lightweight resource is a key part of a recipe
  • A lightweight resource defines the actions that can be taken
  • During a chef-client run, each lightweight resource is identified, and then associated with a lightweight provider
  • A lightweight provider does the work to complete the action requested by the lightweight resource

Read more about how to build custom lightweight resources.

Inline Compile Mode

A lightweight resource is created by the action block of a lightweight provider. When the resource collection is compiled, a lightweight resource is inserted into the top-level resource collection after the point at which the lightweight provider is associated. For example, if a resource collection looks like:


then when lwrp_resource is executed, the resource collection will be modified as follows:

top_level_resource_one           # already processed
  lwrp_resource                  # already processed
    embedded_resource_one        # created by the lightweight provider
    embedded_resource_two        # created by the lightweight provider

In this situation, embedded lightweight resources cannot notify the top-level resource because the top-level resource has finished processing. This has the same effect as if the top-level resource collection were invisible to the embedded lightweight resources.

To ensure that an embedded lightweight resource can notify the top-level resource add use_inline_resources to the top of the file that defines the lightweight provider that is associated with that lightweight resource. When use_inline_resources is added to the file, the code in the lightweight provider’s action block will execute as part of a self-contained chef-client run. If any embedded lightweight resources are updated, the top-level lightweight resource is marked as updated and notifications set for the top-level resource will be triggered normally.


Chef maintains a collection of cookbooks that define some common scenarios and provides resources to support them. These cookbooks are located at To use these resources within recipes, first download the cookbook. Then add those resources to recipes.

Some of the most popular Chef-maintained cookbooks are listed below:

Cookbook Description
apt The apt cookbook is used to configure APT and APT services, for managing APT repositories and preferences.
ark Use to manage software archives.
aws The aws cookbook is used to manage resources that are running in Amazon Web Services.
bluepill The bluepill cookbook is used to install Blue Pill, and then use it to manage services.
chef_handler The chef_handler cookbook is used to distribute and enable exception and report handlers.
cron Use to install cron and start the crond service.
daemontools The daemontools cookbook is used to install and configure daemontools so that it can be used to manage UNIX services.
djbdns The djbdns cookbook is used to install djbdns and use it to configure DNS services.
dmg The dmg cookbook is used to create a DMG package for use with Mac OS X.
dynect The dynect cookbook is used to manage DNS records using the DynECT REST API.
firewall The firewall cookbook is used to manage firewalls and their associated firewall rulesets.
freebsd The freebsd cookbook is used to manage port options for FreeBSD.
gunicorn Gunicorn is a web service gateway interface server for UNIX that is a pre-fork worker model from the Ruby Unicorn project. The gunicorn cookbook is used to install and configure Gunicorn.
homebrew The homebrew cookbook is used to install and configure Homebrew for use as the package manager for Mac OS X.
iis The iis cookbook is used to install and configure Internet Information Services (IIS).
lvm Use to install the lvm2 package, and then manage LVM.
maven The maven cookbook is used to install and configure Apache Maven.
nginx Use to install nginx from package or source code, and then set up configuration handling.
openssh The openssh cookbook is used to install OpenSSH.
omnibus Use to prepare a machine to be an Omnibus builder.
php The php cookbook is used to install and configure PHP and PHP modules.
postfix Use to install and configure postfix for client or outbound relayhost.
powershell The powershell cookbook is used to install Windows PowerShell.
rabbit mq The rabbitmq cookbook is used to install and configure RabbitMQ.
squid Use to configure squid as a caching proxy.
sudo The sudo cookbook is used to install sudo and configure /etc/sudoers.
transmission The transmission cookbook is used to install and configure the Transmission BitTorrent client.
webpi The webpi cookbook is used to run the Microsoft Web Platform Installer (WebPI).
windows The windows cookbook is used to configure auto run, batch, reboot, enable built-in operating system packages, configure Microsoft Windows packages, reboot machines, and more.
yum The yum cookbook is used to manage the contents of the yum.conf configuration file for global yum configurations and for individual yum repositories.