Admin API version 1 in PuppetDB

Introduction

Hey Ninja, In this article, we will briefly discuss Puppet and look at Puppet admin API version 1 command endpoints. Puppet lets us generate reports and perform automation and configurations. In a broader sense, a Puppet is an automation tool, a configuration management program. The primary concept is to have a single central server with all important machine configuration information.

This article will discuss the various endpoints of the Admin API version 1 in PuppetDB. If you are interested in Puppet, you can also check out Ansible Vs Puppet and see the distinction between these two similar and popular tools.

Admin Commands Endpoint

We can use the Admin Commands Endpoint or /cmd endpoint to trigger PuppetDB maintenance operations or delete a node directly. Puppet processes Admin commands synchronously separate from other PuppetDB commands.

You must trigger the Admin command using POST like this:

POST /pdb/admin/v1/cmd

Request Format

The POST request for the command endpoint must specify Content-Type: application/json and the body of this request will be:

{"command": "...",
 "version": 123,
 "payload": <json object>}

In the above code format, the parameters are as follows:

• command: This is a string value that identifies the command
   
• version: This field is for a JSON integer describing the version of the given command you are trying to invoke. It also indicates the version of the wire format to use for the command.
   
• payload: This field must contain a valid JSON object of any type. It's up to the specific handler function to interpret that object.

URL Parameters

POST endpoint does not accept any parameters.

Admin Commands

There are two types of Admin Commands for the Admin API version 1. They are:

• clean
   
• delete
   

Let us now see a little more details about these two.

‘clean’ in Admin API Version 1

As the name suggests, we can use this command for cleanup in Admin API version 1. The structure of the command looks like this:

{"command" : "clean",
 "version" : 1,
 "payload" : [REQUESTED_OPERATION, ...]}

Here the valid entries for REQUESTED_OPERATIONS are "purge_nodes", "purge_reports", "expire_nodes", and “other”.

You can also specify a batch limit using "purge_nodes" that will restrict the maximum number of nodes purged to the specified value (for example, 25). Otherwise, the limit will be the node-purge-gc-batch-limit.

["purge_nodes" {"batch_limit" : 25}]

Response Format

The response type for this command is application/json, which will include the following JSON map:

{"ok": true}

Note: You can only run one maintenance operation at a time. If another maintenance operation is already in progress, the HTTP response status will be 409 (conflict) and include a map, as shown below. Due to this, Puppet will perform no additional maintenance. The msg and details may vary, but the kind will always be "conflict."

{"kind": "conflict",
 "msg": "Another cleanup is already in progress",
 "details": null}

Example

Below is the example for this Admin command

$ curl -X POST http://localhost:8080/pdb/admin/v1/cmd \
       -H 'Accept: myapplication/json' \
       -H 'Content-Type: myapplication/json' \
       -d '{"command": "clean",
            "version": 1,
            "payload": ["expire_nodes", "purge_nodes"]}'
{"ok": true}

‘delete’ in Admin API Version 1

In contrast to the "clean" command, you can use the "delete" command to trigger the deletion of all data associated with a certname immediately in Admin API version 1. The structure for this command looks like this:

{"command" : "delete",
 "version" : 1,
 "payload" : {"certname" : <string>}}

Note: The delete operation does not account for commands which may be in the command queue but not yet processed by PuppetDB. That may cause a node targeted for deletion to reappear when the command in the queue gets processed after running the deletion operation.

Response Format

Similar to “clean”, the response type for this command is application/json, which will include the following JSON map in Admin API version 1:

{"deleted": "certname"}

Example

Below is the example for the use of this Admin command using curl from localhost.

$ curl -X POST http://localhost:8080/pdb/admin/v1/cmd \
       -H 'Accept: myapplication/json' \
       -H 'Content-Type: myapplication/json' \
       -d '{"command": "delete",
            "version": 1,
            "payload": {"certname" : "node-1"}}'
{"deleted": "node-1"}