Skip to content

P
puppetdb
Commit 319f654c authored by Andrew Roetker's avatar Andrew Roetker
Browse files
Options

(PDB-840) Retire deprecated commands 

This commit retires all of the previously deprecated commands and
removes all the associated support code for these commands, such as
validation of reports/catalogs for the deprecated versions. This commit
also updatees al the unit/integration tests to use the non-retired
versions of these commands and removes test code we no longer use.
parent cb3e7ffc
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 161 additions and 2144 deletions
documentation/api/commands.markdown
View file @ 319f654c
......@@ -4,12 +4,7 @@ layout: default
canonical: "/puppetdb/latest/api/commands.html"
---
[factsv1]: ./wire_format/facts_format_v1.html
[catalogv1]: ./wire_format/catalog_format_v1.html
[reportv1]: ./wire_format/report_format_v1.html
[factsv2]: ./wire_format/facts_format_v2.html
[factsv3]: ./wire_format/facts_format_v3.html
[catalogv4]: ./wire_format/catalog_format_v4.html
[catalogv5]: ./wire_format/catalog_format_v5.html
[reportv3]: ./wire_format/report_format_v3.html
[reportv4]: ./wire_format/report_format_v4.html
......@@ -73,49 +68,6 @@ 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][catalogv1]. 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][catalogv1]. 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][catalogv1]. 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][catalogv4]. Extra or missing fields
are an error.
### "replace catalog", version 5
Version 5 differs from version 4 by added support of a producer-timestamp
......@@ -128,22 +80,6 @@ The payload is expected to be a Puppet catalog, as a JSON object, conforming
exactly to the [catalog wire format v5][catalogv5]. 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][factsv1]
### "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][factsv2] 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
......@@ -151,40 +87,12 @@ for the producer-timestamp field that will eventually be used for agent
timekeeping. See [fact wire format v3][factsv3] 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][reportv1].
### "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][reportv1].
### "store report", version 3
> **Note:** This version is deprecated, use the latest version instead.
......
documentation/api/index.markdown
View file @ 319f654c
......@@ -108,8 +108,3 @@ All of PuppetDB's "replace" commands contain payload data, which must be in one
* [Facts wire format version 3](./wire_format/facts_format_v3.html)
* [Catalog wire format version 5](./wire_format/catalog_format_v5.html)
* [Report wire format version 3](./wire_format/report_format_v3.html)
* Deprecated - [Facts wire format version 1](./wire_format/facts_format_v1.html)
* Deprecated - [Facts wire format version 2](./wire_format/facts_format_v2.html)
* Deprecated - [Catalog wire format version 1](./wire_format/catalog_format_v1.html)
* Deprecated - [Catalog wire format version 4](./wire_format/catalog_format_v4.html)
* Deprecated - [Report wire format version 1](./wire_format/report_format_v1.html)
documentation/api/wire_format/catalog_format_v4.markdown deleted 100644 → 0
View file @ cb3e7ffc
---
title: "PuppetDB 2.2 » API » Catalog Wire Format, Version 4"
layout: default
canonical: "/puppetdb/latest/api/wire_format/catalog_format_v4.html"
---
[containment]: /puppet/latest/reference/lang_containment.html
[relationship]: /puppet/latest/reference/lang_relationships.html
[chain]: /puppet/latest/reference/lang_relationships.html#chaining-arrows
[metaparameters]: /puppet/latest/reference/lang_relationships.html#relationship-metaparameters
[require]: /puppet/latest/reference/lang_relationships.html#the-require-function
[resource_ref]: /puppet/latest/reference/lang_datatypes.html#resource-references
[numbers]: /puppet/latest/reference/lang_datatypes.html#numbers
[undef]: /puppet/latest/reference/lang_datatypes.html#undef
[namevar]: /puppet/latest/reference/lang_resources.html#namenamevar
[resource]: /puppet/latest/reference/lang_resources.html
[title]: /puppet/latest/reference/lang_resources.html#title
[type]: /puppet/latest/reference/lang_resources.html#type
[attributes]: /puppet/latest/reference/lang_resources.html#attributes
[replace3]: ../commands.html#replace-catalog-version-3
[replace2]: ../commands.html#replace-catalog-version-2
[replace1]: ../commands.html#replace-catalog-version-1
PuppetDB receives catalogs from puppet masters in the following wire format. This format is subtly different from the internal format used by Puppet so catalogs are converted by the [PuppetDB catalog terminus](../../connect_puppet_master.html) before they are sent. [See below][below] for the justification for this separate format.
Catalog Interchange Format
-----
### Version
**Note:** This is **version 4** of the catalog interchange format and has been deprecated. See [version 5][catalog_v5] for the currently supported version of this wire format.
### Encoding
The entire catalog is serialized as JSON, which requires strict UTF-8 encoding. Unless otherwise noted, null is not allowed anywhere in the catalog.
### Main Data Type: Catalog
{
"name": <string>,
"version": <string>,
"environment": <string>,
"transaction-uuid": <string>,
"edges":
[<edge>, <edge>, ...],
"resources":
[<resource>, <resource>, ...]
}
#### `name`
String. The name of the node for which the catalog was compiled.
#### `version`
String. An arbitrary string that uniquely identifies this specific catalog across time for a single node. This is controlled by Puppet's [`config_version` setting](/references/latest/configuration.html#configversion) and is usually the seconds elapsed since the epoch.
#### `environment`
String. The envrionment associated to the node when the catalog was compiled.
#### `edges`
List of [`<edge>` objects](#data-type-edge). **Every** [relationship][] between any two resources in the catalog, which may have been made with [chaining arrows][chain], [metaparameters][], or [the `require` function][require].
> **Notes:**
>
> * "Autorequire" relationships are not currently encoded in the catalog.
> * This key is significantly different from its equivalent in Puppet's internal catalog format, which only encodes containment edges.
#### `resources`
List of [`<resource>` objects](#data-type-resource). Contains **every** resource in the catalog.
#### `transaction-uuid`
String. A string used to match the catalog with the corresponding report that was issued during the same puppet run.
This field may be `null`. (Note: support for this field was introduced in
[Version 3 of the "replace catalog" command][replace3]. Versions prior to version 3 will populate this field with
a `null` value.
### Data Type: `<string>`
A JSON string. Because the catalog is UTF-8, these must also be UTF-8.
### Data Type: `<integer>`
A JSON int.
### Data Type: `<boolean>`
A JSON boolean.
### Data Type: `<edge>`
A JSON object of the following form, which represents a [relationship][] between two resources:
{"source": <resource-spec>,
"target": <resource-spec>,
"relationship": <relationship>}
All edges are normalized so that the "source" resource is managed **before** the "target" resource. To do this, the Puppet language's "require" and "subscribe" [relationship types][relationship] are munged into "required-by" and "subscription-of" when they are converted into edges.
The keys of an edge are `source`, `target`, and `relationship`, all of which are required.
#### `source`
A [`<resource-spec>`](#data-type-resource-spec). The resource which should be managed **first.**
#### `target`
A [`<resource-spec>`](#data-type-resource-spec). The resource which should be managed **second.**
#### `relationship`
A [`<relationship>`](#data-type-relationship). The way the two resources are related.
### Data Type: `<resource-spec>`
(Synonym: `<resource-hash>`.)
The JSON representation of a [resource reference][resource_ref] (single-resource kind). An object of the following form:
{"type": <string>,
"title": <string>}
The resource named by a resource-spec **must** exist in the catalog's `"resources"` list. Note also that the title must be the resource's actual [title][], rather than an alias or [name/namevar][namevar].
### Data Type: `<relationship>`
One of the following exact strings, when used in the `relationship` key of an [`<edge>` object](#data-type-edge):
* `contains`
* `before`
* `required-by`
* `notifies`
* `subscription-of`
**Note:** Regardless of the relationship type, the "source" resource is always managed **before** the "target" resource. This means that, functionally speaking, `required-by` is a synonym of `before` and `subscription-of` is a synonym of `notifies`. In this catalog format, the different relationship types preserve information about the _origin_ of the relationship.
String | Relationship Type | Origin of Relationship
------------------|--------------------------|-----------------------
`contains` | [containment][] | Class or defined type [containment][]
`before` | ordering | `before` metaparam on source, or `->` chaining arrow
`required-by` | ordering | `require` metaparam on target, or `require` function
`notifies` | ordering w/ notification | `notify` metaparam on source, or `~>` chaining arrow
`subscription-of` | ordering w/ notification | `subscribe` metaparam on target
### Data Type: `<resource>`
A JSON object of the following form, which represents a [Puppet resource][resource]:
{"type": <string>,
"title": <string>,
"aliases": [<string>, <string>, ...],
"exported": <boolean>,
"file": <string>,
"line": <string>,
"tags": [<string>, <string>, ...],
"parameters": {<string>: <JSON object>,
<string>: <JSON object>,
...}
}
The eight keys in a resource object are `type`, `title`, `aliases`, `exported`, `file`, `line`, `tags` and `parameters`. All of them are **required.**
#### `type`
String. The [type][] of the resource, **capitalized.** (E.g. `File`, `Service`, `Class`, `Apache::Vhost`.) Note that every segment must be capitalized if the type includes a namespace separator (`::`).
#### `title`
String. The [title][] of the resource.
#### `aliases`
List of strings. Includes **every** alias for the resource, including the value of its [name/namevar][namevar] and any extra names added with the `"alias"` metaparameter.
#### `exported`
Boolean. Whether or not this is an exported resource.
#### `file`
String. The manifest file in which the resource definition is located.
#### `line`
Positive integer. The line (of the containing manifest file) at which the resource definition can be found.
#### `tags`
List of strings. Includes every tag the resource has. This is a normalized superset of the value of the resource's `tag` attribute.
#### `parameters`
JSON object. Includes all of the resource's [attributes][] and their associated values. The value of an attribute may be any JSON data type, but Puppet will only provide booleans, strings, arrays, and hashes --- [resource references][resource_ref] and [numbers][] in attributes are converted to strings before being inserted into the catalog. Attributes with [undef][] values are not added to the catalog.
Why a version 4 of the catalog wire format?
-----
[below]: #why-a-v4-catalog-wire-format
Prior to version 4 of the replace catalog command, there was a single
version of the catalog wire format. How that wire format was
interpreted was different from one command version to another. This
approach changed in version 4 of the "replace catalog" command. Each
command is tied to a the wire format version of the same number.
### Differences with the previous catalog wire format
There were a number of small changes to the previous (v1) of the catalog wire format
1. The top-level object, containing the "metadata" and "data" keys was removed. "api_version" is no longer included in the command. What was the value of "data" is now the top level object.
2. A new top-level key "environment" was added
documentation/api/wire_format/catalog_format_v5.markdown
View file @ 319f654c
......@@ -212,8 +212,3 @@ List of strings. Includes every tag the resource has. This is a normalized super
#### `parameters`
JSON object. Includes all of the resource's [attributes][] and their associated values. The value of an attribute may be any JSON data type, but Puppet will only provide booleans, strings, arrays, and hashes --- [resource references][resource_ref] and [numbers][] in attributes are converted to strings before being inserted into the catalog. Attributes with [undef][] values are not added to the catalog.
### Differences with the previous catalog wire format
1. The top-level catalog object now contains a "producer-timestamp" field.
documentation/api/wire_format/facts_format_v1.markdown deleted 100644 → 0
View file @ cb3e7ffc
---
title: "PuppetDB 2.2 » API » Facts Wire Format v1"
layout: default
canonical: "/puppetdb/latest/api/wire_format/facts_format_v1.html"
---
[facts_v3]: facts_format_v3.html
### Version
This is **version 1** of the facts interchange format and has been deprecated. See [version 3][facts_v3] for the currently supported version of this wire format.
## Format
Facts are represented as JSON. Unless otherwise noted, `null` is not
allowed anywhere in the set of facts.
{"name": <string>,
"values": {
<string>: <string>,
...
}
}
The `"name"` key is the certname the facts are associated with.
The `"values"` key points to a JSON _Object_ that represents the set
of facts. Each key is the fact name, and the value is the fact value.
Fact names and values MUST be strings.
## Encoding
The entire fact set is expected to be valid JSON, which mandates UTF-8
encoding.
documentation/api/wire_format/facts_format_v2.markdown deleted 100644 → 0
View file @ cb3e7ffc
---
title: "PuppetDB 2.2 » API » Facts Wire Format Version 2"
layout: default
canonical: "/puppetdb/latest/api/wire_format/facts_format_v2.html"
---
[facts_v3]: facts_format_v3.html
### Version
This is **version 2** of the facts interchange format and has been deprecated. See [version 3][facts_v3] for the currently supported version of this wire format.
## Facts Wire Format - Version 2
Facts are represented as JSON. Unless otherwise noted, `null` is not
allowed anywhere in the set of facts.
{"name": <string>,
"environment": <string>,
"values": {
<string>: <string>,
...
}
}
The `"name"` key is the certname the facts are associated with.
The `"environment"` key is the environment associated to the node when the facts were collected.
The `"values"` key points to a JSON _Object_ that represents the set
of facts. Each key is the fact name, and the value is the fact value.
Fact names and values MUST be strings.
## Encoding
The entire fact set is expected to be valid JSON, which mandates UTF-8
encoding.
Differences with the fact wire format version 1
-----
1. Added an "environment" key to the top-level facts object
documentation/api/wire_format/facts_format_v3.markdown
View file @ 319f654c
......@@ -35,9 +35,3 @@ Fact names and values MUST be strings.
The entire fact set is expected to be valid JSON, which mandates UTF-8
encoding.
Differences with the fact wire format version 2
-----
1. Added an "producer-timestamp" key to the top-level facts object
documentation/api/wire_format/report_format_v1.markdown deleted 100644 → 0
View file @ cb3e7ffc
---
title: "PuppetDB 2.2 » API » Report Wire Format, Version 1"
layout: default
canonical: "/puppetdb/latest/api/wire_format/report_format_v1.html"
---
[api]: ../index.html
[report_v3]: report_format_v3.html
### Version
This is **version 1** of the report interchange format and has been deprecated. See [version 3][report_v3] for the currently supported version of this wire format.
## Report interchange format
A report is represented as JSON (this implies UTF-8 encoding). Unless
otherwise noted, `null` is not allowed anywhere in the report.
{
"certname": <string>,
"puppet-version": <string>,
"report-format": <int>,
"configuration-version": <string>,
"start-time": <datetime>,
"end-time": <datetime>,
"resource-events": [<resource-event>, <resource-event>, ...],
"transaction-uuid" : <string>
}
All keys are mandatory unless otherwise noted, though values that are lists may be empty lists.
`"certname"` is the certname the report is associated with.
`"puppet-version"` is the version of puppet that was run to generate this report.
`"report-format"` is the version number of the report format that puppet used
to generate the original report data. This is a constant defined by puppet.
`"configuration-version"` is an identifier string that puppet uses to match a
specific catalog for a node to a specific puppet run. This value is
generated by puppet.
`"start-time"` is the time at which the puppet run began; see more details about
the `datetime` format below.
`"end-time"` is the time at which the puppet run completed; see more details about
the `datetime` format below.
`"transaction-uuid"` is a string used to identify a puppet run. It can be used to
match a report with the catalog that was used for the run. This field may be `null`.
### Encoding
The entire report is expected to be valid JSON, which implies UTF-8
encoding.
### Data type: `<string>`
A JSON string. By virtue of the report being UTF-8, these must also
be UTF-8.
### Data type: `<integer>`
A JSON int.
### Data type: `<datetime>`
A JSON string representing a date and time (with time zone), formatted based on
the recommendations in ISO8601; so, e.g., for a UTC time, the String would be
formatted as `YYYY-MM-DDThh:mm:ss.sssZ`. For non-UTC, the `Z` may be replaced
with `±hh:mm` to represent the specific timezone.
### Data type: `<resource-event>`
A JSON Object of the following form:
{
"resource-type": <string>,
"resource-title": <string>,
"property": <string>,
"timestamp": <datetime>,
"status": <string>,
"old-value": <string>,
"new-value": <string>,
"message": <string>,
"file": <string>,
"line: <integer>,
"containment-path": [<string>, <string>, ...]
}
All keys are required.
`"resource-type"` is the name of the puppet resource type that the event occurred on.
`"resource-title"` is the title of the puppet resource that the event occurred on.
`"property"` is the name of the property of the resource for which the event occurred.
This may be `null` only if the `status` is `skipped`.
`"timestamp"` is the date/time at which the event occurred.
`"status"` is a string representing the outcome of the event; this should be one
of `success`, `failure`, or `skipped`.
`"old-value"` is the value that puppet determined the property to have held prior
to the event.
`"new-value"` is the value that puppet was instructed to set the property to.
`"message"` is a descriptive message providing extra information about the event.
This should be `null` if `status` is `success`.
`"file"` is the manifest in which the resource is defined. This field may be `null`.
`"line"` is the line number (within `"file"`) where the resource is defined. This field may be `null`.
`"containment-path"` is a collection of strings where each string is a Puppet type or class
that represents the containment hierarchy of the resource within the catalog. This field may be `null`.
## Gaps with this wire format
1. Binary data needs to be dealt with (hopefully only for the `old-value` and
`new-value` fields.
documentation/api/wire_format/report_format_v3.markdown deleted 100644 → 0
View file @ cb3e7ffc
---
title: "PuppetDB 2.2 » API » Report Wire Format, Version 3"
layout: default
canonical: "/puppetdb/latest/api/wire_format/report_format_v3.html"
---
> **Note:** This version is deprecated, use the latest version instead.
## Report interchange format
A report is represented as JSON (this implies UTF-8 encoding). Unless
otherwise noted, `null` is not allowed anywhere in the report.
{
"certname": <string>,
"environment": <string>,
"puppet-version": <string>,
"report-format": <int>,
"configuration-version": <string>,
"start-time": <datetime>,
"end-time": <datetime>,
"resource-events": [<resource-event>, <resource-event>, ...],
"transaction-uuid": <string>
}
All keys are mandatory unless otherwise noted, though values that are lists may be empty lists.
`"certname"` is the certname the report is associated with.
`"report"` is the environment associated to the node at the time of the report
`"puppet-version"` is the version of puppet that was run to generate this report.
`"report-format"` is the version number of the report format that puppet used
to generate the original report data. This is a constant defined by puppet.
`"configuration-version"` is an identifier string that puppet uses to match a
specific catalog for a node to a specific puppet run. This value is
generated by puppet.
`"start-time"` is the time at which the puppet run began; see more details about
the `datetime` format below.
`"end-time"` is the time at which the puppet run completed; see more details about
the `datetime` format below.
`"transaction-uuid"` is a string used to identify a puppet run. It can be used to
match a report with the catalog that was used for the run. This field may be `null`.
### Encoding
The entire report is expected to be valid JSON, which implies UTF-8
encoding.
### Data type: `<string>`
A JSON string. By virtue of the report being UTF-8, these must also
be UTF-8.
### Data type: `<integer>`
A JSON int.
### Data type: `<datetime>`
A JSON string representing a date and time (with time zone), formatted based on
the recommendations in ISO8601; so, e.g., for a UTC time, the String would be
formatted as `YYYY-MM-DDThh:mm:ss.sssZ`. For non-UTC, the `Z` may be replaced
with `±hh:mm` to represent the specific timezone.
### Data type: `<resource-event>`
A JSON Object of the following form:
{
"resource-type": <string>,
"resource-title": <string>,
"property": <string>,
"timestamp": <datetime>,
"status": <string>,
"old-value": <string>,
"new-value": <string>,
"message": <string>,
"file": <string>,
"line: <integer>,
"containment-path": [<string>, <string>, ...]
}
All keys are required.
`"resource-type"` is the name of the puppet resource type that the event occurred on.
`"resource-title"` is the title of the puppet resource that the event occurred on.
`"property"` is the name of the property of the resource for which the event occurred.
This may be `null` only if the `status` is `skipped`.
`"timestamp"` is the date/time at which the event occurred.
`"status"` is a string representing the outcome of the event; this should be one
of `success`, `failure`, or `skipped`.
`"old-value"` is the value that puppet determined the property to have held prior
to the event.
`"new-value"` is the value that puppet was instructed to set the property to.
`"message"` is a descriptive message providing extra information about the event.
This should be `null` if `status` is `success`.
`"file"` is the manifest in which the resource is defined. This field may be `null`.
`"line"` is the line number (within `"file"`) where the resource is defined. This field may be `null`.
`"containment-path"` is a collection of strings where each string is a Puppet type or class
that represents the containment hierarchy of the resource within the catalog. This field may be `null`.
## Gaps with this wire format
1. Binary data needs to be dealt with (hopefully only for the `old-value` and
`new-value` fields.
Why a version 3 of the report wire format?
-----
[below]: #why-a-v3-report-wire-format
Prior to version 3 of the store report command, there was a single
version of the report wire format. How that wire format was
interpreted was different from one command version to another. This
approach changed in version 3 of the store report command. Beginning
with version 3, each command is tied to a the wire format version of
the same number.
### Differences with the previous report wire format
1. A new top-level key "environment" was added
documentation/api/wire_format/report_format_v4.markdown
View file @ 319f654c
......@@ -117,7 +117,3 @@ This should be `null` if `status` is `success`.
`"containment-path"` is a collection of strings where each string is a Puppet type or class
that represents the containment hierarchy of the resource within the catalog. This field may be `null`.