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_urls: 'https://localhost:8081',
    cacert: '/path/to/ca.pem'
    cert: '/path/to/certfile.pem',
    key: '/path/to/keyfile.pem'
    })

SSL with PE RBAC token based authentication:

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

Configure connections to multiple PuppetDB's via server_urls

client = PuppetDB::Client.new({
    :server_urls => "https://localhost:8081,https://localhost:8083",
    :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.

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

If you have configured multiple PuppetDB's via server_urls then you can query in :failover mode. This will query each PuppetDB in server_urls in order until it gets a successful response. It will fail with an APIError only if all queries fail.

response = client.request(
  'nodes',
  [:"=", "certname", "foo"],
  {
    :limit => 10
    :query_mode => :failover
  }
)

See the PuppetDB API Docs for more.

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.

You can get the status of all configured PuppetDB's by querying the /status/v1/services endpoints.

client.status

# The result will be of the form (one entry per server)
# {
#   "http://localhost:8080": {
#     "puppetdb-status": {
#       "service_version": "6.3.1-SNAPSHOT",
#       "service_status_version": 1,
#       "detail_level": "info",
#       "state": "running",
#       "status": {
#         "maintenance_mode?": false,
#         "queue_depth": 0,
#         "read_db_up?": true,
#         "write_db_up?": true
#       },
#       "active_alerts": [
#       ]
#     },
#     "status-service": {
#       "service_version": "1.1.0",
#       "service_status_version": 1,
#       "detail_level": "info",
#       "state": "running",
#       "status": {
#       },
#       "active_alerts": [
#       ]
#     }
#   }
# }

You can export an archive of your PuppetDB to a file. Optionally you can override the anonymization_profile (default: none).

client.export('path/for/new_puppetdb_export.tar.gz', anonymization_profile: :high)

Once you have a PuppetDB export, it can be loaded into PuppetDB with import.

client.import('path/to/existing_puppetdb_export.tar.gz')

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.