Collect, backup, and restore classification data with the node classifier API for Puppet Enterprise 3.7 to 2019.5

Version and installation information

PE version: 3.7 to 2019.5
Installation type:
3.7 to 2019.1: Monolithic, split
2019.2 and later: Standard

Note: Links to our documentation are for Puppet Enterprise 2019.5. Make sure you've got the right version of docs for your deployment.

Classifier data contains hostnames. Before sending classifier data to us, review it. You might want to redact sensitive information.

1. Pull classification data using the node classifier service API's groups endpoint. To generate data in the current directory in classifier_groups.json, run the following on the console node (the master in a monolithic installation) :

   curl -X GET \
       --cert   $(puppet config print hostcert) \
       --key    $(puppet config print hostprivkey) \
       --cacert $(puppet config print localcacert) \
       https://$(puppet config print server):4433/classifier-api/v1/groups > classifier_groups.json

2. If the request fails, return additional information by running the query again with the --verbose option:

   curl -X GET \
       --cert   $(puppet config print hostcert) \
       --key    $(puppet config print hostprivkey) \
       --cacert $(puppet config print localcacert) \
       https://$(puppet config print server):4433/classifier-api/v1/groups --verbose

Read more about the groups endpoint.

How do I restore my classification data?

Restore backed up classification data to fix unintended changes to classification.

Before you begin: Back up your classification data. When you restore classification data, existing classification data is overwritten.

1. Restore classification data from a .json file by running the following command on the console node (the master in a monolithic installation). Replace with the full path to the .json file containing your backup classifier information.

   curl -X POST -H 'Content-Type: application/json'  \
       --cert   $(puppet config print hostcert) \
       --key    $(puppet config print hostprivkey) \
       --cacert $(puppet config print cacert) \
       --data-binary "@/<PATH TO classifier_groups.json>" \
       https://$(puppet config print server):4433/classifier-api/v1/import-hierarchy

How do I collect classifier data for a particular node?

Use a node classifier API request to collect classifier data for a statically pinned or dynamically grouped node.

1. Generate a file that contains the node's data by running one of the following commands on the console node (the master in a monolithic installation).

• For statically pinned nodes, run the following command to collect classifier data in the current directory in node_classification.json, replacing <NODE NAME> with the FQDN of the node to collect data on, for example: agent.example.com.

  curl -X POST -H 'Content-Type: application/json' \
      --cacert $(puppet config print localcacert) \
      --cert   $(puppet config print hostcert) \
      --key    $(puppet config print hostprivkey) \
      https://$(hostname -f):4433/classifier-api/v1/classified/nodes/<NODE NAME> > node_classification.json

• For dynamically grouped nodes, form a request to collect classifier data including the groups the node is in. To generate the data in the current directory in node_classification.json, run the following command, replacing and with key-value pairs and with the FQDN of the node to collect data on, for example: agent.example.com.

  Note: Groups returned by this request are determined by the facts submitted in the request, so make sure to include every fact that defines the group in your request.

  curl -X POST -H 'Content-Type: application/json' \
       --data '{"fact":{"<FACT>": "<VALUE>", <ADDITIONAL FACTS IN KEY-VALUE PAIRS AS  NEEDED>}}' \
       --cacert $(puppet config print localcacert) \
       --cert   $(puppet config print hostcert) \
       --key    $(puppet config print hostprivkey) \
       https://$(hostname -f):4433/classifier-api/v1/classified/nodes/<NODE NAME> > node_classification.json

How do I collect other classifier data?

Form requests for other node classifier data by modifying the requests included in this article.

By default, the node classifier service listens on port 4433 and all endpoints are relative to the /classifier-api/ path. So, for example, the full URL for the /v1/ groups endpoint on localhost would be https://localhost:4433/classifier-api/v1/groups.

Learn more about forming requests for other endpoints not described in this article in our Node classifier service API documentation. Pay close attention to which request type each endpoint requires.

If you need additional help forming classifier requests, please contact Support.