puppetdb-ruby

a simple gem for interacting with the PuppetDB API.

This library was migrated from puppetlabs ownership to VoxPupuli on 19 October 2016.

Installing from Ruby CLI:

gem install puppetdb-ruby

Include in Gemfile:

gem 'puppetdb-ruby'

Require the puppetdb gem in your ruby code.

require 'puppetdb'

# Defaults to latest API version.

Non-SSL:

client = PuppetDB::Client.new({:server => 'http://localhost:8080'})

SSL with cert-based authentication:

client = PuppetDB::Client.new({
    :server => 'https://localhost:8081',
    :pem    => {
        'key'     => "keyfile",
        'cert'    => "certfile",
        'ca_file' => "cafile"
    }})

SSL with PE RBAC token based authentication:

client = PuppetDB::Client.new({
    :server => "https://localhost:8081",
    :token  => "my_pe_rbac_token",
    :cacert => "/path/to/cacert.pem",
    })

SSL with PE RBAC token based authentication, using all settings from PE Client Tools configurations:

client = PuppetDB::Client.new()

Note: When using cert-based authentication you must specify the full pem structure. When using token based authentication you must NOT provide the pem structure and instead pass ':token' and ':cacert' (or allow them to be read from the PE Client Tools configuration).

The Query Feature allows the user to request data from PuppetDB using the Query endpoints. It defaults to the latest version of the Query Endpoint.

Example:

response = client.request(
  'nodes',
  [:and,
    [:'=', ['fact', 'kernel'], 'Linux'],
    [:>, ['fact', 'uptime_days'], 30]
  ],
  {:limit => 10}
)

nodes = response.data

# queries are composable

uptime = PuppetDB::Query[:>, [:fact, 'uptime_days'], 30]
redhat = PuppetDB::Query[:'=', [:fact, 'osfamily'], 'RedHat']
debian = PuppetDB::Query[:'=', [:fact, 'osfamily'], 'Debian']

client.request uptime.and(debian)
client.request uptime.and(redhat)
client.request uptime.and(debian.or(redhat))

See the PuppetDB API Docs for more about the AST based query language.

PQL queries are supported by using the empty endpoint.

Example:

response = client.request(
  '',
  'resources[title] { nodes { deactivated is null } }',
  {:limit => 10}
)

resources = response.data

See the PuppetDB API Docs for more on PQL queries.

The Command Feature allows the user to execute REST Commands against the PuppetDB Command API Endpoints. It defaults to the latest version of the Command Endpoint.

The command method takes three arguments:

• command: a string identifying the command
• payload: a valid JSON object of any sort. It’s up to an individual handler function to determine how to interpret that object.
• version: a JSON integer describing what version of the given command you’re attempting to invoke. The version of the command also indicates the version of the wire format to use for the command.

Example:

client.command(
  'deactivate node',
  {'certname' => 'test1', 'producer_timestamp' => '2015-01-01'},
  3
)

See the PuppetDB Commands Endpoint Docs for more information.

bundle install
bundle exec rspec

File issues or feature requests using GitHub issues.

If you are interested in contributing to this project, please see the Contribution Guidelines

This module was donated to VoxPupuli by Puppet Inc on 10-19-2016.

Nathaniel Smith nathaniel@puppetlabs.com Lindsey Smith lindsey@puppetlabs.com Ruth Linehan ruth@puppetlabs.com

See LICENSE.