Custom Resource Guide

Chef Infra Client ships with over 150 built-in resources for managing system configuration such as directory, remote_file, and 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

Syntax

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

The resources directory does not exist by default in a cookbook. Generate the 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 custom_web cookbook:

chef generate resource cookbooks/custom_web site

The custom_web cookbook directory with a custom resource has the structure:

. cookbooks
└── custom_web
    ├── CHANGELOG.md
    ├── LICENSE
    ├── Policyfile.rb
    ├── README.md
    ├── chefignore
    ├── kitchen.yml
    ├── metadata.rb
    ├── recipes
    │   └── default.rb
    ├── resources
    │   └── site.rb
    └── test
        └── integration
            └── default
                └── default_test.rb

Example Resource

This example site uses Chef Infra’s built-in file, service and package resources, and includes :create and :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

where

site is the name of the custom resource. The provides statement makes the custom resource available for use recipes.
homepage sets the default HTML for the index.html file with a default value of '<h1>Hello world!</h1>'
the action block 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 /var/www/html/index.html
action :create is the default resource (because it is listed first); action :delete must 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.

Syntax

Call a resource in a recipe by its resource_name. For example:

site 'foo'

Learn More

Learn Chef interactive tutorial: Extending Chef Infra: Custom Resources

See the Custom Resources Glossary for a description of available methods.