puppetdb-ruby

a simple gem for interacting with the PuppetDB API.

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

Installation

Installing from Ruby CLI:

gem install puppetdb-ruby

Include in Gemfile:

gem 'puppetdb-ruby'

Usage

Require the puppetdb gem in your ruby code.

require 'puppetdb'

# Defaults to latest API version.

Create a new connection:

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).

Query API usage

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.

Currently, puppetdb-ruby only supports the AST Query Language.

Support for the PQL Query Language is planned for a future release.

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.

PQL Queries usage

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.

Command API Usage

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.

Tests

bundle install
bundle exec rspec

Issues & Contributions

File issues or feature requests using GitHub issues.

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

Authors

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

Nathaniel Smith [email protected] Lindsey Smith [email protected] Ruth Linehan [email protected]

License

See LICENSE.