Published on 25 April 2018 by

We're pleased to announce that the Puppet Resource API is now available.

The Resource API provides a simple way to create new native resources in the form of types and providers for Puppet. It is provided as a Ruby gem to be referenced within modules. Support for it has been included as an experimental feature in version 1.4 of the Puppet Development Kit (see pdk new provider --help for details).

The Resource API provides the following functionality:

  • Simple type and provider definition.
  • Use Puppet 4+ data types: String, Integer, Float, Numeric, Boolean, Optional[], Variant[], etc.
  • Canonicalize, simple_get_filter, and remote_resource features.
  • Logging facilities.
  • New providers are compatible with all puppet commands:
    • puppet apply
    • puppet resource
    • puppet agent
    • puppet device (if applicable)

The code snippets below illustrate how to create a type and a provider using the Resource API that manage a Cisco IOS device. A simple example type for configuring NTP parameters:

require 'puppet/resource_api'

Puppet::ResourceApi.register_type(
  name: 'ntp_config',
  docs: 'Specify NTP config',
  features: ['remote_resource'],
  attributes: {
    name: {
      type: 'String',
      desc: 'Config name, default to "default" as the NTP config is global rather than instance based',
      behaviour: :namevar,
      default: 'default',
    },
    authenticate:  {
      type: 'Boolean',
      desc: 'NTP authentication enabled [true|false]',
    },
    source_interface:  {
      type: 'String',
      desc: 'The source interface for the NTP system',
    },
    # more attributes here...

The provider is a Ruby class that contains the logic to read the current state and enforce the desired state. (Note: Not shown are the utility methods to parse and render the necessary IOS commands.)

require 'puppet/resource_api'
require 'puppet/resource_api/simple_provider'
require 'puppet_x/puppetlabs/cisco_ios/utility'

class Puppet::Provider::NtpConfig::NtpConfig < Puppet::ResourceApi::SimpleProvider
  include PuppetX::CiscoIOS::Utility

  def get(_context)
    output = run_command_enable_mode(get_values)
    if output.nil?
      return []
    else
      return instances_from_cli(output)
    end
  end

  def update(_context, _name, is, should)
    array_of_commands_to_run = commands_from_is_should(is, should)
    array_of_commands_to_run.each do |command|
      run_command_conf_t_mode(command)
    end
  end
end

Get started

To get started with the Resource API, checkout the Getting Started section of the Resource API documentation. We're updating that as we continue to add features.

To ease adoption of the Resource API there is a module on the Forge to install in your Puppet server or Puppet agent. The Resource API gem must be installed in order to use modules that have types and providers created using the Resource API. In the future we are planning to bundle the Resource API with the Puppet platform.

We encourage all module developers to review the Resource API and use it when creating modules that have types and providers. For reference, there is an example of its usage in a branch of the apt module. In the future we are planning to release a hands-on-lab to help developers to create modules with types and providers that use the Resource API.

Feedback welcome

We’d love to get feedback from you. If you find issues please raise them in the GitHub repository or email the following contacts directly: David Schmitt (Tech Lead, david dot schmitt at puppet dot com), David Armstrong (Developer, david dot armstrong at puppet dot com), David Mallon (Development Manager, david dot mallon at puppet dot com) and Davin Hanlon (Product Owner, davin dot hanlon at puppet dot com).

Davin Hanlon is a product owner at Puppet.

Learn more

Share via:
Posted in:

Add new comment

The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.