1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
---
title: "Admin commands endpoint"
layout: default
canonical: "/puppetdb/latest/api/admin/v1/cmd.html"
---
# Admin commands endpoint
[curl]: ../../query/curl.markdown#using-curl-from-localhost-non-sslhttp
[config-purge-limit]: ../../../configure.markdown#node-purge-gc-batch-limit
The `/cmd` endpoint can be used to trigger PuppetDB maintenance
operations or to directly delete a node. Admin commands are processed
synchronously seperate from other PuppetDB commands.
## `POST /pdb/admin/v1/cmd`
Admin commands must be triggered by a POST.
### Request format
The POST request should specify `Content-Type: application/json` and
the request body should look like this:
``` json
{"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.
### URL parameters
* The POST endpoint accepts no URL parameters.
## List of admin commands
## "clean", version 1
``` json
{"command" : "clean",
"version" : 1,
"payload" : [REQUESTED_OPERATION, ...]}
```
where valid `REQUESTED_OPERATION`s are `"expire_nodes"`,
`"purge_nodes"`, `"purge_reports"`, `"gc_packages"`, and `"other"`.
In addition, a purge_nodes operation can be structured like this to
specify a batch_limit:
``` json
["purge_nodes" {"batch_limit" : 50}]
```
When specified, the `batch_limit` restricts the maximum number of
nodes purged to the value specified, and if not specified, the limit
will be the [`node-purge-gc-batch-limit`][config-purge-limit].
An empty payload vector requests all maintenance operations.
### Response format
The response type will be `application/json`, and upon success will
include this JSON map:
``` json
{"ok": true}
```
Only one maintenance operation can be running at a time. If any other
maintenance operation is already in progress the HTTP response status will be
409 (conflict), will include a map like this
``` json
{"kind": "conflict",
"msg": "Another cleanup is already in progress",
"details": null}
```
and no additional maintenance will be performed. The `msg` and
`details` may or may not vary, but the `kind` will always be
"conflict".
### Example
[Using `curl` from localhost][curl]:
``` sh
$ curl -X POST http://localhost:8080/pdb/admin/v1/cmd \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"command": "clean",
"version": 1,
"payload": ["expire_nodes", "purge_nodes"]}'
{"ok": true}
```
## "delete", version 1
``` json
{"command" : "delete",
"version" : 1,
"payload" : {"certname" : <string>}}
```
The `"delete"` command can be used to trigger the immediate deletion of all data
associated with a certname. It is important to note that the delete operation
doesn't account for commands which may be in the command queue but not yet
processed by PuppetDB. This could cause a node targeted for deletion to
reappear when the command in the queue gets processed after the deletion
operation has run.
### Response format
The response type will be `application/json`, and upon success will
include this JSON map:
``` json
{"deleted": "certname"}
```
### Example
[Using `curl` from localhost][curl]:
``` sh
$ curl -X POST http://localhost:8080/pdb/admin/v1/cmd \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"command": "delete",
"version": 1,
"payload": {"certname" : "node-1"}}'
{"deleted": "node-1"}
```
|
