puppetdb_cli 2.0.0

data/lib/puppetdb_cli/db/import.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Add the import command
+#
+# The import command is used to submit an exported archive to PuppetDB
+module PuppetDBCLI
+  @import_cmd = @db_cmd.define_command do
+    name 'import'
+    usage 'import [options] <path>'
+    summary 'import a PuppetDB archive to PuppetDB'
+
+    run do |opts, args, cmd|
+      PuppetDBCLI::Utils.log_command_start cmd.name, opts, args
+
+      if args.count.zero?
+        PuppetDBCLI.logger.fatal 'No file path provided'
+        exit 1
+      elsif args.count > 1
+        PuppetDBCLI.logger.fatal 'Only one argument, the path to the export file, is allowed.'
+        exit 1
+      end
+
+      filename = File.expand_path(args.first)
+      PuppetDBCLI.logger.info "Starting import from '#{filename}'"
+
+      client = PuppetDBCLI::Utils.open_client_connection(opts)
+      response = client.import(filename)
+
+      exit 1 unless response.success?
+    end
+  end
+end

data/lib/puppetdb_cli/db/status.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Add the status command to the PuppetDB CLI
+#
+# The status command is used to query for all the statuses of the configured PuppetDB's
+module PuppetDBCLI
+  @status_cmd = @db_cmd.define_command do
+    name 'status'
+    usage 'status [options]'
+    summary 'query the PuppetDB status endpoint for each configured PuppetDB'
+
+    run do |opts, args, cmd|
+      PuppetDBCLI::Utils.log_command_start cmd.name, opts, args
+
+      unless args.count.zero?
+        PuppetDBCLI.logger.fatal 'status command does not allow arguments'
+        exit 1
+      end
+      client = PuppetDBCLI::Utils.open_client_connection opts
+
+      response = client.status
+      puts JSON.pretty_generate(response)
+    end
+  end
+end

data/lib/puppetdb_cli/logger.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+# PuppetDB CLI namespace
+module PuppetDBCLI
+  def self.logger
+    @logger ||= PuppetDBCLI::Logger.new
+  end
+
+  # A logger for the PuppetDB CLI
+  #
+  # Overrides standard format of logs for better cli ouput, but reverts to traditional
+  # log formatting when in debug mode
+  class Logger < ::Logger
+    def initialize
+      super($stderr)
+
+      self.formatter = proc do |severity, datetime, _progname, msg|
+        if level == ::Logger::DEBUG
+          "[#{datetime.strftime '%Y-%m-%d %H:%M:%S.%6N'}] #{severity} -- #{msg}\n"
+        else
+          "#{severity}: #{msg}\n"
+        end
+      end
+
+      self.level = ::Logger::INFO
+    end
+
+    def enable_debug_mode
+      self.level = ::Logger::DEBUG
+      debug 'Debug mode enabled'
+    end
+  end
+end

data/lib/puppetdb_cli/query.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'json'
+
+# Add the query command to PuppetDBCLI
+#
+# The query command submits queries to /pdb/query/v4
+module PuppetDBCLI
+  @query_cmd = @base_cmd.define_command do
+    name 'query'
+    usage 'query [options] <query>'
+    summary 'Query puppetdb with AST or PQL'
+
+    flag :h, :help, 'Show help for this command.' do |_, c|
+      c.add_command Cri::Command.new_basic_help
+      puts c.help
+      exit 0
+    end
+
+    run do |opts, args, cmd|
+      PuppetDBCLI::Utils.log_command_start cmd.name, opts, args
+
+      if args.count.zero?
+        PuppetDBCLI.logger.fatal 'No query provided'
+        exit 1
+      elsif args.count > 1
+        PuppetDBCLI.logger.fatal 'More than one argument provided. Try wrapping the query in single quotes.'
+        exit 1
+      end
+      query = args.first
+
+      client = PuppetDBCLI::Utils.open_client_connection opts
+
+      response = PuppetDBCLI::Utils.send_query client, query
+      puts JSON.pretty_generate(response.data)
+    end
+  end
+end

data/lib/puppetdb_cli/utils.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Utils for PuppetDBCLI
+#
+# Primarily used for interaction with the PuppetDB::Client
+module PuppetDBCLI::Utils
+  def self.log_command_start(name, opts, args)
+    PuppetDBCLI.logger.debug "Running the #{name} command"
+    PuppetDBCLI.logger.debug "CLI options: #{opts}"
+    PuppetDBCLI.logger.debug "CLI arguments: #{args.to_a}"
+  end
+
+  def self.construct_config_overrides(cli_opts)
+    {
+      config_file: cli_opts[:config],
+      server_urls: cli_opts[:urls]&.split(','),
+      key: cli_opts[:key],
+      cert: cli_opts[:cert],
+      cacert: cli_opts[:cacert],
+      token_file: cli_opts[:token]
+    }.delete_if { |_, v| v.nil? }
+  end
+
+  def self.open_client_connection(cli_opts)
+    config_overrides = construct_config_overrides cli_opts
+    PuppetDBCLI.logger.debug "Initializing client connection with configuration overrides: #{config_overrides}"
+
+    PuppetDB::Client.new(config_overrides)
+  rescue URI::InvalidURIError => e
+    PuppetDBCLI.logger.fatal "The provided PuppetDB server url was invalid. Failed with message '#{e.message}'"
+    exit 1
+  # This will catch errors like SocketError from HTTParty and RuntimeError from puppetdb-ruby
+  rescue RuntimeError => e
+    PuppetDBCLI.logger.fatal e.message
+    exit 1
+  end
+
+  def self.send_query(client, query)
+    PuppetDBCLI.logger.debug "Sending query request '#{query}'"
+
+    client.request('', query, query_mode: :failover)
+  rescue SocketError => e
+    PuppetDBCLI.logger.fatal e.message
+    exit 1
+  rescue PuppetDB::APIError => e
+    puts e.response
+    PuppetDBCLI.logger.fatal "Last PuppetDB API response code #{e.response&.code}"
+    exit 1
+  end
+end

data/lib/puppetdb_cli/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# PuppetDB CLI version
+module PuppetDBCLI
+  VERSION = '2.0.0'
+end

data/man/puppet-db.pod

@@ -0,0 +1,127 @@
+=head1 NAME
+
+puppet db - manage PuppetDB administrative tasks
+
+=head1 SYNOPSIS
+
+puppet-db [options] <action> [arguments]
+
+=head1 DESCRIPTION
+
+The C<puppet-db> tool allows you to perform PuppetDB administrative tasks such
+as exporting and anonymizing a backup of your PuppetDB or importing a backup to
+a PuppetDB. To learn more about the archive format and these administrative
+tasks in general, consult our documentation at:
+[http://docs.puppetlabs.com/puppetdb/master/anonymization.html]
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-h>,B<--help>
+
+Prints a list of the commands and a brief synopsis of each command. If
+an action is specified, it will print a description of that action and
+the options specific to that action.
+
+=item B<--version>
+
+Displays version information
+
+=item B<-c>,B<--config> <path>
+
+Overrides the path for the PuppetDB CLI config. For more information about
+PuppetDB CLI configuration, see puppetdb_conf(8).
+Default: ~/.puppetlabs/client-tools/puppetdb.conf
+
+=item B<--urls> <str>
+
+Overrides the SERVER_URLS setting for the PuppetDB service. These urls points to
+your PuppetDB instances. You can specify multiple urls as a comma-delimitted
+list, 'http://foo:8080,http://bar.com:8080'.
+
+=item B<--cacert> <path>
+
+Overrides the path for the Puppet CA cert.
+
+=item B<--cert> <path>
+
+Overrides the path for the Puppet client cert.
+
+=item B<--key> <path>
+
+Overrides the path for the Puppet client private key.
+
+=item B<--token> <path>
+
+Overrides the path for the RBAC token (PE only).
+
+=back
+
+=head1 ACTIONS
+
+  $ puppet-db export [options]
+      The export action will export a PuppetDB archive from PuppetDB. The
+      default location of this archive will be './pdb-export.tgz' relative to
+      wherever the command was run from. You can specify a different location to
+      export as an optional argument. Additionally you can specify what level of
+      anonymization you want for your archive using the '--anonymization <str>'
+      flag, for more information about PuppetDB archive anonymization, consult
+      the documentation at:
+      [http://docs.puppetlabs.com/puppetdb/master/anonymization.html]
+
+  $ puppet-db import <path>
+      The import action will import a PuppetDB archive to PuppetDB. You must
+      specify the location of the archive to the import action as a path.
+
+  $ puppet-db status
+      The status action will query the PuppetDB status endpoint (for each
+      configured PuppetDB) and return a map from PuppetDB host to the status for
+      that PuppetDB. For more information about the PuppetDB status endpoint
+      see: [https://docs.puppet.com/puppetdb/latest/api/status/v1/status.html]
+
+=head1 SEE ALSO
+
+puppet-db(8), puppetdb_conf(8)
+
+=head1 EXAMPLES
+
+    --------------------------------------------------------------------
+    Example #1 - Export a PuppetDB archive:
+
+    $ puppet-db export ./my-pdb-export.tgz
+    Exporting PuppetDB...
+    Finished exporting PuppetDB archive to ./my-pdb-export.tgz.
+
+    --------------------------------------------------------------------
+    Example #2 - Import a PuppetDB archive:
+
+    $ puppet-db import ./my-pdb-export.tgz
+    Importing ./my-pdb-export.tgz to PuppetDB...
+    Finished importing ./my-pdb-export.tgz to PuppetDB.
+
+    --------------------------------------------------------------------
+    Example #3 - Query for the status of PuppetDB:
+
+    $ puppet-db status
+    {
+      "puppetdb-status": {
+        "service_version": "4.0.0-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
+        }
+      },
+      "status-service": {
+        "service_version": "0.3.1",
+        "service_status_version": 1,
+        "detail_level": "info",
+        "state": "running",
+        "status": {}
+      }
+    }

data/man/puppet-query.pod

@@ -0,0 +1,83 @@
+=head1 NAME
+
+puppet query - perform ad hoc queries against PuppetDB
+
+=head1 SYNOPSIS
+
+puppet-query [options] <query>
+
+=head1 DESCRIPTION
+
+The C<puppet-query> tool allows you to query PuppetDB using either the AST or
+PQL query languages. To read more about the syntax of PuppetDB queries, please
+consult the documentation at:
+[http://docs.puppetlabs.com/puppetdb/master/api/query/v4/pql.html]
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-h>,B<--help>
+
+Prints a list of the commands and a brief synopsis of each command. If
+an action is specified, it will print a description of that action and
+the options specific to that action.
+
+=item B<--version>
+
+Displays version information
+
+=item B<-c>,B<--config> <path>
+
+Overrides the path for the PuppetDB CLI config. For more information about
+PuppetDB CLI configuration, see puppetdb_conf(8).
+Default: ~/.puppetlabs/client-tools/puppetdb.conf
+
+=item B<--urls> <str>
+
+Overrides the SERVER_URLS setting for the PuppetDB service. These urls points to
+your PuppetDB instances. You can specify multiple urls as a comma-delimitted
+list, 'http://foo:8080,http://bar.com:8080'.
+
+=item B<--cacert> <path>
+
+Overrides the path for the Puppet CA cert.
+
+=item B<--cert> <path>
+
+Overrides the path for the Puppet client cert.
+
+=item B<--key> <path>
+
+Overrides the path for the Puppet client private key.
+
+=item B<--token> <path>
+
+Overrides the path for the RBAC token (PE only).
+
+=back
+
+=head1 SEE ALSO
+
+puppet-db(8), puppetdb_conf(8)
+
+=head1 EXAMPLES
+
+  ----------------------------------------------------------------------
+  $ puppet-query "nodes { certname = 'host-1' }"
+
+  [
+   {
+      "catalog_environment": "production",
+      "catalog_timestamp": "2016-01-28T18:26:04.023Z",
+      "certname": "host-0",
+      "deactivated": null,
+      "expired": null,
+      "facts_environment": "production",
+      "facts_timestamp": "2016-01-28T18:26:02.589Z",
+      "latest_report_hash": "2638652161207e7606d7d2461538d2dae883237b",
+      "latest_report_status": "failed",
+      "report_environment": "production",
+      "report_timestamp": "2016-01-28T18:13:02.405Z"
+   }
+  ]

data/man/puppetdb_conf.pod

@@ -0,0 +1,87 @@
+=head1 NAME
+
+puppetdb_conf - PuppetDB CLI configuration files
+
+=head1 SYNOPSIS
+
+~/.puppetlabs/client-tools/puppetdb.conf
+
+=head1 DESCRIPTION
+
+The `puppet-query` and `puppet-db` commands obtain their configuration from the
+following sources in the following order:
+
+=over 4
+
+=item 1. command-line options
+
+=item 2. ~/.puppetlabs/client-tools/puppetdb.conf
+
+=item 3. /etc/puppetlabs/client-tools/puppetdb.conf
+
+=item 4. hardcoded default PuppetDB url, B<http://127.0.0.1:8080>
+
+=back
+
+The configuration file is in JSON format.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<server_urls>
+
+Either a JSON String (for a single url) or Array (for multiple urls) of your
+PuppetDB servers to query or manage via the CLI commands.
+
+=item B<cacert>
+
+Your site's CA certificate.
+
+=item B<cert>
+
+An SSL certificate signed by your site's Puppet CA.
+
+=item B<key>
+
+The private key for that certificate.
+
+=item B<token-file>
+
+The path for the RBAC token (PE only).
+
+=back
+
+=head1 SEE ALSO
+
+puppet-db(8), puppet-query(8)
+
+=head1 EXAMPLES
+
+    --------------------------------------------------------------------
+    Example #1 - Using a single entry in server_urls:
+
+    {
+        "puppetdb": {
+            "server_urls":"https://alpha-rho.local:8081",
+            "cacert":"<path to ca.pem>",
+            "cert":"<path to cert .pem>",
+            "key":"<path to private-key .pem>"
+        }
+    }
+
+
+    --------------------------------------------------------------------
+    Example #2 - Using multiple server_urls:
+
+    {
+        "puppetdb": {
+            "server_urls":[
+                "https://alpha-rho.local:8081",
+                "https://beta-phi.local:8081"
+            ],
+            "cacert":"<path to ca.pem>",
+            "cert":"<path to cert .pem>",
+            "key":"<path to private-key .pem>"
+        }
+    }