Puppet RESTful API

Puppet is a configuration management tool that helps automate the provisioning, configuring, and managing of infrastructure resources. Puppet provides a RESTful API that allows users to interact with the Puppet server programmatically.

Introduction

Puppet RESTful API is a web-based API that allows users to perform common administration tasks on the Puppet server, such as node management, classification, and reporting. The API is built on top of HTTP and utilizes a Representational State Transfer (REST) architecture.

Features

The Puppet RESTful API provides several features that allow users to:

• Create, update, and delete nodes.
• Assign and modify node classifications.
• Generate reports on Puppet runs.
• Retrieve facts and variables from nodes.
• Query the state of resources on nodes.

Authentication

Puppet RESTful API uses token-based authentication. To use the API, users must first obtain a token by sending their credentials to the Puppet server. The token is then used for all subsequent API requests.

curl -X POST https://puppetserver:8140/puppet-admin/v1/auth/token \
-H 'Content-Type: application/json' \
-d '{"login": "user", "password": "password"}'

The response will contain a JSON object with the token:

{
    "token": "eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU"
}

This token can then be used in subsequent RESTful API requests by including it in the X-Authentication header:

curl -X GET https://puppetserver:8140/puppet-admin/v1/nodes \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

Resources

The Puppet RESTful API provides several resources that can be queried and updated:

Node resource

The node resource allows users to manage and query nodes in Puppet. Nodes can be created, updated, deleted, and queried.

# List all nodes
curl -X GET https://puppetserver:8140/puppet-admin/v1/nodes \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

# Get a node
curl -X GET https://puppetserver:8140/puppet-admin/v1/nodes/test-node \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

# Create a node
curl -X POST https://puppetserver:8140/puppet-admin/v1/nodes \
-H 'Content-Type: application/json' \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU' \
-d '{"name": "test-node", "facts": {"osfamily": "Redhat", "operatingsystem": "CentOS", "kernelrelease": "3.10"}}'

# Update a node
curl -X PUT https://puppetserver:8140/puppet-admin/v1/nodes/test-node \
-H 'Content-Type: application/json' \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU' \
-d '{"facts": {"osfamily": "Redhat", "operatingsystem": "CentOS", "kernelrelease": "4.1"}}'

# Delete a node
curl -X DELETE https://puppetserver:8140/puppet-admin/v1/nodes/test-node \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

Classification resource

The classification resource allows users to assign and modify node classifications in Puppet. Classifications can be created, updated, deleted, and queried.

# List all classifications
curl -X GET https://puppetserver:8140/puppet-admin-api/v1/classifications \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

# Get a classification
curl -X GET https://puppetserver:8140/puppet-admin-api/v1/classifications/webserver \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

# Assign a classification to a node
curl -X PUT https://puppetserver:8140/puppet-admin-api/v1/classifications/webserver \
-H 'Content-Type: application/json' \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU' \
-d '{"nodes":["test-node"]}}'

# Delete a classification
curl -X DELETE https://puppetserver:8140/puppet-admin-api/v1/classifications/webserver \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

Report resource

The report resource allows users to generate reports on Puppet runs. Reports can be retrieved and queried.

# List all reports
curl -X GET https://puppetserver:8140/puppet-admin/v1/reports \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

# Get a report
curl -X GET https://puppetserver:8140/puppet-admin/v1/reports/123 \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

Fact resource

The fact resource allows users to retrieve facts and variables from nodes.

# List all facts for a node
curl -X GET https://puppetserver:8140/puppet-admin/v1/facts/test-node \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

# Get a specific fact for a node
curl -X GET https://puppetserver:8140/puppet-admin/v1/facts/test-node/operatingsystem \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

Resource status resource

The resource status resource allows users to query the state of resources on nodes.

# List all resource statuses for a node
curl -X GET https://puppetserver:8140/puppet-admin/v1/status/test-node \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

# Get the status of a specific resource on a node
curl -X GET https://puppetserver:8140/puppet-admin/v1/status/test-node/File%5B%27/var/log/messages%27%5D \
-H 'X-Authentication: eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJweXRob24tc2VydmVyIiwibmJmIjoxNTkwNzRjMzMxLCJleHAiOjE1OTA3NTYzMzEsImlhdCI6MTU5MDc0YzMzMX0.XX1OiFhPakv6wptRUQKkT5cTAJd2Sj2t0hL2ImJMUxU'

Conclusion

Puppet RESTful API provides a powerful way for users to interact with Puppet programmatically. By utilizing the resources provided by the API, users can automate many of the common administration tasks performed on the Puppet server.