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. The version of the command also indicates the version of the wire format to use for the command.

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
  • The POST body must contain the JSON payload.
  • There is an Accept header that matches application/json.
  • The content-type is application/json.

Optionally, there may be a query 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

Note: This version is deprecated, use the latest version instead.

The payload is expected to be a Puppet catalog, as a JSON string, including the fields of the catalog wire format v1. Extra fields are ignored.

“replace catalog”, version 2

Note: This version is deprecated, use the latest version instead.

The payload is expected to be a Puppet catalog, as either a JSON string or an object, conforming exactly to the catalog wire format v1. Extra or missing fields are an error.

“replace catalog”, version 3

Note: This version is deprecated, use the latest version instead.

This version of the command introduces the new transaction-uuid field. This value is generated by Puppet and can be used, e.g., to correlate a report with the exact catalog that was used for the run. All previous versions of the replace catalog command will store a null value for this field.

The payload is expected to be a Puppet catalog, as either a JSON string or an object, conforming exactly to the catalog wire format v1. Extra or missing fields are an error.

“replace catalog”, version 4

Note: This version is deprecated, use the latest version instead.

The key change to version 4 is adding support for environments. This value will be populated by Puppet. This version also explicitly couples the version of the command with the same version of the wire format. Other changes in this version were related to removing unused metadata fields added by puppet.

The payload is expected to be a Puppet catalog, as a JSON object, conforming exactly to the catalog wire format v4. Extra or missing fields are an error.

“replace catalog”, version 5

Version 5 differs from version 4 by added support of a producer-timestamp field. This field is currently populated by the master, but will eventually be populated by agents to help ensure a consistent order of events in a multiple-master setup. Previous versions of the command will store a null value for this field.

The payload is expected to be a Puppet catalog, as a JSON object, conforming exactly to the catalog wire format v5. Extra or missing fields are an error.

“replace facts”, version 1

Note: This version is deprecated, use the latest version instead.

The payload is expected to be a set of facts, as a JSON string, conforming to the fact wire format v1

“replace facts”, version 2

Note: This version is deprecated, use the latest version instead.

Similar to version 4 of replace catalog, this version of replace facts adds support for environments and an explicit coupling between command version and wire format version. See fact wire format v2 for more information on the payload of this command.

“replace facts”, version 3

Similar to version 5 of replace catalog, this version of replace facts adds support for the producer-timestamp field that will eventually be used for agent timekeeping. See fact wire format v3 for more information on the payload of this command.

“deactivate node”, version 1

Note: This version is deprecated, use the latest version instead.

The payload is expected to be the name of a node, as a serialized JSON string, which will be deactivated effective as of the time the command is processed.

“deactivate node”, version 2

The payload is expected to be the name of a node, as a raw JSON string, which will be deactivated effective as of the time the command is processed. Serialization of the payload is no longer required.

“store report”, version 1

Note: This version is deprecated, use the latest version instead.

The payload is expected to be a report, containing events that occurred on Puppet resources. It is structured as a JSON object, conforming to the report wire format v1.

“store report”, version 2

Note: This version is deprecated, use the latest version instead.

This version of the command introduces support for the transaction-uuid, file, line, and containment-path fields.

The payload is expected to be a report, containing events that occurred on Puppet resources. It is structured as a JSON object, conforming to the report wire format v1.

“store report”, version 3

Note: This version is deprecated, use the latest version instead.

Similar to replace catalog version 4, this version of store report adds support for environments and creates an explicit link between command version and wire format version. This is a backward compatible change with version 2.

The payload is expected to be a report, containing events that occurred on Puppet resources. It is structured as a JSON object, conforming to the report wire format v3.

“store report”, version 4

This version of store reports, includes a new top level status field to store the overall status of a puppet run.

The payload is expected to be a report, containing events that occurred on Puppet resources. It is structured as a JSON object, conforming to the report wire format v4.

Examples using curl

To post a replace facts command you can use the following curl command:

curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"command":"replace facts","version":3,"payload":{"name":"test1","environment":"DEV","values":{"myfact":"myvalue"}}}' \
  http://localhost:8080/v3/commands

An example of deactivate node:

curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"command":"deactivate node","version":2,"payload":"test1"}' \
  http://localhost:8080/v3/commands
Back to top
The page rank or the 1 our of 5 rating a user has given the page.
The email address of the user submitting feedback.
The URL of the page being ranked/rated.