Forming node classifier requests
Sections
Requests to the node classifier API must be well-formed HTTP(S) requests.
By default, the node classifier service listens on port 4433 and all
endpoints are relative to the /classifier-api/
path. For example, the full URL for the /v1/groups
endpoint on localhost would be https://localhost:4433/classifier-api/v1/groups
.
If needed, you can change the port the classifier API listens on.
Authenticating to the node classifier API
You need to authenticate requests to the node classifier API. You can do this using RBAC authentication tokens or with the list of allowed RBAC certificates.
Authentication token
You can make requests to the node classifier API using RBAC authentication tokens.
For detailed information about authentication tokens, see token-based authentication.
/groups
endpoint of the node classifier
API to get a list of all groups that exist in the node classifier, along with their
associated metadata. The example assumes that you have already generated a token
with puppet-access
login
.auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups"
curl --insecure --header "$auth_header" "$uri"
Copied!
See Usage notes for curl examples for information about forming curl commands.
uri="https://$(puppet config print server):4433/classifier-api/v1/groups?token=$(puppet-access show)"
curl --insecure "$uri"
Copied!
Authenticating using an allowed certificate
You can also authenticate requests using a certificate listed in RBAC's certificate allowlist.
The RBAC allowlist is located at
/etc/puppetlabs/console-services/rbac-certificate-allowlist
. If
you edit this file, you must reload the pe-console-services
service
for your changes to take effect (sudo service pe-console-services
reload
). You can attach the certificate using the command line as
demonstrated in the example cURL query below. You must have the allowed certificate
name and the private key to run the script.
The following query returns a list of all groups that exist in the node classifier, along with their associated metadata. This query shows how to attach the allowlist certificate to authenticate the node classifier API.
/etc/puppetlabs/console-services/rbac-certificate-allowlist
.type_header='Content-Type: application/json'
cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups"
curl --header "$type_header" --cert "$cert" --cacert "$cacert" --key "$key" "$uri"
Copied!
You do not need to use an agent certificate for authentication.
You can use puppet cert generate
to
create a new certificate specifically for use with the API.
Using pagination parameters
If you have a large number of groups, classes, nodes, node check-ins, or environments, then sending a GET request through the classifier API could return an excessively large number of items.
To limit the number of items returned, you can use the limit
and offset
parameters.
-
limit
: The value of thelimit
parameter limits how many items are returned in a response. The value must be a non-negative integer. If you specify a value other than a non-negative integer, you get a 400 Bad Request error. -
offset
: The value of theoffset
parameter specifies the number of item that are skipped. For example, if you specify an offset of 20 with a limit of 10, as shown in the example below, the first 20 items are skipped and you get back item 21 through to item 30. The value must be a non-negative integer. If you specify a value other than a non-negative integer, you get a 400 Bad Request error.
limit
and
offset
parameters.type_header='Content-Type: application/json'
cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"
uri="https://$(puppet config print server):4433/classifier-api/v1/groups?limit=10&offset=20"
curl --header "$type_header" --cert "$cert" --cacert "$cacert" --key $key "$uri"
Copied!
See Usage notes for curl examples for information about forming curl commands.