Skip to content
Browse files

Merge branch 'jan_2013_external_sources'

Conflicts:
	.gitignore
	Rakefile
  • Loading branch information...
2 parents c87a8c8 + 662a0fe commit 897d8b2eb38d930c5c2632185122c561998c6cd6 @nfagerlund nfagerlund committed Jan 30, 2013
Showing with 228 additions and 4,821 deletions.
  1. +2 −1 .gitignore
  2. +127 −58 Rakefile
  3. +0 −1 marionette-collective
  4. +17 −0 source/_config.yml
  5. +0 −1 source/mcollective
  6. +0 −99 source/puppetdb/1.1/api/commands.markdown
  7. +0 −91 source/puppetdb/1.1/api/index.markdown
  8. +0 −71 source/puppetdb/1.1/api/query/curl.markdown
  9. +0 −76 source/puppetdb/1.1/api/query/experimental/event.markdown
  10. +0 −72 source/puppetdb/1.1/api/query/experimental/report.markdown
  11. +0 −310 source/puppetdb/1.1/api/query/tutorial.markdown
  12. +0 −62 source/puppetdb/1.1/api/query/v1/facts.markdown
  13. +0 −148 source/puppetdb/1.1/api/query/v1/metrics.markdown
  14. +0 −61 source/puppetdb/1.1/api/query/v1/nodes.markdown
  15. +0 −107 source/puppetdb/1.1/api/query/v1/resources.markdown
  16. +0 −39 source/puppetdb/1.1/api/query/v1/status.markdown
  17. +0 −38 source/puppetdb/1.1/api/query/v2/fact-names.markdown
  18. +0 −111 source/puppetdb/1.1/api/query/v2/facts.markdown
  19. +0 −150 source/puppetdb/1.1/api/query/v2/metrics.markdown
  20. +0 −181 source/puppetdb/1.1/api/query/v2/nodes.markdown
  21. +0 −180 source/puppetdb/1.1/api/query/v2/operators.markdown
  22. +0 −69 source/puppetdb/1.1/api/query/v2/query.markdown
  23. +0 −182 source/puppetdb/1.1/api/query/v2/resources.markdown
  24. +0 −231 source/puppetdb/1.1/api/wire_format/catalog_format.markdown
  25. +0 −32 source/puppetdb/1.1/api/wire_format/facts_format.markdown
  26. +0 −107 source/puppetdb/1.1/api/wire_format/report_format.markdown
  27. +0 −31 source/puppetdb/1.1/community_add_ons.markdown
  28. +0 −406 source/puppetdb/1.1/configure.markdown
  29. +0 −137 source/puppetdb/1.1/connect_puppet_apply.markdown
  30. +0 −132 source/puppetdb/1.1/connect_puppet_master.markdown
  31. BIN source/puppetdb/1.1/images/perf-dash-large.png
  32. BIN source/puppetdb/1.1/images/perf-dash-small.png
  33. +0 −103 source/puppetdb/1.1/index.markdown
  34. +0 −107 source/puppetdb/1.1/install_from_packages.markdown
  35. +0 −247 source/puppetdb/1.1/install_from_source.markdown
  36. +0 −40 source/puppetdb/1.1/install_via_module.markdown
  37. +0 −20 source/puppetdb/1.1/known_issues.markdown
  38. +0 −84 source/puppetdb/1.1/maintain_and_tune.markdown
  39. +0 −119 source/puppetdb/1.1/postgres_ssl.markdown
  40. +0 −93 source/puppetdb/1.1/puppetdb-faq.markdown
  41. +0 −537 source/puppetdb/1.1/release_notes.markdown
  42. +0 −73 source/puppetdb/1.1/repl.markdown
  43. +0 −92 source/puppetdb/1.1/scaling_recommendations.markdown
  44. +0 −87 source/puppetdb/1.1/upgrade.markdown
  45. +0 −35 source/puppetdb/1.1/using.markdown
  46. +82 −0 vendor/bin/git-new-workdir
View
3 .gitignore
@@ -12,4 +12,5 @@ log
pdf_output
pdf_source
puppetdocs-latest.tar.gz*
-.bundle
+.bundle
+externalsources
View
185 Rakefile
@@ -19,18 +19,86 @@ end
$LOAD_PATH.unshift File.expand_path('lib')
references = %w(configuration function indirection metaparameter report type developer)
+top_dir = Dir.pwd
+
+namespace :externalsources do
+
+ # For now, we're using things in the _config.yml, just... because it's there I guess.
+ def load_externalsources
+ require 'yaml'
+ all_config = YAML.load(File.open("source/_config.yml"))
+ return all_config['externalsources']
+ end
+
+ def repo_name(repo_url)
+ repo_url.split('/')[-1].sub(/\.git$/, '')
+ end
+
+ # "Update all working copies defined in source/_config.yml"
+ task :update do
+ Rake::Task['externalsources:clone'].invoke
+ externalsources = load_externalsources
+ Dir.chdir("externalsources") do
+ externalsources.each do |name, info|
+ unless File.directory?(name)
+ puts "Making new working directory for #{name}"
+ system ("#{top_dir}/vendor/bin/git-new-workdir #{repo_name(info['repo'])} #{name} #{info['commit']}")
+ end
+ Dir.chdir(name) do
+ puts "Updating #{name}"
+ system ("git fetch origin && git checkout --force #{info['commit']} && git clean --force .")
+ end
+ end
+ end
+ end
+
+ # "Clone any external documentation repos (from externalsources in source/_config.yml) that don't yet exist"
+ task :clone do
+ externalsources = load_externalsources
+ repos = []
+ externalsources.each do |name, info|
+ repos << info['repo']
+ end
+ Dir.chdir("externalsources") do
+ repos.uniq.each do |repo|
+ system ("git clone #{repo}") unless File.directory?("#{repo_name(repo)}")
+ end
+ end
+ end
+
+ # "Symlink external documentation into place in the source directory"
+ task :link do
+ Rake::Task['externalsources:clean'].invoke # Bad things happen if any of these symlinks already exist, and Jekyll will run FOREVER
+ Rake::Task['externalsources:clean'].reenable
+ externalsources = load_externalsources
+ externalsources.each do |name, info|
+ # Have to use absolute paths for the source, since we have no idea how deep in the hierarchy info['url'] is (and thus how many ../..s it would need).
+ FileUtils.ln_sf "#{top_dir}/externalsources/#{name}/#{info['subdirectory']}", "source#{info['url']}"
+ end
+ end
+
+ # "Clean up any external source symlinks from the source directory" # In the current implementation, all external sources are symlinks and there are no other symlinks in the source. This means we can naively kill all symlinks in ./source.
+ task :clean do
+ system("find ./source -type l -print0 | xargs -0 rm")
+ end
+end
desc "Generate the documentation"
task :generate do
+ Rake::Task['externalsources:update'].invoke # Create external sources if necessary, and check out the required working directories
+ Rake::Task['externalsources:link'].invoke # Link docs folders from external sources into the source at the appropriate places.
+
system("mkdir -p output")
system("rm -rf output/*")
system("mkdir output/references")
- Dir.chdir("source")
- system("bundle exec jekyll ../output")
+ Dir.chdir("source") do
+ system("bundle exec jekyll ../output")
+ end
+
Rake::Task['references:symlink'].invoke
- Dir.chdir("..")
- puts Dir.pwd
-
+
+ Rake::Task['externalsources:clean'].invoke # The opposite of externalsources:link. Delete all symlinks in the source.
+ Rake::Task['externalsources:clean'].reenable
end
@@ -50,55 +118,56 @@ task :generate_pdf do
system("cp -rf source pdf_source")
system("cp -rf pdf_mask/* pdf_source") # Copy in and/or overwrite differing files
# The point being, this way we don't have to maintain separate copies of the actual source files, and it's clear which things are actually different for the PDF version of the page.
- Dir.chdir("pdf_source")
- system("bundle exec jekyll ../pdf_output")
+ Dir.chdir("pdf_source") do
+ system("bundle exec jekyll ../pdf_output")
+ end
Rake::Task['references:symlink:for_pdf'].invoke
- Dir.chdir("../pdf_output")
- pdf_targets = YAML.load(File.open("../pdf_mask/pdf_targets.yaml"))
- pdf_targets.each do |target, pages|
- system("cat #{pages.join(' ')} > #{target}")
- if target == 'puppetdb1.html'
- content = File.read('puppetdb1.html')
- content.gsub!('-puppetdb-1-install_from_source-html-step-3-option-b-manually-create-a-keystore-and-truststore', '-puppetdb-1-install_from_source-html-step-3-option-b-manuallu-create-a-keystore-and-truststore')
- File.open('puppetdb1.html', "w") {|pdd1| pdd1.print(content)}
- # Yeah, so, I found the magic string that, when used as an element ID and then
- # linked to from elsewhere in the document, causes wkhtmltopdf to think an
- # unthinkable thought and corrupt the output file.
- # Your guess is as good as mine. #doomed #sorcery #wat
- # >:|
- # -NF
+ Dir.chdir("../pdf_output") do
+ pdf_targets = YAML.load(File.open("../pdf_mask/pdf_targets.yaml"))
+ pdf_targets.each do |target, pages|
+ system("cat #{pages.join(' ')} > #{target}")
+ if target == 'puppetdb1.html'
+ content = File.read('puppetdb1.html')
+ content.gsub!('-puppetdb-1-install_from_source-html-step-3-option-b-manually-create-a-keystore-and-truststore', '-puppetdb-1-install_from_source-html-step-3-option-b-manuallu-create-a-keystore-and-truststore')
+ File.open('puppetdb1.html', "w") {|pdd1| pdd1.print(content)}
+ # Yeah, so, I found the magic string that, when used as an element ID and then
+ # linked to from elsewhere in the document, causes wkhtmltopdf to think an
+ # unthinkable thought and corrupt the output file.
+ # Your guess is as good as mine. #doomed #sorcery #wat
+ # >:|
+ # -NF
+ end
end
end
# system("cat `cat ../pdf_source/page_order.txt` > rebuilt_index.html")
# system("mv index.html original_index.html")
# system("mv rebuilt_index.html index.html")
puts "Remember to run rake serve_pdf"
puts "Remember to run rake compile_pdf (while serving on localhost:9292)"
- Dir.chdir("..")
end
desc "Temporary task for debugging PDF compile failures"
task :reshuffle_pdf do
require 'yaml'
- Dir.chdir("pdf_output")
- pdf_targets = YAML.load(File.open("../pdf_mask/pdf_targets.yaml"))
- pdf_targets.each do |target, pages|
- system("cat #{pages.join(' ')} > #{target}")
- if target == 'puppetdb1.html'
- content = File.read('puppetdb1.html')
- content.gsub!('-puppetdb-1-install_from_source-html-step-3-option-b-manually-create-a-keystore-and-truststore', '-puppetdb-1-install_from_source-html-step-3-option-b-manuallu-create-a-keystore-and-truststore')
- File.open('puppetdb1.html', "w") {|pdd1| pdd1.print(content)}
- # Yeah, so, I found the magic string that, when used as an element ID and then
- # linked to from elsewhere in the document, causes wkhtmltopdf to think an
- # unthinkable thought and corrupt the output file.
- # Your guess is as good as mine. #doomed #sorcery #wat
- # >:|
- # -NF
+ Dir.chdir("pdf_output") do
+ pdf_targets = YAML.load(File.open("../pdf_mask/pdf_targets.yaml"))
+ pdf_targets.each do |target, pages|
+ system("cat #{pages.join(' ')} > #{target}")
+ if target == 'puppetdb1.html'
+ content = File.read('puppetdb1.html')
+ content.gsub!('-puppetdb-1-install_from_source-html-step-3-option-b-manually-create-a-keystore-and-truststore', '-puppetdb-1-install_from_source-html-step-3-option-b-manuallu-create-a-keystore-and-truststore')
+ File.open('puppetdb1.html', "w") {|pdd1| pdd1.print(content)}
+ # Yeah, so, I found the magic string that, when used as an element ID and then
+ # linked to from elsewhere in the document, causes wkhtmltopdf to think an
+ # unthinkable thought and corrupt the output file.
+ # Your guess is as good as mine. #doomed #sorcery #wat
+ # >:|
+ # -NF
+ end
end
end
puts "Remember to run rake serve_pdf"
puts "Remember to run rake compile_pdf (while serving on localhost:9292)"
- Dir.chdir("..")
end
@@ -121,10 +190,10 @@ end
desc "Create tarball of documentation"
task :tarball do
tarball_name = "puppetdocs-latest.tar.gz"
- FileUtils.cd 'output'
- sh "tar -czf #{tarball_name} *"
- FileUtils.mv tarball_name, '..'
- FileUtils.cd '..'
+ FileUtils.cd('output') do
+ sh "tar -czf #{tarball_name} *"
+ FileUtils.mv tarball_name, '..'
+ end
sh "git rev-parse HEAD > #{tarball_name}.version" if File.directory?('.git') # Record the version of this tarball, but only if we're in a git repo.
end
@@ -141,19 +210,19 @@ namespace :references do
namespace :symlink do
- desc "Show the versions that will be symlinked"
+ # "Show the versions that will be symlinked"
task :versions do
require 'puppet_docs'
PuppetDocs::Reference.special_versions.each do |name, (version, source)|
puts "#{name}: #{version}"
end
end
- desc "Symlink the latest & stable directories when generating a flat page for PDFing"
+ # "Symlink the latest & stable directories when generating a flat page for PDFing"
task :for_pdf do
require 'puppet_docs'
PuppetDocs::Reference.special_versions.each do |name, (version, source)|
- Dir.chdir '../pdf_output/references' do
+ Dir.chdir 'pdf_output/references' do
FileUtils.ln_sf version.to_s, name.to_s
end
end
@@ -162,11 +231,11 @@ namespace :references do
end
- desc "Symlink the latest & stable directories"
+ # "Symlink the latest & stable directories"
task :symlink do
require 'puppet_docs'
PuppetDocs::Reference.special_versions.each do |name, (version, source)|
- Dir.chdir '../output/references' do
+ Dir.chdir 'output/references' do
FileUtils.ln_sf version.to_s, name.to_s
end
end
@@ -175,7 +244,7 @@ namespace :references do
namespace :puppetdoc do
references.each do |name|
- desc "Write references/VERSION/#{name}"
+ # "Write references/VERSION/#{name}"
task name => 'references:check_version' do
require 'puppet_docs'
PuppetDocs::Reference::Generator.new(ENV['VERSION'], name).generate
@@ -189,7 +258,7 @@ namespace :references do
namespace :index do
- desc "Generate a stub index for VERSION"
+ # "Generate a stub index for VERSION"
task :stub => 'references:check_version' do
filename = Pathname.new('source/references') + ENV['VERSION'] + 'index.markdown'
filename.parent.mkpath
@@ -218,9 +287,9 @@ namespace :references do
end
task :fetch_tags do
- Dir.chdir("vendor/puppet")
- sh "git fetch --tags"
- Dir.chdir("../..")
+ Dir.chdir("vendor/puppet") do
+ sh "git fetch --tags"
+ end
end
desc "Update the contents of source/man/{app}.markdown" # Note that the index must be built manually if new applications are added. Also, let's not ever have a `puppet index` command.
@@ -257,10 +326,10 @@ end
task :default => :spec
-require 'rdoc/task'
-Rake::RDocTask.new do |rdoc|
- rdoc.rdoc_dir = 'rdoc'
- rdoc.title = "puppet-docs"
- rdoc.rdoc_files.include('README*')
- rdoc.rdoc_files.include('lib/**/*.rb')
-end
+# require 'rdoc/task'
+# Rake::RDocTask.new do |rdoc|
+# rdoc.rdoc_dir = 'rdoc'
+# rdoc.title = "puppet-docs"
+# rdoc.rdoc_files.include('README*')
+# rdoc.rdoc_files.include('lib/**/*.rb')
+# end
1 marionette-collective
@@ -1 +0,0 @@
-Subproject commit fabf25c7235f8a5099c2634a3416fa86bf2d110c
View
17 source/_config.yml
@@ -18,4 +18,21 @@ defaultnav:
/hiera/1: hiera1.html
destination: ../output
url: "http://docs.puppetlabs.com"
+externalsources:
+ puppetdb_1.1:
+ url: /puppetdb/1.1
+ repo: git://github.com/puppetlabs/puppetdb.git
+ # Change this to origin/1.1.x once puppetdb team cuts a branch
+ commit: origin/master
+ subdirectory: documentation
+ puppetdb_master:
+ url: /puppetdb/master
+ repo: git://github.com/puppetlabs/puppetdb.git
+ commit: origin/master
+ subdirectory: documentation
+ marionette-collective:
+ url: /mcollective
+ repo: git://github.com/puppetlabs/marionette-collective.git
+ commit: origin/master
+ subdirectory: website
---
View
1 source/mcollective
View
99 source/puppetdb/1.1/api/commands.markdown
@@ -1,99 +0,0 @@
----
-title: "PuppetDB 1.1 » API » Commands"
-layout: default
-canonical: "/puppetdb/1.1/api/commands.html"
----
-
-[facts]: ./wire_format/facts_format.html
-[catalog]: ./wire_format/catalog_format.html
-[report]: ./wire_format/report_format.html
-
-Commands are used to change PuppetDB's
-model of a population. Commands are represented by `command objects`,
-which have the following JSON wire format:
-
- {"command": "...",
- "version": 123,
- "payload": <json object>}
-
-`command` is a string identifying the command.
-
-`version` is a JSON integer describing what version of the given
-command you're attempting to invoke.
-
-`payload` must be a valid JSON object of any sort. It's up to an
-individual handler function to determine how to interpret that object.
-
-The entire command MUST be encoded as UTF-8.
-
-## Command submission
-
-Commands are submitted via HTTP to the `/commands/` URL and must
-conform to the following rules:
-
-* A `POST` is used
-* There is a parameter, `payload`, that contains the entire command object as
- outlined above. (Not to be confused with the `payload` field inside the command object.)
-* There is an `Accept` header that contains `application/json`.
-* The POST body is url-encoded
-* The content-type is `x-www-form-urlencoded`.
-
-Optionally, there may be a parameter, `checksum`, that contains a SHA-1 hash of
-the payload which will be used for verification.
-
-When a command is successfully submitted, the submitter will
-receive the following:
-
-* A response code of 200
-* A content-type of `application/json`
-* A response body in the form of a JSON object, containing a single key 'uuid', whose
- value is a UUID corresponding to the submitted command. This can be used, for example, by
- clients to correlate submitted commands with server-side logs.
-
-The terminus plugins for puppet masters use this command API to update facts, catalogs, and reports for nodes.
-
-## Command Semantics
-
-Commands are processed _asynchronously_. If PuppetDB returns a 200
-when you submit a command, that only indicates that the command has
-been _accepted_ for processing. There are no guarantees as to when
-that command will be processed, nor that when it is processed it will
-be successful.
-
-Commands that fail processing will be stored in files in the "dead
-letter office", located under the MQ data directory, in
-`discarded/<command>`. These files contain the command and diagnostic
-information that may be used to determine why the command failed to be
-processed.
-
-## List of Commands
-
-### "replace catalog", version 1
-
-The payload is expected to be a Puppet catalog, as a JSON string, including the
-fields of the [catalog wire format][catalog]. Extra fields are
-ignored.
-
-### "replace catalog", version 2
-
-The payload is expected to be a Puppet catalog, as either a JSON string or an
-object, conforming exactly to the [catalog wire
-format][catalog]. Extra or missing fields are an error.
-
-### "replace facts", version 1
-
-The payload is expected to be a set of facts, as a JSON string, conforming to
-the [fact wire format][facts]
-
-### "deactivate node", version 1
-
-The payload is expected to be the name of a node, as a JSON string, which will be deactivated
-effective as of the time the command is *processed*.
-
-## Experimental commands
-
-### "store report", version 1
-
-The payload is expected to be a report, containing events that occurred on Puppet
-resources. It is structured as a JSON object, confirming to the
-[report wire format][report].
View
91 source/puppetdb/1.1/api/index.markdown
@@ -1,91 +0,0 @@
----
-title: "PuppetDB 1.1 » API » Overview"
-layout: default
-canonical: "/puppetdb/1.1/api/index.html"
----
-
-[commands]: ./commands.html
-[terminus]: ../connect_puppet_master.html
-
-Since PuppetDB collects lots of data from Puppet, it's an ideal platform for new tools and applications that use that data. You can use the HTTP API described in these pages to interact with PuppetDB's data.
-
-Summary
------
-
-PuppetDB's API uses a Command/Query Responsibility Separation (CQRS) pattern. This means:
-
-* Data can be **queried** using a standard REST-style API. Queries are processed immediately.
-* When **making changes** to data (facts, catalogs, etc), you must send an explicit **command** (as opposed to submitting data without comment and letting the receiver determine intent). Commands are processed asynchronously in FIFO order.
-
-The PuppetDB API consists of the following parts:
-
-* [The REST interface for queries](#queries)
-* [The HTTP command submission interface](#commands)
-* [The wire formats that PuppetDB requires for incoming data](#wire-formats)
-
-Queries
------
-
-PuppetDB 1.1 supports versions 1 and 2 of the query API. Version 1 is backwards-compatible with PuppetDB 1.0.x, but version 2 has significant new capabilities, including subqueries.
-
-PuppetDB's data can be queried with a REST API.
-
-* [Specification of the General Query Structure](./query/v2/query.html)
-* [Available Operators](./query/v2/operators.html)
-* [Query Tutorial](./query/tutorial.html)
-* [Curl Tips](./query/curl.html)
-
-The available query endpoints are documented in the pages linked below.
-
-### Query Endpoints
-
-#### Version 2
-
-Version 2 of the query API adds new endpoints, and introduces subqueries and regular expression operators for more efficient requests and better insight into your data. The following endpoints will continue to work for the foreseeable future.
-
-* [Facts Endpoint](./query/v2/facts.html)
-* [Resources Endpoint](./query/v2/resources.html)
-* [Nodes Endpoint](./query/v2/nodes.html)
-* [Fact-Names Endpoint](./query/v2/fact-names.html)
-* [Metrics Endpoint](./query/v2/metrics.html)
-
-#### Version 1
-
-Version 1 of the query API works with PuppetDB 1.1 and 1.0. It isn't deprecated, but we encourage you to use version 2 if you can.
-
-In PuppetDB 1.0, you could access the version 1 endpoints without the `/v1/` prefix. This still works but **is now deprecated,** and we currently plan to remove support in PuppetDB 2.0. Please change your version 1 applications to use the `/v1/` prefix.
-
-* [Facts Endpoint](./query/v1/facts.html)
-* [Resources Endpoint](./query/v1/resources.html)
-* [Nodes Endpoint](./query/v1/nodes.html)
-* [Status Endpoint](./query/v1/status.html)
-* [Metrics Endpoint](./query/v1/metrics.html)
-
-#### Experimental
-
-These endpoints are not yet set in stone, and their behavior may change at any time without regard for normal versioning rules. We invite you to play with them, but you should be ready to adjust your application on your next upgrade.
-
-* [Report Endpoint](./query/experimental/report.html)
-* [Event Endpoint](./query/experimental/event.html)
-
-Commands
------
-
-Commands are sent via HTTP but do not use a REST-style interface.
-
-PuppetDB supports a relatively small number of commands. The command submission interface and the available commands are all described at the commands page:
-
-* [Commands (all commands, all API versions)][commands]
-
-Unlike the query API, these commands are generally only useful to Puppet itself, and all format conversion and command submission is handled by the [PuppetDB terminus plugins][terminus] on your puppet master.
-
-The "replace" commands all require data in one of the wire formats described below.
-
-Wire Formats
------
-
-All of PuppetDB's "replace" commands contain payload data, which must be in one of the following formats. These formats are also linked from the [commands](#commands) that use them.
-
-* [Facts wire format](./wire_format/facts_format.html)
-* [Catalog wire format](./wire_format/catalog_format.html)
-* [Report wire format (experimental)](./wire_format/report_format.html)
View
71 source/puppetdb/1.1/api/query/curl.markdown
@@ -1,71 +0,0 @@
----
-layout: default
-title: "PuppetDB 1.1 » API » Query » Curl Tips"
-canonical: "/puppetdb/1.1/api/query/curl.html"
----
-
-[Facts]: ./v2/facts.html
-[Nodes]: ./v2/nodes.html
-[fact-names]: ./v2/fact-names.html
-[Resources]: ./v2/resources.html
-[Metrics]: ./v2/metrics.html
-[curl]: http://curl.haxx.se/docs/manpage.html
-[dashboard]: ../../maintain_and_tune.html#monitor-the-performance-dashboard
-[whitelist]: ../../configure.html#certificate-whitelist
-
-
-You can use [`curl`][curl] to directly interact with PuppetDB's REST API. This is useful for testing, prototyping, and quickly fetching arbitrary data.
-
-The instructions below are simplified. For full usage details, see [the curl manpage][curl] . For additional examples, please see the docs for the individual REST endpoints:
-
-* [facts][]
-* [fact-names][]
-* [nodes][]
-* [resources][]
-* [metrics][]
-
-## Using `curl` From `localhost` (Non-SSL/HTTP)
-
-With its default settings, PuppetDB accepts unsecured HTTP connections at port 8080 on `localhost`. This allows you to SSH into the PuppetDB server and run curl commands without specifying certificate information:
-
- curl -H "Accept: application/json" 'http://localhost:8080/v2/facts/<node>'
- curl -H "Accept: application/json" 'http://localhost:8080/v2/metrics/mbean/java.lang:type=Memory'
-
-If you have allowed unsecured access to other hosts in order to [monitor the dashboard][dashboard], these hosts can also use plain HTTP curl commands.
-
-## Using `curl` From Remote Hosts (SSL/HTTPS)
-
-To make secured requests from other hosts, you will need to supply the following via the command line:
-
-* Your site's CA certificate (`--cacert`)
-* An SSL certificate signed by your site's Puppet CA (`--cert`)
-* The private key for that certificate (`--key`)
-
-Any node managed by puppet agent will already have all of these and you can re-use them for contacting PuppetDB. You can also generate a new cert on the CA puppet master with the `puppet cert generate` command.
-
-> **Note:** If you have turned on [certificate whitelisting][whitelist], you must make sure to authorize the certificate you are using.
-
- curl -H "Accept: application/json" 'https://<your.puppetdb.server>:8081/v2/facts/<node>' --cacert /etc/puppet/ssl/certs/ca.pem --cert /etc/puppet/ssl/certs/<node>.pem --key /etc/puppet/ssl/private_keys/<node>.pem
-
-### Locating Puppet Certificate Files
-
-Locate Puppet's `ssldir` as follows:
-
- $ sudo puppet config print ssldir
-
-Within this directory:
-
-* The CA certificate is found at `certs/ca.pem`
-* The corresponding private key is found at `private_keys/<name>.pem`
-* Other certificates are found at `certs/<name>.pem`
-
-
-## Dealing with complex query strings
-
-Many query strings will contain characters like `[` and `]`, which must be URL-encoded. To handle this, you can use `curl`'s `--data-urlencode` option.
-
-If you do this with an endpoint that accepts `GET` requests, **you must also use the `-G` or `--get` option.** This is because `curl` defaults to `POST` requests when the `--data-urlencode` option is present.
-
- curl -G -H "Accept: application/json" 'http://localhost:8080/v2/nodes' --data-urlencode 'query=["=", ["node", "active"], true]'
-
-
View
76 source/puppetdb/1.1/api/query/experimental/event.markdown
@@ -1,76 +0,0 @@
----
-title: "PuppetDB 1.1 » API » Experimental » Querying Events"
-layout: default
-canonical: "/puppetdb/1.1/api/query/experimental/event.html"
----
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-[report]: ./report.html
-
-# Events
-
-Querying events from reports is accomplished by making an HTTP request to the
-`/events` REST endpoint.
-
-# Query format
-
-* The HTTP method must be `GET`.
-
-* There must be an `Accept` header specifying `application/json`.
-
-* The `query` parameter is a JSON array of query predicates, in prefix
- form, conforming to the format described below.
-
-The `query` parameter is described by the following grammar:
-
- query: [ {match} {field} {value} ]
- field: string
- match: "="
-
-`field` may be any of:
-
-`report`: the unique id of the report; this is a hash built up from the contents
- of the report which allow us to distinguish it from other reports. These ids
- can be acquired via the [`/reports`][report] query endpoint.
-
-For example, for all events in the report with id
-'38ff2aef3ffb7800fe85b322280ade2b867c8d27', the JSON query structure would be:
-
- ["=", "report", "38ff2aef3ffb7800fe85b322280ade2b867c8d27"]
-
-# Response format
-
- The response is a JSON array of events that matched the input parameters.
- The events are sorted by their timestamps, in descending order:
-
-`[
- {
- "old-value": "absent",
- "property": "ensure",
- "timestamp": "2012-10-30T19:01:05.000Z",
- "resource-type": "File",
- "resource-title": "/tmp/reportingfoo",
- "new-value": "file",
- "message": "defined content as '{md5}49f68a5c8493ec2c0bf489821c21fc3b'",
- "report": "38ff2aef3ffb7800fe85b322280ade2b867c8d27",
- "status": "success"
- },
- {
- "old-value": "absent",
- "property": "message",
- "timestamp": "2012-10-30T19:01:05.000Z",
- "resource-type": "Notify",
- "resource-title": "notify, yo",
- "new-value": "notify, yo",
- "message": "defined 'message' as 'notify, yo'",
- "report": "38ff2aef3ffb7800fe85b322280ade2b867c8d27",
- "status": "success"
- }
- ]`
-
-
-# Example
-
-[You can use `curl`][curl] to query information about events like so:
-
- curl -G -H "Accept: application/json" 'http://localhost:8080/experimental/events' --data-urlencode 'query=["=", "report", "38ff2aef3ffb7800fe85b322280ade2b867c8d27"]'
View
72 source/puppetdb/1.1/api/query/experimental/report.markdown
@@ -1,72 +0,0 @@
----
-title: "PuppetDB 1.1 » API » Experimental » Querying Reports"
-layout: default
-canonical: "/puppetdb/1.1/api/query/experimental/report.html"
----
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-# Reports
-
-Querying reports is accomplished by making an HTTP request to the `/reports` REST
-endpoint.
-
-# Query format
-
-* The HTTP method must be `GET`.
-
-* There must be an `Accept` header specifying `application/json`.
-
-* The `query` parameter is a JSON array of query predicates, in prefix
- form, conforming to the format described below.
-
-The `query` parameter is described by the following grammar:
-
- query: [ {match} {field} {value} ]
- field: string
- match: "="
-
-`field` may be any of:
-
-`certname`
-: the name of the node associated with the report
-
-For example, for all reports run on the node with certname 'example.local', the
-JSON query structure would be:
-
- ["=", "certname", "example.local"]
-
-# Response format
-
-The response is a JSON array of report summaries for all reports
-that matched the input parameters. The summaries are sorted by
-the completion time of the report, in descending order:
-
-`[
- {
- "end-time": "2012-10-29T18:38:01.000Z",
- "puppet-version": "3.0.1",
- "receive-time": "2012-10-29T18:38:04.238Z",
- "configuration-version": "1351535883",
- "start-time": "2012-10-29T18:38:00.000Z",
- "id": "d4bcb35a-fb7b-45da-84e0-fceb7a1df713",
- "certname": "foo.local",
- "report-format": 3
- },
- {
- "end-time": "2012-10-26T22:39:32.000Z",
- "puppet-version": "3.0.1",
- "receive-time": "2012-10-26T22:39:35.305Z",
- "configuration-version": "1351291174",
- "start-time": "2012-10-26T22:39:31.000Z",
- "id": "5ec13ff5-c6fd-43fb-b5b1-59a00ec8e1f1",
- "certname": "foo.local",
- "report-format": 3
- }
-]`
-
-# Example
-
-[You can use `curl`][curl] to query information about reports like so:
-
- curl -G -H "Accept: application/json" 'http://localhost:8080/experimental/reports' --data-urlencode 'query=["=", "certname", "example.local"]'
View
310 source/puppetdb/1.1/api/query/tutorial.markdown
@@ -1,310 +0,0 @@
----
-title: "PuppetDB 1.1 » API » Query Tutorial"
-layout: default
-canonical: "/puppetdb/1.1/api/query/tutorial.html"
----
-
-This page is a walkthrough for constructing several types of PuppetDB queries. It uses the **version 2 API** in all of its examples; however, most of the general principles are also applicable to the version 1 API.
-
-If you need to use the v1 API, note that it lacks many of v2's capabilities, and be sure to consult the v1 endpoint references before attempting to use these examples with it.
-
-## How to query
-
-Queries are performed by performing a GET request to an endpoint URL and supplying a querystring parameter called `query`,
-which contains the query to execute. Results are always returned in
-`application/json` form. A curl command like the following can be used to
-easily try queries from the command line:
-
-`curl -H 'Accept: application/json' -X GET http://puppetdb:8080/v2/<resources-or-facts> --data-urlencode query@<filename>`
-
-where `filename` contains the query to execute.
-
-## Resources Walkthrough
-
-### Our first query
-
-Let's start by taking a look at a simple resource query. Suppose we want to
-find the user "nick" on every node. We can use this query:
-
- ["and",
- ["=", "type", "User"],
- ["=", "title", "nick"]]
-
-This query has two `"="` clauses, which both must be true.
-
-In general, the `"="` operator follows a specific structure:
-
-`["=", <attribute to compare>, <value>]`
-
-In this case, the attributes are "type" and "title", and the values are "User"
-and "nick".
-
-The `"and"` operator also has a well-defined structure:
-
-`["and", <query clause>, <query clause>, <query clause>, ...]`
-
-The query clauses can be any legal query (including another `"and"`). At least
-one clause has to be specified, and all the clauses have to be true for the
-`"and"` clause to be true. An `"or"` operator is also available, which looks
-just like the `"and"` operator, except that, as you'd expect, it's true if
-*any* specified clause is true.
-
-The query format is declarative; it describes conditions the results must
-satisfy, not how to find them. So the order of the clauses is irrelevant.
-Either the type clause or the title clause could come first, without affecting
-the performance or the results of the query.
-
-If we execute this query against the `/resources` route, we get results that
-look something like this:
-
- [{
- "parameters" : {
- "comment" : "Nick Lewis",
- "uid" : "1115",
- "shell" : "/bin/bash",
- "managehome" : false,
- "gid" : "allstaff",
- "home" : "/home/nick",
- "groups" : "developers",
- "ensure" : "present"
- },
- "sourceline" : 111,
- "sourcefile" : "/etc/puppet/manifests/user.pp",
- "exported" : false,
- "tags" : [ "firewall", "default", "node", "nick", "role::base", "users", "virtual", "user", "account", "base", "role::firewall::office", "role", "role::firewall", "class", "account::user", "office", "virtual::users", "allstaff" ],
- "title" : "nick",
- "type" : "User",
- "resource" : "0ae7e1230e4d540caa451d0ade2424f316bfbf39",
- "certname" : "foo.example.com"
- }]
-
-Our results are an array of "resources", where each resource is an object with
-a particular set of keys.
-
-parameters: this field is itself an object, containing all the parameters and values of the resource
-sourceline: the line the resource was declared on
-sourcefile: the file the resource was specified in
-exported: true if the resource was exported by this node, or false otherwise
-tags: all the tags on the resource
-title: the resource title
-type: the resource type
-resources: this is an internal identifier for the resource used by PuppetDB
-certname: the node that the resource came from
-
-There will be an entry in the list for every resource. A resource is specific
-to a single node, so if the resource is on 100 nodes, there will be 100 copies
-of the resource (each with at least a different certname field).
-
-### Excluding results
-
-We know this instance of the user "nick" is defined on line 111 of
-/etc/puppet/manifests/user.pp. What if
-we want to check whether or not we define the same resource somewhere else?
-After all, if we're repeating ourselves, something may be wrong! Fortunately,
-there's an operator to help us:
-
- ["and",
- ["=", "type", "User"],
- ["=", "title", "nick"],
- ["not",
- ["and",
- ["=", "sourceline", "/etc/puppet/manifests/user.pp"],
- ["=", "sourcefile", 111]]]]
-
-The `"not"` operator wraps another clause, and returns results for which the
-clause is *not* true. In this case, we want resources which aren't defined on
-line 111 of /etc/puppet/manifests/user.pp.
-
-### Resource attributes
-
-So far we've seen that we can query for resources based on their `certname`,
-`type`, `title`, `sourcefile`, and `sourceline`. There are a few more available:
-
- ["and",
- ["=", "tag", "foo"],
- ["=", "exported", true],
- ["=", ["parameter", "ensure"], "present"]]
-
-This query returns resources whose set of tags *contains* the tag
-"foo", and which are exported, and whose "ensure" parameter is
-"present". Because the parameter name can take any value (including
-that of another attribute), it must be namespaced using
-`["parameter", <parameter name>]`.
-
-The full set of queryable attributes can be found in [the resource
-endpoint documentation](./v2/resources.html) for easy reference.
-
-### Regular expressions
-
-What if we want to restrict our results to a certain subset of nodes? Certainly, we could do something like:
-
- ["or",
- ["=", "certname", "www1.example.com"],
- ["=", "certname", "www2.example.com"],
- ["=", "certname", "www3.example.com"]]
-
-And this works great if we know exactly the set of nodes we want. But what if
-we want all the 'www' servers, regardless of how many we have? In this case, we
-can use the regular expression match operator `~`:
-
- ["~", "certname", "www\\d+\\.example\\.com"]
-
-Notice that, because our regular expression is specified inside a string, the
-backslash characters must be escaped. The rules for which constructs can be
-used in the regexp depend on which database is in use, so common features
-should be used for interoperability. The regexp operator can be used on every
-field of resources except for parameters, and `exported`.
-
-## Facts Walkthrough
-
-In addition to resources, we can also query for facts. This looks similar,
-though the available fields and operators are a bit different. Some things are
-the same, though. For instance, support you want all the facts for a certain
-node:
-
- ["=", "certname", "foo.example.com"]
-
-This gives results that look something like this:
-
- [ {
- "certname" : "foo.example.com",
- "name" : "architecture",
- "value" : "amd64"
- }, {
- "certname" : "foo.example.com",
- "name" : "fqdn",
- "value" : "foo.example.com"
- }, {
- "certname" : "foo.example.com",
- "name" : "hostname",
- "value" : "foo"
- }, {
- "certname" : "foo.example.com",
- "name" : "ipaddress",
- "value" : "192.168.100.102"
- }, {
- "certname" : "foo.example.com",
- "name" : "kernel",
- "value" : "Linux"
- }, {
- "certname" : "foo.example.com",
- "name" : "kernelversion",
- "value" : "2.6.32"
- } ]
-
-### Fact attributes
-
-In the last query, we saw that a "fact" consists of a "certname", a "name", and
-a "value". As you might expect, we can query using "name" or "value".
-
- ["and",
- ["=", "name", "operatingsystem"],
- ["=", "value", "Debian"]]
-
-This will find all the "operatingsystem = Debian" facts, and their
-corresponding nodes. As you see, "and" is supported for facts, as are "or" and
-"not".
-
-### Fact operators
-
-As with resources, facts also support the `~` regular expression match
-operator, for all their fields. In addition to that, numeric comparisons are
-supported for fact values:
-
- ["and",
- ["=", "name", "uptime_seconds"],
- [">=", "value", 100000],
- ["<", "value", 1000000]]
-
-This will find nodes for which the uptime_seconds fact is in the half-open
-range [100000, 1000000). Numeric comparisons will *always be false* for fact
-values which are not numeric. Importantly, version numbers such as 2.6.12 are
-not numeric, and the numeric comparison operators can't be used with them at
-this time.
-
-## Nodes Walkthrough
-
-We can also query for nodes. Once again, this is quite similar to resource and
-fact queries:
-
- ["=", "name", "foo.example.com"]
-
-The result of this query is:
-
- ["foo.example.com"]
-
-This will find the node foo.example.com. Note that the results of a node query
-contain only the node names, rather than an object with multiple fields as with
-resources and facts.
-
-### Querying on facts
-
-Nodes can also be queried based on their facts, using the same operators as for
-fact queries:
-
- ["and",
- ["=", ["fact", "operatingsystem"], "Debian"],
- ["<", ["fact", "uptime_seconds"], 10000]]
-
-This will return Debian nodes with uptime_seconds < 10000.
-
-## Subquery Walkthrough
-
-The queries we've looked at so far are quite powerful and useful, but what if
-your query needs to consider both resources *and* facts? For instance, suppose
-you need the IP address of your Apache servers, to configure a load balancer.
-You could find those servers using this resource query:
-
- ["and",
- ["=", "type", "Class"],
- ["=", "title", "Apache"]]
-
-This will find all the Class[Apache] resources, which each knows the certname
-of the node it came from. Then you could put all those certnames into a fact
-query:
-
- ["and",
- ["=", "name", "ipaddress"],
- ["or",
- ["=", "certname", "a.example.com"],
- ["=", "certname", "b.example.com"],
- ["=", "certname", "c.example.com"],
- ["=", "certname", "d.example.com"],
- ["=", "certname", "e.example.com"]]]
-
-But this query is lengthy, and it requires some logic to assemble and run the
-second query. No, there has to be a better way. What if we could find the
-Class[Apache] servers and use the results of that directly to find the
-certname? It turns out we can, with this fact query:
-
- ["and",
- ["=", "name", "ipaddress"],
- ["in", "certname",
- ["extract", "certname", ["select-resources",
- ["and",
- ["=", "type", "Class"],
- ["=", "title", "Apache"]]]]
-
-This may appear a little daunting, so we'll look at it piecewise.
-
-Let's start with "select-resources". This operator takes one argument, which is
-a resource query, and returns the results of that query, in exactly the form
-you would expect to see them if you did a plain resource query.
-
-We then use an operator called "extract" to turn our list of resources into
-just a list of certnames. So we now conceptually have something like
-
- ["in", "certname", ["foo.example.com", "bar.example.com", "baz.example.com"]]
-
-The "in" operator matches facts whose "certname" is in the supplied list. (For
-now, that list has to be generated from a subquery, and can't be supplied
-directly in the query, so if you want a literal list, you'll unfortunately
-still have to use a combination of "or" and "="). At this point, our query
-seems a lot like the one above, except we didn't have to specify exactly which
-certnames to use, and instead we get them in the same query.
-
-Similarly, there is a "select-facts" operator which will perform a fact
-subquery. Either kind of subquery is usable from every kind of query (facts,
-resources, and nodes), subqueries may be nested, and multiple subqueries may be
-used in a single query. Finding use cases for some of those combinations is
-left as an exercise to the reader.
View
62 source/puppetdb/1.1/api/query/v1/facts.markdown
@@ -1,62 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v1 » Querying Facts"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v1/facts.html"
----
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-Querying facts occurs via an HTTP request to the
-`/facts` REST endpoint.
-
-
-## Query format
-
-Facts are queried by making a request to a URL in the following form:
-
-The HTTP request must conform to the following format:
-
-* The URL requested is `/facts/<node>`
-* A `GET` is used.
-* There is an `Accept` header containing `application/json`.
-
-The supplied `<node>` path component indicates the certname for which
-facts should be retrieved.
-
-## Response format
-
-Successful responses will be in `application/json`. Errors will be returned as
-non-JSON strings.
-
-The result is a JSON object containing two keys, "name" and "facts". The
-"facts" entry is itself an object mapping fact names to values:
-
- {"name": "<node>",
- "facts": {
- "<fact name>": "<fact value>",
- "<fact name>": "<fact value>",
- ...
- }
- }
-
-If no facts are known for the supplied node, an HTTP 404 is returned.
-
-## Example
-
-[Using `curl` from localhost][curl]:
-
- curl -H "Accept: application/json" 'http://localhost:8080/facts/<node>'
-
-Where `<node>` is the name of the node from which you wish to retrieve facts.
-
-For example:
-
- curl -X GET -H 'Accept: application/json' http://puppetdb:8080/facts/a.example.com
-
- {"name": "a.example.com",
- "facts": {
- "operatingsystem": "Debian",
- "ipaddress": "192.168.1.105",
- "uptime_days": "26 days"
- }
- }
View
148 source/puppetdb/1.1/api/query/v1/metrics.markdown
@@ -1,148 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v1 » Querying Metrics"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v1/metrics.html"
----
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-Querying PuppetDB metrics is accomplished by making an HTTP request
-to paths under the `/metrics` REST endpoint.
-
-## Listing available metrics
-
-### Request format
-
-To get a list of all available metric names:
-
-* Request `/metrics/mbeans`.
-* Use a `GET` request.
-* Provide an `Accept` header containing `application/json`.
-
-### Response format
-
-Responses return a JSON Object mapping a string to a string:
-
-* The key is the name of a valid MBean
-* The value is a URI to use for requesting that MBean's attributes
-
-## Retrieving a specific metric
-
-### Request format
-
-To get the attributes of a particular metric:
-
-* Request `/metrics/mbean/<name>`, where `<name>` is something that was
- returned in the list of available metrics specified above.
-* Use a `GET` request.
-* Provide an `Accept` header containing `application/json`.
-
-### Response format
-
-Responses return a JSON Object mapping strings to (strings/numbers/booleans).
-
-## Useful metrics
-
-### Population metrics
-
-* `com.puppetlabs.puppetdb.query.population:type=default,name=num-nodes`:
- The number of nodes in your population.
-* `com.puppetlabs.puppetdb.query.population:type=default,name=num-resources`:
- The number of resources in your population.
-* `com.puppetlabs.puppetdb.query.population:type=default,name=avg-resources-per-node`:
- The average number of resources per node in your population.
-* `com.puppetlabs.puppetdb.query.population:type=default,name=pct-resource-dupes`:
- The percentage of resources that exist on more than one node.
-
-### Database metrics
-
-* `com.jolbox.bonecp:type=BoneCP`: Database connection pool
- metrics. How long it takes to get a free connection, average
- execution times, number of free connections, etc.
-
-### Command-processing metrics
-
-Each of the following metrics is available for each command supported
-in PuppetDB. In the below list of metrics, `<name>` should be
-substituted with a command specifier. Example `<name>`s you can use
-include:
-
-* `global`: Aggregate stats for _all_ commands
-* `replace catalog.1`: Stats for catalog replacement
-* `replace facts.1`: Stats for facts replacement
-* `deactivate node.1`: Stats for node deactivation
-
-Other than `global`, all command specifiers are of the form
-`<command>.<version>`. As we version commands, you'll be able to get
-statistics for each version independently.
-
-Metrics available for each command:
-
-* `com.puppetlabs.puppetdb.command:type=<name>,name=discarded`: stats
- about commands we've discarded (we've retried them as many times as
- we can, to no avail)
-* `com.puppetlabs.puppetdb.command:type=<name>,name=fatal`: stats about
- commands we failed to process.
-* `com.puppetlabs.puppetdb.command:type=<name>,name=processed`: stats
- about commands we've successfully processed
-* `com.puppetlabs.puppetdb.command:type=<name>,name=processing-time`:
- stats about how long it takes to process commands
-* `com.puppetlabs.puppetdb.command:type=<name>,name=retried`: stats about
- commands that have been submitted for retry (due to transient
- errors)
-
-### HTTP metrics
-
-Each of the following metrics is available for each HTTP endpoint. In
-the below list of metrics, `<name>` should be substituted with a REST
-endpoint name. Example `<name>`s you can use include:
-
-* `commands`: Stats relating to the command processing REST
- endpoint. The PuppetDB terminus in Puppet talks to this endpoint to
- submit new catalogs, facts, etc.
-* `metrics`: Stats relating to the metrics REST endpoint. This is the
- endpoint you're reading about right now!
-* `facts`: Stats relating to fact querying. This is the endpoint used
- by the puppetmaster for inventory service queries.
-* `resources`: Stats relating to resource querying. This is the
- endpoint used when collecting exported resources.
-
-In addition to customizing `<name>`, the following metrics are
-available for each HTTP status code (`<status code>`). For example, you can
-see the stats for all `200` responses for the `resources`
-endpoint. This allows you to see, per endpoint and per response,
-independent counters and statistics.
-
-* `com.puppetlabs.puppetdb.http.server:type=<name>,name=service-time`:
- stats about how long it takes to service all HTTP requests to this endpoint
-* `com.puppetlabs.puppetdb.http.server:type=<name>,name=<status code>`:
- stats about how often we're returning this response code
-
-### Storage metrics
-
-Metrics involving the PuppetDB storage subsystem all begin with the
-`com.puppetlabs.puppetdb.scf.storage:type=default,name=` prefix. There are
-a number of metrics concerned with individual storage operations (storing
-resources, storing edges, etc.). Metrics of particular note include:
-
-* `com.puppetlabs.puppetdb.scf.storage:type=default,name=duplicate-pct`:
- the percentage of catalogs that PuppetDB determines to be
- duplicates of existing catalogs.
-* `com.puppetlabs.puppetdb.scf.storage:type=default,name=gc-time`: state
- about how long it takes to do storage compaction
-
-### JVM Metrics
-
-* `java.lang:type=Memory`: memory usage statistics
-* `java.lang:type=Threading`: stats about JVM threads
-
-### MQ Metrics
-
-* `org.apache.activemq:BrokerName=localhost,Type=Queue,Destination=com.puppetlabs.puppetdb.commands`:
- stats about the command processing queue: queue depth, how long messages remain in the queue, etc.
-
-## Example
-
-[Using `curl` from localhost][curl]:
-
- curl -H "Accept: application/json" 'http://localhost:8080/metrics/mbean/java.lang:type=Memory'
View
61 source/puppetdb/1.1/api/query/v1/nodes.markdown
@@ -1,61 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v1 » Querying Nodes"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v1/nodes.html"
----
-
-[resource]: ./resources.html
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-Nodes can be queried by making an HTTP request to the `/nodes` REST
-endpoint with a JSON-formatted parameter called `query`.
-
-## Query format
-
-* The HTTP method must be `GET`.
-* There must be an `Accept` header specifying `application/json`.
-
-The `query` parameter uses a format similar to [resource queries][resource].
-
-Only queries against facts and filters based on node activeness are currently
-supported.
-
-These query terms must be of the form `["fact", "<fact name>"]` or `["node", "active"]`,
-respectively.
-
-Accepted operators are: `[= > < >= <= and or not]`
-
-Inequality operators are strictly arithmetic, and will ignore any fact values
-which are not numeric.
-
-Note that nodes which are missing a fact referenced by a `not` query will match
-the query.
-
-In this example, the query will return active nodes whose kernel is Linux and whose uptime is less
-than 30 days:
-
- ["and",
- ["=", ["node", "active"], true],
- ["=", ["fact", "kernel"], "Linux"],
- [">", ["fact", "uptime_days"], 30]]
-
-If no `query` parameter is supplied, all nodes will be returned.
-
-## Response format
-
-The response is a JSON array of node names that match the predicates, sorted
-in ascending order:
-
-`["foo.example.com", "bar.example.com", "baz.example.com"]`
-
-## Example
-
-[Using `curl` from localhost][curl]:
-
-Retrieving all nodes:
-
- curl -H "Accept: application/json" 'http://localhost:8080/nodes'
-
-Retrieving all active nodes:
-
- curl -G -H "Accept: application/json" 'http://localhost:8080/nodes' --data-urlencode 'query=["=", ["node", "active"], true]'
View
107 source/puppetdb/1.1/api/query/v1/resources.markdown
@@ -1,107 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v1 » Querying Resources"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v1/resources.html"
----
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-Resources are queried via an HTTP request to the
-`/resources` REST endpoint.
-
-## Query format
-
-Queries for resources must conform to the following format:
-
-* A `GET` is used.
-* There is a single parameter, `query`.
-* There is an `Accept` header containing `application/json`.
-* The `query` parameter is a JSON array of query predicates, in prefix
- form, conforming to the format described below.
-
-The `query` parameter adheres to the following grammar:
-
- query: [ {type} {query}+ ] | [ {match} {field} {value} ]
- field: string | [ string+ ]
- value: string
- type: "or" | "and" | "not"
- match: "="
-
-`field` strings may be any of the following:
-
-`tag`
-: a case-insensitive tag on the resource
-
-`["node", "name"]`
-: the name of the node associated with the resource
-
-`["node", "active"]`
-: `true` if the node has not been deactivated, `false` if it has
-
-`["parameter", "<parameter name>"]`
-: a parameter of the resource
-
-`type`
-: the resource type
-
-`title`
-: the resource title
-
-`exported`
-: whether or not the resource is exported
-
-`sourcefile`
-: the manifest file where the resource was declared
-
-`sourceline`
-: the line of the manifest in which the resource was declared
-
-For example, the JSON query structure for file resources, tagged "magical", and present on any active host except
-for "example.local" would be:
-
- ["and", ["not", ["=", ["node", "name"], "example.local"]],
- ["=", ["node", "active"], true],
- ["=", "type", "File"],
- ["=", "tag", "magical"],
- ["=", ["parameter", "ensure"], "enabled"]]
-
-The following conditionals for type behaviors are defined:
-
-`or`
-: If *any* condition is true, the result is true.
-
-`and`
-: If *all* conditions are true, the result is true.
-
-`not`
-: If *none* of the conditions are true, the result is true.
-
-The following match operator behaviors are defined:
-
-`=`
-: Exact string equality of the field and the value.
-
-## Response format
-
-An array of zero or more resource objects, with each object in the
-following form:
-
- {"certname": "the certname of the associated host",
- "resource": "the resource's unique hash",
- "type": "File",
- "title": "/etc/hosts",
- "exported": "true",
- "tags": ["foo", "bar"],
- "sourcefile": "/etc/puppet/manifests/site.pp",
- "sourceline": "1",
- "parameters": {<parameter>: <value>,
- <parameter>: <value>,
- ...}}
-
-## Example
-
-[Using `curl` from localhost][curl]:
-
-Retrieving the resource `File['/etc/ipsec.conf']`:
-
- curl -G -H "Accept: application/json" 'http://localhost:8080/resources' --data-urlencode 'query=["and", ["=", "type", "File"], ["=", "title", "/etc/ipsec.conf"]]'
View
39 source/puppetdb/1.1/api/query/v1/status.markdown
@@ -1,39 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v1 » Querying Status"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v1/status.html"
----
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-
-## Routes
-
-### `GET /v1/status/nodes/<NODE>`
-
-This will return status information for the given node. There must be
-an `Accept` header containing `application/json`.
-
-
-## Response Format
-
-Node status information will be returned in a JSON hash of the form:
-
- {"name": <node>,
- "deactivated": <timestamp>,
- "catalog_timestamp": <timestamp>,
- "facts_timestamp": <timestamp>}
-
-If the node is active, "deactivated" will be null. If a catalog or facts are
-not present, the corresponding timestamps will be null.
-
-If no information is known about the node, the result will be a 404 with a JSON
-hash containing an "error" key with a message indicating such.
-
-## Example
-
-[Using `curl` from localhost][curl]:
-
- curl -H "Accept: application/json" 'http://localhost:8080/status/nodes/<node>'
-
-Where <node> is the name of the node whose status you wish to check.
View
38 source/puppetdb/1.1/api/query/v2/fact-names.markdown
@@ -1,38 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v2 » Querying Fact Names"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v2/fact-names.html"
----
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-The `/fact-names` endpoint can be used to retrieve all known fact names.
-
-
-## Routes
-
-### `GET /fact-names`
-
-This will return an alphabetical list of all known fact names, *including* those which are
-known only for deactivated nodes.
-
-#### Examples
-
-[Using `curl` from localhost][curl]:
-
- curl -X GET -H 'Accept: application/json' http://localhost:8080/v2/fact-names
-
- ["kernel", "operatingsystem", "osfamily", "uptime"]
-
-
-## Request
-
-All requests must accept `application/json`.
-
-## Response Format
-
-The response will be in `application/json`, and will contain an alphabetical
-JSON array containing fact names. Each fact name will appear only once,
-regardless of how many nodes have that fact.
-
- [<fact>, <fact>, ..., <fact>, <fact>]
View
111 source/puppetdb/1.1/api/query/v2/facts.markdown
@@ -1,111 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v2 » Querying Facts"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v2/facts.html"
----
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-Querying facts occurs via an HTTP request to the
-`/facts` REST endpoint.
-
-
-## Routes
-
-### `GET /v2/facts`
-
-This will return all facts matching the given query. Facts for
-deactivated nodes are not included in the response. There must be an
-`Accept` header containing `application/json`.
-
-#### URL Parameters
-
-* `query`: Required. A JSON array containing the query in prefix notation.
-
-#### Available Fields
-
-* `"name"`: matches facts of the given name
-* `"value"`: matches facts with the given value
-* `"certname"`: matches facts for the given node
-
-#### Operators
-
-See [the Operators page](./operators.html)
-
-#### Examples
-
-[Using `curl` from localhost][curl]:
-
-Get the operatingsystem fact for all nodes:
-
- curl -X GET -H 'Accept: application/json' http://puppetdb:8080/v2/facts --data-urlencode 'query=["=", "name", "operatingsystem"]'
-
- [{"certname": "a.example.com", "name": "operatingsystem", "value": "Debian"},
- {"certname": "b.example.com", "name": "operatingsystem", "value": "RedHat"},
- {"certname": "c.example.com", "name": "operatingsystem", "value": "Darwin"},
-
-Get all facts for a single node:
-
- curl -X GET -H 'Accept: application/json' http://puppetdb:8080/v2/facts --data-urlencode 'query=["=", "certname", "a.example.com"]'
-
- [{"certname": "a.example.com", "name": "operatingsystem", "value": "Debian"},
- {"certname": "a.example.com", "name": "ipaddress", "value": "192.168.1.105"},
- {"certname": "a.example.com", "name": "uptime_days", "value": "26 days"}]
-
-### `GET /v2/facts/<NAME>`
-
-This will return all facts for all nodes with the indicated
-name. There must be an `Accept` header containing `application/json`.
-
-#### URL Parameters
-
-* `query`: Optional. A JSON array containing the query in prefix
- notation. The syntax and semantics are identical to the `query`
- parameter for the `/facts` route, mentioned above. When supplied,
- the query is assumed to supply _additional_ criteria that can be
- used to return a _subset_ of the information normally returned by
- this route.
-
-#### Examples
-
- curl -X GET -H 'Accept: application/json' http://puppetdb:8080/v2/facts/operatingsystem
-
- [{"certname": "a.example.com", "name": "operatingsystem", "value": "Debian"},
- {"certname": "b.example.com", "name": "operatingsystem", "value": "Redhat"},
- {"certname": "c.example.com", "name": "operatingsystem", "value": "Ubuntu"}]
-
-### `GET /v2/facts/<NAME>/<VALUE>`
-
-This will return all facts for all nodes with the indicated name and
-value. There must be an `Accept` header containing `application/json`.
-
-#### URL Parameters
-
-* `query`: Optional. A JSON array containing the query in prefix
- notation. The syntax and semantics are identical to the `query`
- parameter for the `/facts` route, mentioned above. When supplied,
- the query is assumed to supply _additional_ criteria that can be
- used to return a _subset_ of the information normally returned by
- this route.
-
-#### Examples
-
- curl -X GET -H 'Accept: application/json' http://puppetdb:8080/v2/facts/operatingsystem/Debian
-
- [{"certname": "a.example.com", "name": "operatingsystem", "value": "Debian"},
- {"certname": "b.example.com", "name": "operatingsystem", "value": "Debian}]
-
-## Response Format
-
-Successful responses will be in `application/json`. Errors will be returned as
-non-JSON strings.
-
-The result will be a JSON array, with one entry per fact. Each entry is of the form:
-
- {
- "certname": <node name>,
- "name": <fact name>,
- "value": <fact value>
- }
-
-If no facts are known for the supplied node, an HTTP 404 is returned.
View
150 source/puppetdb/1.1/api/query/v2/metrics.markdown
@@ -1,150 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v2 » Querying Metrics"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v2/metrics.html"
----
-
-> **Note:** The v2 metrics endpoint is currently exactly the same as the [v1 endpoint](../v1/metrics.html).
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-Querying PuppetDB metrics is accomplished by making an HTTP request
-to paths under the `/metrics` REST endpoint.
-
-## Listing available metrics
-
-### Request format
-
-To get a list of all available metric names:
-
-* Request `/metrics/mbeans`.
-* Use a `GET` request.
-* Provide an `Accept` header containing `application/json`.
-
-### Response format
-
-Responses return a JSON Object mapping a string to a string:
-
-* The key is the name of a valid MBean
-* The value is a URI to use for requesting that MBean's attributes
-
-## Retrieving a specific metric
-
-### Request format
-
-To get the attributes of a particular metric:
-
-* Request `/metrics/mbean/<name>`, where `<name>` is something that was
- returned in the list of available metrics specified above.
-* Use a `GET` request.
-* Provide an `Accept` header containing `application/json`.
-
-### Response format
-
-Responses return a JSON Object mapping strings to (strings/numbers/booleans).
-
-## Useful metrics
-
-### Population metrics
-
-* `com.puppetlabs.puppetdb.query.population:type=default,name=num-nodes`:
- The number of nodes in your population.
-* `com.puppetlabs.puppetdb.query.population:type=default,name=num-resources`:
- The number of resources in your population.
-* `com.puppetlabs.puppetdb.query.population:type=default,name=avg-resources-per-node`:
- The average number of resources per node in your population.
-* `com.puppetlabs.puppetdb.query.population:type=default,name=pct-resource-dupes`:
- The percentage of resources that exist on more than one node.
-
-### Database metrics
-
-* `com.jolbox.bonecp:type=BoneCP`: Database connection pool
- metrics. How long it takes to get a free connection, average
- execution times, number of free connections, etc.
-
-### Command-processing metrics
-
-Each of the following metrics is available for each command supported
-in PuppetDB. In the below list of metrics, `<name>` should be
-substituted with a command specifier. Example `<name>`s you can use
-include:
-
-* `global`: Aggregate stats for _all_ commands
-* `replace catalog.1`: Stats for catalog replacement
-* `replace facts.1`: Stats for facts replacement
-* `deactivate node.1`: Stats for node deactivation
-
-Other than `global`, all command specifiers are of the form
-`<command>.<version>`. As we version commands, you'll be able to get
-statistics for each version independently.
-
-Metrics available for each command:
-
-* `com.puppetlabs.puppetdb.command:type=<name>,name=discarded`: stats
- about commands we've discarded (we've retried them as many times as
- we can, to no avail)
-* `com.puppetlabs.puppetdb.command:type=<name>,name=fatal`: stats about
- commands we failed to process.
-* `com.puppetlabs.puppetdb.command:type=<name>,name=processed`: stats
- about commands we've successfully processed
-* `com.puppetlabs.puppetdb.command:type=<name>,name=processing-time`:
- stats about how long it takes to process commands
-* `com.puppetlabs.puppetdb.command:type=<name>,name=retried`: stats about
- commands that have been submitted for retry (due to transient
- errors)
-
-### HTTP metrics
-
-Each of the following metrics is available for each HTTP endpoint. In
-the below list of metrics, `<name>` should be substituted with a REST
-endpoint name. Example `<name>`s you can use include:
-
-* `commands`: Stats relating to the command processing REST
- endpoint. The PuppetDB terminus in Puppet talks to this endpoint to
- submit new catalogs, facts, etc.
-* `metrics`: Stats relating to the metrics REST endpoint. This is the
- endpoint you're reading about right now!
-* `facts`: Stats relating to fact querying. This is the endpoint used
- by the puppetmaster for inventory service queries.
-* `resources`: Stats relating to resource querying. This is the
- endpoint used when collecting exported resources.
-
-In addition to customizing `<name>`, the following metrics are
-available for each HTTP status code (`<status code>`). For example, you can
-see the stats for all `200` responses for the `resources`
-endpoint. This allows you to see, per endpoint and per response,
-independent counters and statistics.
-
-* `com.puppetlabs.puppetdb.http.server:type=<name>,name=service-time`:
- stats about how long it takes to service all HTTP requests to this endpoint
-* `com.puppetlabs.puppetdb.http.server:type=<name>,name=<status code>`:
- stats about how often we're returning this response code
-
-### Storage metrics
-
-Metrics involving the PuppetDB storage subsystem all begin with the
-`com.puppetlabs.puppetdb.scf.storage:type=default,name=` prefix. There are
-a number of metrics concerned with individual storage operations (storing
-resources, storing edges, etc.). Metrics of particular note include:
-
-* `com.puppetlabs.puppetdb.scf.storage:type=default,name=duplicate-pct`:
- the percentage of catalogs that PuppetDB determines to be
- duplicates of existing catalogs.
-* `com.puppetlabs.puppetdb.scf.storage:type=default,name=gc-time`: state
- about how long it takes to do storage compaction
-
-### JVM Metrics
-
-* `java.lang:type=Memory`: memory usage statistics
-* `java.lang:type=Threading`: stats about JVM threads
-
-### MQ Metrics
-
-* `org.apache.activemq:BrokerName=localhost,Type=Queue,Destination=com.puppetlabs.puppetdb.commands`:
- stats about the command processing queue: queue depth, how long messages remain in the queue, etc.
-
-## Example
-
-[Using `curl` from localhost][curl]:
-
- curl -H "Accept: application/json" 'http://localhost:8080/metrics/mbean/java.lang:type=Memory'
View
181 source/puppetdb/1.1/api/query/v2/nodes.markdown
@@ -1,181 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v2 » Querying Nodes"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v2/nodes.html"
----
-
-[resource]: ./resources.html
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-Nodes can be queried by making an HTTP request to the `/nodes` REST
-endpoint with a JSON-formatted parameter called `query`.
-
-
-## Routes
-
-### `GET /v2/nodes`
-
-This will return all nodes matching the given query. Deactivated nodes
-aren't included in the response. There must be an `Accept` header
-containing `application/json`.
-
-#### Parameters
-
-* `query`: Required. A JSON array of query predicates, in prefix form,
- conforming to the format described below.
-
-The `query` parameter is a similar format to [resource queries][resource].
-
-Only queries against `"name"` and facts are currently supported.
-
-Fact terms must be of the form `["fact", <fact name>]`.
-
-Node query supports [all available operators](./operators.html). Inequality
-operators are only supported for fact queries, but regular expressions are
-supported for both name and facts.
-
-Inequality operators are strictly arithmetic, and will ignore any fact values
-which are not numeric.
-
-Note that nodes which are missing a fact referenced by a `not` query will match
-the query.
-
-This query will return nodes whose kernel is Linux and whose uptime is less
-than 30 days:
-
- ["and",
- ["=", ["fact", "kernel"], "Linux"],
- [">", ["fact", "uptime_days"], 30]]
-
-If no `query` parameter is supplied, all nodes will be returned.
-
-#### Response format
-
-The response is a JSON array of hashes of the form:
-
- {"name": <string>,
- "deactivated": <timestamp>,
- "catalog_timestamp": <timestamp>,
- "facts_timestamp": <timestamp>,
- "report_timestamp": <timestamp>}
-
-The array is sorted alphabetically by `name`.
-
-#### Example
-
-[You can use `curl`][curl] to query information about nodes like so:
-
- curl -H "Accept: application/json" 'http://localhost:8080/v2/nodes'
- curl -G -H "Accept: application/json" 'http://localhost:8080/v2/nodes' --data-urlencode 'query=["=", ["fact", "kernel"], "Linux"]'
-
-### `GET /v2/nodes/<NODE>`
-
-This will return status information for the given node, active or
-not. There must be an `Accept` header containing `application/json`.
-
-#### Response format
-
-The response is the same format as for the [/v1/status](../v1/status.html)
-endpoint.
-
-### `GET /v2/nodes/<NODE>/facts`
-
-This will return the facts for the given node. Facts from deactivated
-nodes aren't included in the response. There must be an `Accept`
-header containing `application/json`.
-
-#### Parameters
-
-* `query`: Optional. A JSON array containing the query in prefix
- notation. The syntax and semantics are identical to the `query`
- parameter for the `/v2/facts` route. When supplied, the query is
- assumed to supply _additional_ criteria that can be used to return a
- _subset_ of the information normally returned by this route.
-
-#### Response format
-
-The response is the same format as for the [/v2/facts](./facts.html)
-endpoint.
-
-### `GET /v2/nodes/<NODE>/facts/<NAME>`
-
-This will return facts with the given name for the given node. Facts
-from deactivated nodes aren't included in the response. There must be
-an `Accept` header containing `application/json`.
-
-#### Parameters
-
-* `query`: Optional. A JSON array containing the query in prefix
- notation. The syntax and semantics are identical to the `query`
- parameter for the `/v2/facts` route. When supplied, the query is
- assumed to supply _additional_ criteria that can be used to return a
- _subset_ of the information normally returned by this route.
-
-#### Response format
-
-The response is the same format as for the [/v2/facts](./facts.html)
-endpoint.
-
-
-### `GET /v2/nodes/<NODE>/facts/<NAME>/<VALUE>`
-
-This will return facts with the given name and value for the given
-node. Facts from deactivated nodes aren't included in the
-response. There must be an `Accept` header containing
-`application/json`.
-
-#### Parameters
-
-* `query`: Optional. A JSON array containing the query in prefix
- notation. The syntax and semantics are identical to the `query`
- parameter for the `/v2/facts` route. When supplied, the query is
- assumed to supply _additional_ criteria that can be used to return a
- _subset_ of the information normally returned by this route.
-
-#### Response format
-
-The response is the same format as for the [/v2/facts](./facts.html)
-endpoint.
-
-### `GET /v2/nodes/<NODE>/resources`
-
-This will return the resources for the given node. Resources from
-deactivated nodes aren't included in the response. There must be an
-`Accept` header containing `application/json`.
-
-#### Parameters
-
-* `query`: Optional. A JSON array containing the query in prefix
- notation. The syntax and semantics are identical to the `query`
- parameter for the `/v2/resources` route. When supplied, the query is
- assumed to supply _additional_ criteria that can be used to return a
- _subset_ of the information normally returned by this route.
-
-#### Response format
-
-The response is the same format as for the [/v2/resources][resource]
-endpoint.
-
-### `GET /v2/nodes/<NODE>/resources/<TYPE>`
-
-This will return the resources of the indicated type for the given
-node. Resources from deactivated nodes aren't included in the
-response. There must be an `Accept` header containing
-`application/json`.
-
-This endpoint behaves identically to the
-[`/v2/resources/<TYPE>`][resource] endpoint, except the resources
-returned include _only_ those belonging to the node given in the URL
-for this route.
-
-### `GET /v2/nodes/<NODE>/resources/<TYPE>/<TITLE>`
-
-This will return the resource of the indicated type and title for the
-given node. Resources from deactivated nodes aren't included in the
-response. There must be an `Accept` header containing
-`application/json`.
-
-This endpoint behaves identically to the
-[`/v2/resources/<TYPE>`][resource] endpoint, except the resources
-returned include _only_ those belonging to the node given in the URL
-for this route.
View
180 source/puppetdb/1.1/api/query/v2/operators.markdown
@@ -1,180 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v2 » Query Operators"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v2/operators.html"
----
-
-[resources]: ./resources.html
-[facts]: ./facts.html
-[query]: ./query.html
-
-PuppetDB's [query strings][query] can use several common operators.
-
-> **Note:** The operators below apply to **version 2** of the query API. Not all of them are available to version 1 queries.
-
-
-## Binary Operators
-
-Each of these operators accepts two arguments: a **field,** and a
-**value.** These operators are **non-transitive:** their syntax must always be:
-
- ["<OPERATOR>", "<FIELD>", "<VALUE>"]
-
-The available fields for each endpoint are listed in that endpoint's documentation.
-
-### `=` (equality)
-
-**Matches if:** the field's actual value is exactly the same as the provided value. Note that this **does not** coerce values --- the provided value must be the same data type as the field. In particular, be aware that:
-
-* Most fields are strings.
-* Some fields are booleans.
-* Numbers in resource parameters from Puppet are usually stored as strings, and equivalent numbers will **not** match --- if the value of `someparam` were "0", then `["=", "someparam", "0.0"]` wouldn't match.
-
-### `>` (greater than)
-
-**Matches if:** the field is greater than the provided value. Coerces both the field and value to floats or integers; if
-they can't be coerced, the operator will not match.
-
-### `<` (less than)
-
-**Matches if:** the field is less than the provided value. Coerces both the field and value to floats or integers; if
-they can't be coerced, the operator will not match.
-
-### `>=` (less than or equal to)
-
-**Matches if:** the field is greater than or equal to the provided value. Coerces both the field and value to floats or integers; if
-they can't be coerced, the operator will not match.
-
-### `<=` (greater than or equal to)
-
-**Matches if:** the field is less than or equal to the provided value. Coerces both the field and value to floats or integers; if
-they can't be coerced, the operator will not match.
-
-### `~` (regexp match)
-
-**Matches if:** the field's actual value matches the provided regular expression. The provided value must be a regular expression represented as a JSON string:
-
-* The regexp **must not** be surrounded by the slash characters (`/rexegp/`) that delimit regexps in many languages.
-* Every backslash character **must** be escaped with an additional backslash. Thus, a sequence like `\d` would be represented as `\\d`, and a literal backslash (represented in a regexp as a double-backslash `\\`) would be represented as a quadruple-backslash (`\\\\`).
-
-The following example would match if the `certname` field's actual value resembled something like `www03.example.com`:
-
- ["~", "certname", "www\\d+\\.example\\.com"]
-
-> **Note:** Regular expression matching is performed by the database backend, and the available regexp features are backend-dependent. For best results, use the simplest and most common features that can accomplish your task. See the links below for details:
->
-> * [PostgreSQL regexp features](http://www.postgresql.org/docs/9.1/static/functions-matching.html#POSIX-SYNTAX-DETAILS)
-> * [HSQLDB (embedded database) regexp features](http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html)
-
-
-
-## Boolean Operators
-
-Every argument of these operators should be a **complete query string** in its own right. These operators are **transitive:** the order of their arguments does not matter.
-
-### `and`
-
-**Matches if:** **all** of its arguments would match. Accepts any number of query strings as its arguments.
-
-### `or`
-
-**Matches if:** **at least one** of its arguments would match. Accepts any number of query strings as its arguments.
-
-### `not`
-
-**Matches if:** its argument **would not** match. Accepts a **single** query string as its argument.
-
-
-## Subquery Operators
-
-Subqueries allow you to correlate data from multiple sources or multiple
-rows. (For instance, a query such as "fetch the IP addresses of all nodes with
-`Class[Apache]`" would have to use both facts and resources to return a list of facts.)
-
-Subqueries are unlike the other operators listed above:
-
-* The `in` operator results in a complete query string. The `extract` operator and the subqueries do not.
-* An `in` statement **must** contain a field and an `extract` statement.
-* An `extract` statement **must** contain a field and a subquery.
-
-These statements work together as follows (working "outward" and starting with the subquery):
-
-* The subquery collects a group of PuppetDB objects (specifically, a group of [resources][] or a group of [facts][]). Each of these objects has many **fields.**
-* The `extract` statement collects the value of a **single field** across every object returned by the subquery.
-* The `in` statement **matches** if the value of its field is present in the list returned by the `extract` statement.
-
-Subquery | Extract | In
----------|---------|---
-Every resource whose type is "Class" and title is "Apache." (Note that all resource objects have a `certname` field, among other fields.) | Every `certname` field from the results of the subquery. | Match if the `certname` field is present in the list from the `extract` statement.
-
-The complete `in` statement described in the table above would match any object that shares a `certname` with a node that has `Class[Apache]`. This could be combined with a boolean operator to get a specific fact from every node that matches the `in` statement.
-
-
-### `in`
-
-An `in` statement constitutes a full query string, which can be used alone or as an argument for a [boolean operator](#boolean-operators).
-
-"In" statements are **non-transitive** and take two arguments:
-
-* The first argument **must** be a valid **field** for the endpoint **being queried.**
-* The second argument **must** be an **`extract` statement,** which acts as a list of possible values for the field.
-
-**Matches if:** the field's actual value is included in the list of values created by the `extract` statement.
-
-### `extract`
-
-An `extract` statement **does not** constitute a full query string. It may only be used as the second argument of an `in` statement.
-
-"Extract" statements are **non-transitive** and take two arguments:
-
-* The first argument **must** be a valid **field** for the endpoint **being subqueried** (see second argument).
-* The second argument **must** be a **subquery.**
-
-As the second argument of an `in` statement, an `extract` statement acts as a list of possible values. This list is compiled by extracting the value of the requested field from every result of the subquery.
-
-### Available Subqueries
-
-A subquery may only be used as the second argument of an `extract` statement, where it acts as a collection of PuppetDB objects. Each of the objects returned by the subquery has many fields; the `extract` statement takes the value of one field from each of those objects, and passes that list of values to the `in` statement that contains it.
-
-In version 2 of the query API, the available subqueries are:
-
-* [`select-resources`](#select-resources)
-* [`select-facts`](#select-facts)
-
-#### `select-resources`
-
-A `select-resources` subquery may **only** be used as the second argument of an `extract` statement.
-
-It takes a single argument, which must be a **complete query string** which would be valid for [the `/v2/resources` endpoint][resources]. (Note that `/v2/resources/<TYPE>` and `/v2/resources/<TYPE>/<TITLE>` cannot be directly subqueried.) Since the argument is a normal query string, it can itself include any number of `in` statements and subqueries.
-
-#### `select-facts`
-
-A `select-facts` subquery may **only** be used as the second argument of an `extract` statement.
-
-It takes a single argument, which must be a **complete query string** which would be valid for [the `/v2/facts` endpoint][facts]. (Note that `/v2/facts/<NAME>` and `/v2/facts/<NAME>/<VALUE>` cannot be directly subqueried.) Since the argument is a normal query string, it can itself include any number of `in` statements and subqueries.
-
-### Subquery Examples
-
-This query string queries the `/facts` endpoint for the IP address of
-all nodes with `Class[Apache]`:
-
- ["and",
- ["=", "name", "ipaddress"],
- ["in", "certname",
- ["extract", "certname",
- ["select-resources",
- ["and",
- ["=", "type", "Class"],
- ["=", "title", "Apache"]]]]]]
-
-This query string queries the `/facts` endpoint for the IP address of
-all Debian nodes.
-
- ["and",
- ["=", "name", "ipaddress"],
- ["in", "certname",
- ["extract", "certname",
- ["select-facts",
- ["and",
- ["=", "name", "operatingsystem"],
- ["=", "value", "Debian"]]]]]]
View
69 source/puppetdb/1.1/api/query/v2/query.markdown
@@ -1,69 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v2 » Query Structure"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v2/query.html"
----
-
-[prefix]: http://en.wikipedia.org/wiki/Polish_notation
-[jetty]: ../../../configure.html#jetty-http-settings
-[index]: ../../index.html
-[urlencode]: http://en.wikipedia.org/wiki/Percent-encoding
-[operators]: ./operators.html
-[tutorial]: ../tutorial.html
-[curl]: ../curl.html
-
-## Summary
-
-PuppetDB's query API can retrieve data objects from PuppetDB for use in other applications. For example, the terminus plugins for puppet masters use this API to collect exported resources, and to translate node facts into the inventory service.
-
-The query API is implemented as HTTP URLs on the PuppetDB server. By default, it can only be accessed over the network via host-verified HTTPS; [see the jetty settings][jetty] if you need to access the API over unencrypted HTTP.
-
-## API URLs
-
-The first component of an API URL is the API version, written as `v1`, `v2`, etc. This page describes version 2 of the API, so every URL will begin with `/v2`. After the version, URLs are organized into a number of **endpoints.**
-
-### Endpoints
-
-Conceptually, an endpoint represents a reservoir of some type of PuppetDB object. Each version of the PuppetDB API defines a set number of endpoints.
-
-See the [API index][index] for a list of the available endpoints. Each endpoint may have additional sub-endpoints under it; these are generally just shortcuts for the most common types of query, so that you can write terser and simpler query strings.
-
-## Query Structure
-
-A query consists of:
-
-* An HTTP GET request to an endpoint URL...
-* ...which may or may not contain a **query string** as a `query` URL parameter...
-* ...and which must contain an `Accept: application/json` header.
-
-That is, nearly every query will look like a GET request to a URL that resembles the following:
-
- https://puppetdb:8081/v2/<ENDPOINT>?query=<QUERY STRING>
-
-Query strings are optional for some endpoints, required for others, and prohibited for others; see each endpoint's documentation.
-
-### Query Strings
-
-A query string must be:
-
-* A [URL-encoded][urlencode]...
-* ...JSON array, which may contain scalar data types (usually strings) and additional arrays...
-* ...which describes a complex _comparison operation..._
-* ...in [_prefix notation._][prefix]
-
-JSON arrays are delimited by square brackets (`[` and `]`), and items in the array are separated by commas. JSON strings are delimited by straight double-quotes (`"`) and must be UTF-8 text; literal double quotes and literal backslashes in the string must be escaped with a backslash (`"` is `\"` and `\` is `\\`).
-
-"Prefix notation" means every array in a query string must begin with an [operator][operators], and the remaining elements in the array will be interpreted as that operator's arguments, in order. (The similarity to Lisp is intentional.)
-
-A complete query string describes a comparison operation. When submitting a query, PuppetDB will check every _possible_ result from the endpoint to see if it matches the comparison from the query string, and will only return those objects that match.
-
-For a more complete description of how to construct query strings, see [the Operators page][operators].
-
-## Query Responses
-
-All queries return data with a content type of `application/json`.
-
-## Tutorial and Tips
-
-For a walkthrough on constructing queries, see [the Query Tutorial page][tutorial]. For quick tips on using curl to make ad-hoc queries, see [the Curl Tips page][curl].
-
View
182 source/puppetdb/1.1/api/query/v2/resources.markdown
@@ -1,182 +0,0 @@
----
-title: "PuppetDB 1.1 » API » v2 » Querying Resources"
-layout: default
-canonical: "/puppetdb/1.1/api/query/v2/resources.html"
----
-
-[curl]: ../curl.html#using-curl-from-localhost-non-sslhttp
-
-Resources are queried via an HTTP request to the
-`/resources` REST endpoint.
-
-
-## Routes
-
-### `GET /v2/resources`
-
-This will return all resources matching the given query. Resources for
-deactivated nodes are not included in the response. There must be an
-`Accept` header containing `application/json`.
-
-#### Parameters
-
-* `query`: Required. A JSON array of query predicates, in prefix form,
- conforming to the format described below.
-
-The `query` parameter is described by the following grammar:
-
- query: [ {bool} {query}+ ] | [ "not" {query} ] | [ {match} {field} {value} ]
- field: string | [ string+ ]
- value: string
- bool: "or" | "and"
- match: "=" | "~"
-
-`field` may be any of:
-
-`tag`
-: a case-insensitive tag on the resource
-
-`certname`
-: the name of the node associated with the resource
-
-`[parameter <resource_param>]`
-: a parameter of the resource
-
-`type`
-: the resource type
-
-`title`
-: the resource title
-
-`exported`
-: whether or not the resource is exported
-
-`sourcefile`
-: the manifest file the resource was declared in
-
-`sourceline`
-: the line of the manifest on which the resource was declared
-
-For example, for file resources, tagged "magical", on any host except
-for "example.local" the JSON query structure would be:
-
- ["and", ["not", ["=", "certname", "example.local"]],
- ["=", "type", "File"],
- ["=", "tag", "magical"],
- ["=", ["parameter", "ensure"], "enabled"]
-
-See [the Operators page](./operators.html) for the full list of available operators. Note that
-resource queries *do not support* inequality, and regexp matching *is not
-supported* against node status or parameter values.
-
-### `GET /v2/resources/<TYPE>`
-
-This will return all resources for all nodes with the given
-type. Resources from deactivated nodes aren't included in the
-response. There must be an `Accept` header containing
-`application/json`.
-
-#### Parameters
-
-* `query`: Optional. A JSON array containing the query in prefix
- notation. The syntax and semantics are identical to the `query`
- parameter for the `/resources` route, mentioned above. When
- supplied, the query is assumed to supply _additional_ criteria that
- can be used to return a _subset_ of the information normally
- returned by this route.
-
-#### Examples
-
-[Using `curl` from localhost][curl]:
-
- curl -X GET -H "Accept: application/json" 'http://puppetdb:8080/v2/resources/User'