Puppet Server HTTP API overview
Puppet Server provides several services via HTTP API, and the Puppet agent application uses those services to resolve a node's credentials, retrieve a configuration catalog, retrieve file data, and submit reports.
Puppet and Puppet CA APIs
Puppet Server's HTTP API is split into two separately versioned APIs:
An API for configuration-related services
An API for the certificate authority (CA).
All configuration endpoints are prefixed with /puppet
, while all CA endpoints are prefixed with /puppet-ca
. All endpoints are explicitly versioned: the prefix is always immediately followed by a string like /v3
(a directory separator, the letter v
, and the version number of the API).
Authorization
Authorization for /puppet
and /puppet-ca
endpoints is controlled with Puppet Server's auth.conf
authorization system.
Puppet V3 HTTP API
The Puppet agent application uses several network services to manage systems. These services are all grouped under the /puppet
API. Other tools can access these services and use the Puppet primary server's data for other purposes.
The V3 API contains endpoints of two types: those that are based on dispatching to Puppet's internal "indirector" framework, and those that are not (namely the environments endpoint).
Every HTTP endpoint that dispatches to the indirector follows the form /puppet/v3/:indirection/:key?environment=:environment
, where:
:environment
is the name of the environment that should be in effect for the request. Not all endpoints need an environment, but the query parameter must always be specified.:indirection
is the indirection to which the request is dispatched.:key
is the "key" portion of the indirection call.
Using this API requires significant understanding of how Puppet's internal services are structured, but the following documents specify what is available and how to interact with it.
Configuration management services
The Puppet agent application directly uses these servcies to manage the configuration of a node.
These endpoints accept payload formats formatted as JSON by default (MIME type of application/json
), except for File Content
and File Bucket File
, which always use application/octet-stream
.
Environments endpoint
The /puppet/v3/environments
endpoint uses a different format than the configuration management and informational services endpoints.
The endpoint accepts only payloads formatted as JSON, and responds with JSON (MIME type of application/json
).
Puppet Server-specific endpoints
Puppet Server adds several unique endpoints of its own. They include these additional /puppet/v3/
endpoints:
Environment classes, at
/puppet/v3/environment_classes
Environment modules, at
/puppet/v3/environment_modules
Static file content, at
/puppet/v3/static_file_content
It also includes these unique APIs, with endpoints containing other URL prefixes:
Status API, at
/status/v1/services
Metrics v1 (mbeans) API, at
/metrics/v1/mbeans
Metrics v2 (Jolokia) API, at
/metrics/v2/
-
Admin API, at
/puppet-admin-api/v1/
:Environment cache, at
/puppet-admin-api/v1/environment-cache
JRuby pool, at
/puppet-admin-api/v1/jruby-pool
Error responses
The environments
endpoint responds to error conditions in a uniform manner and uses standard HTTP response codes to signify those errors.
Request problem | HTTP API error response code |
---|---|
Client submits malformed request | 400 Bad Request |
Unauthorized client | 403 Not Authorized |
Client uses an HTTP method not permitted for the endpoint | 405 Method Not Allowed |
Client requests a response in a format other than JSON | 406 Unacceptable |
Server encounters an unexpected error while handling a request | 500 Server Error |
Server can't find an endpoint handler for an HTTP request | 404 Not Found |
Except for HEAD requests, error responses contain a body of a uniform JSON object with the following properties:
message
: (String
) A human-readable message explaining the error.issue_kind
: (String
) A unique label to identify the error class.
Puppet provides a JSON schema for error objects. Endpoints implemented by Puppet Server have a different error schema:
{
"msg": "",
"kind": ""
}
CA V1 HTTP API
The certificate authority (CA) API contains all of the endpoints supporting Puppet's public key infrastructure (PKI) system.
The CA V1 endpoints share the same basic format as the Puppet V3 API, because they are based on the interface of Puppet's indirector-based CA. However, Puppet Server's CA is implemented in Clojure. Both have a different prefix and version than the V3 API.
These endpoints follow the form /puppet-ca/v1/:indirection/:key
, where:
:indirection
is the indirection to which the request is dispatched.:key
is the "key" portion of the indirection call.
As with the Puppet V3 API, using this API requires a significant amount of understanding of how Puppet's internal services are structured. The following documents specify what is available and how to interact with it.
SSL certificate-related services
These endpoints accept only plain-text payload formats. Historically, Puppet has used the MIME type s
to mean text/plain
. In Puppet 5, it always uses text/plain
, but continues to accept s
as an equivalent.
Serialization formats
Puppet sends messages using several serialization formats. Not all REST services support all of the formats.
Note: PSON has been deprecated in Puppet 7 and removed in Puppet 8. You can use the
allow_pson_serialization=false
setting to prevent Puppet from downgrading from JSON to PSON.