Chef InSpec custom resources

You can extend the functionality of Chef InSpec profiles by creating custom resources.

For hands-on examples, check out Extending InSpec: InSpec Wrappers and Custom Resources on Learn Chef.

Resource location

Create custom resources in a profile’s libraries directory.

examples/profile
...
├──libraries
│  └── example_config.rb

Resource structure

The smallest possible resource takes this form:

class Tiny < Inspec.resource(1)
  name 'tiny'
end

Resources are written as a regular Ruby class which inherits from Inspec.resource. The number (1) specifies the version this resource plugin targets. As Chef InSpec evolves, this interface may change and may require a higher version.

Resource attributes

Use the following attributes to configure a resource.

name: Identifier of the resource.
Required
desc: Description of the resource
Optional
example: Example usage of the resource
Optional
supports: Platform restrictions of the resource
Optional

Resource methods

The following methods are available to the resource.

inspec: Contains a registry of all other resources to interact with the operating system or target in general.
skip_resource: A resource may call this method to indicate that requirements aren’t met. All tests that use this resource will be marked as skipped.

The additional methods may be defined within the resource:

resource_id

An instance method. Place logic here to determine the unique identifier for a resource, and set it using the superclass method.

Following is an example of its usage in an InSpec test:

# example_config resource can have unique conf file path as an identifier.
describe example_config do
  its("resource_id") { should eq PATH_OF_CONF_FILE }
end

Example

The following example shows a full resource using attributes and methods to provide simple access to a configuration file:

class ExampleConfig < Inspec.resource(1)
  name 'example_config'

  # Restrict to only run on the below platforms (if none were given, all OS's supported)
  supports platform_family: 'fedora'
  supports platform: 'centos', release: '6.9'
  # Supports `*` for wildcard matcher in the release
  supports platform: 'centos', release: '7.*'

  desc '
    Resource description ...
  '

  example '
    describe example_config do
      its("signal") { should eq "on" }
    end
  '

  # Load the configuration file on initialization
  def initialize(path = nil)
    @path = path || '/etc/example.conf'
    @params = SimpleConfig.new( read_content )
  end

  # Expose all parameters of the configuration file.
  def method_missing(name)
    @params[name]
  end

  def resource_id
    value = example_method_to_determine_resource_id # define logic to determine resource_id value
    super(value)
  end

  private

  def read_content
    f = inspec.file(@path)
    # Test if the path exist and that it's a file
    if f.file?
      # Retrieve the file's contents
      f.content
    else
      # If the file doesn't exist, skip all tests that use example_config
      raise Inspec::Exceptions::ResourceSkipped, "Can't read config at #{@path}"
    end
  end
end

For a full example, see our example resource.

Alternate custom resource names

If you have a profile that includes another profile with custom resources as a dependency, the custom resources from the dependent profile are included by default. If two custom resource names conflict, you can use the require_resource InSpec DSL function to rename a custom resource in control code.

require_resource(
  profile: '<DEPENDENCY_NAME>',
  resource: '<RESOURCE_NAME>',
  as: '<ALTERNATE_RESOURCE_NAME>'
)

where:

<DEPENDENCY_NAME> is the dependent profile
<RESOURCE_NAME> is the resource name in the dependent profile
<ALTERNATE_RESOURCE_NAME> is an alternate name for that resource

Lazy Loading

Prior to InSpec v4.16, resources were pre-loaded for every invocation of inspec. This was a heavy and unnecessary burden on the system and exacerbated startup times (especially on Windows).

As of InSpec v4.16, resources are lazily loaded into the inspec process upon use. This greatly speeds up the initial startup costs of the inspec process and only loads what you need to use. For example, inspec --version no longer runs for 10 seconds!.

Overriding Core Resources

Lazy loading does change the way the resource registry is handled in ways that might break some assumptions. Specifically, inspec.<resource> isn’t pre-populated with the core resources that InSpec ships with. If you make a local/custom resource of the same name, referring to the core resource with inspec.<resource> won’t resolve to the core resource.

As such, overriding core resources isn’t recommended best practice.

If you really do need to do this, it’s easiest to make a local resource with a new name and refer to the core resource directly. Otherwise, you need to ensure that the core resource you want is registered (with require "inspec/resource/<name>") before your profile is run to ensure it’s eagerly loaded and in the global resource registry.