Custom Resource Guide
Chef Infra Client ships with over 150 built-in resources for managing system configuration such as
windows_firewall. With Custom Resources you can extend the built-in capabilities of Chef Infra Client to create reusable resources for use anywhere in your infrastructure.
- Ship directly in cookbooks
- Leverage Chef Infra Client built-in resources and any additional custom Ruby code (if needed)
- Behave the same as existing built-in resources in your recipes
The layout for a custom resource is:
provides :resource_name property :property_name, RubyType, default: 'value' action :action_a do # a mix of built-in Chef Infra resources and Ruby end action :action_b do # a mix of built-in Chef Infra resources and Ruby end
The first action listed is the default action.
Write a Custom Resource
You’ll write the code for a custom resource in a Ruby file and located in a cookbook’s
/resources directory (you need to generate the resource first). This code:
- Declares the properties of the custom resource
- Loads current state of properties for existing resources
- Defines each action the custom resource may take
Generate a Custom Resource
resources directory does not exist by default in a cookbook.
resources directory and a resource file from the
chef-repo/cookbooks directory with the command:
chef generate resource PATH_TO_COOKBOOK RESOURCE_NAME
For example, this command generates a
site resource in the
chef generate resource cookbooks/custom_web site
custom_web cookbook directory with a custom resource has the structure:
- cookbooks - custom_web - recipes - default.rb - resources - site.rb - test - integration - default - default_test.rb - .gitignore - CHANGELOG.md - chefignore - kitchen.yml - LICENSE - metadata.rb - Policyfile.rb - README.md
site uses Chef Infra’s built-in
package resources, and includes
:delete actions. It also assumes the existence of a custom httpd template. The code in this custom resource is similar to a typical recipe because it uses built-in Chef Infra Client resources, with the addition of the property and actions definitions for this custom resource.
provides :site property :homepage, String, default: '<h1>Hello world!</h1>' action :create do package 'httpd' service 'httpd' do action [:enable, :start] end file '/var/www/html/index.html' do content new_resource.homepage end end action :delete do package 'httpd' do action :remove end file '/var/www/html/index.html' do action :delete end end
siteis the name of the custom resource. The
providesstatement makes the custom resource available for use recipes.
homepagesets the default HTML for the
index.htmlfile with a default value of
actionblock uses the built-in collection of resources to tell Chef Infra Client how to install Apache, start the service, and then create the contents of the file located at
action :createis the default resource (because it is listed first);
action :deletemust be called specifically (because it is not the default action)
Once written, you can use a custom resource may be used in a recipe with the same syntax as Chef Infra Client built-in resources.
Call a resource in a recipe by its
resource_name. For example:
Learn Chef interactive tutorial: Extending Chef Infra: Custom Resources
See the Custom Resources Glossary for a description of available methods.