Advanced Concept of Status API in Puppet

Status API in Puppet: services endpoint

/service is an endpoint. This endpoint returns information about the running services. We use this information in integrating and scripting with other services. The information it returns is understood by machines. 

We have two variations for this endpoint. Let us see its usage, request, and response format.

GET/status/v1/services

This returns the status of all the PE services on a particular port.

Request Format

For this endpoint, we need to specify the port for the PE service we want to query. Below is a table that has the ports and the service linked to it:

We need to add the following:

level: It tells how rigorous the check should run. 

timeout: It sets the limit for the check and is specified in seconds.

For example: Below is a request that returns the info status of a PE:

cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"

curl --cert "$cert" --cacert "$cacert" --key "$key" \
--header "Content-Type: application/json" \
--request GET "https://puppet.status.example:4433/status/v1/services?level=info&timeout=50"

Response Format

For queries to this endpoint, we get a JSON object. The object contains a list of details about the PE. The server responds using either code- 200, 503, or 400. The meaning of these codes are in the table at the article's end. The following table represents the key and their meaning.

GET/status/v1/services/<service_name>

This returns the status of the PE services whose name is specified.

Request Format

We need to specify the service name and their respective port number for this endpoint. Below is a table that has the ports and the service linked to it:

The content type and parameter for this are the same as the get/status/v1/services. 

For example: Below is a request that returns the info status of a classifier service:

cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"

curl --cert "$cert" --cacert "$cacert" --key "$key" \
--header "Content-Type: application/json" \
--request GET "https://puppet.example.com:4433/status/v1/services/classifier-service?level=info&timeout=50"

Response Format

We get a JSON object for queries to this endpoint, just like for GET/status/v1/services. The server responds using either code- 200, 503, 404, or 400. 

Status API in Puppet: services plaintext endpoint

service plaintext endpoints are helpful in cases where JSON parsing or parameter setting is impossible. It returns a string containing the service state and a status code.

GET/status/v1/simple

The above endpoint provides a status for all the services the status service has an idea about.

Request Format

For this endpoint, we need to specify the port for the PE service we want to query. It uses text/plain; charset=utf-8 as its content type. Also, no parameters are accepted in this endpoint. 

Response Format

200 and 503 are the response code that the server uses. The status of all the services the endpoint has an idea about is the response we get for the request. It can return 3 values: running - which means that all the services are running; error - which means that either one or more services report an error; and unknown - when no services report an error, but any one service is unknown.

GET/status/v1/simple/<service_name>

This returns the status for a specific service we specify in the place of <service_name>.

Request Format

It is the same as that for the GET/status/v1/simple endpoint. It just needs a specific service name to process the request. The service name can be activity-service,classifier-service, code-manager-service, orchestrator-service, puppetdb-service, rbac-service, or server.

Response Format

The server responds with 200, 503, or 400 response codes and their respective messages. 

Status API: metrics endpoint

We use metrics endpoint when we want additional information about Puppet Server. We use the debug value for the limit parameter to get this metric. 

Let us see the type of metrics endpoints:

GET /status/v1/services/pe-jruby-metrics

This endpoint returns information about the JRuby pools. It is in JSON format.

Request Format

The port number for this endpoint is 8140, and the value for the level parameter is debug.

uri="https://$(puppet config print server):8140/status/v1/services/pe-jruby-metrics?level=debug"
curl --insecure "$uri"

Response Format

The response code for the response for this endpoint is 200 and 503. It also returns information about PE services in JSON format.

There are two sections in the response(in the experimental section)- jruby-pool-lock-status and metrics.

The keys in jruby-pool-lock-status are in the table below:

The keys in metrics are in the table below:

GET/status/v1/services/pe-master

This endpoint provides information about the routes that connect the server and the agent. The information is in JSON format.

Request Format

It is the same as that of the GET/status/v1/services endpoint. Example:

uri="https://$(puppet config print server):8140/status/v1/services/pe-master?level=debug"
curl --insecure "$uri"

Response Format

The response codes for this endpoint are 200 and 503. It also returns information about the PE services in JSON format. There’s a subsection in the experimental section of the response which has the following keys:

GET/status/v1/services/pe-puppet-profiler

It provides us with statistics about catalog compilation. It is in JSON format. 

Request Format

Again the request format is the same as that of the GET/status/v1/services endpoint. We need to add pe-puppet-profiler at the end. Example:

uri="https://$(puppet config print server):8140/status/v1/services/pe-puppet-profiler?level=debug"
curl --insecure "$uri"

Response Format

The server responds with codes 200 or 503. The metrics have two subsections: 

function-metrics and resource-metrics. They both contain the following keys:

Table for different response codes:

Here are some examples of Response Code and their description:

Frequently Asked Questions

What are the values for the level parameter?

There are three values for the level parameter: info, debug, and critical.

What is the default value of the timeout parameter?

The default value for the timeout parameter is 30 (seconds).

What value do we use for the level parameter in the metrics endpoint?

We use debug value for the level parameter in the metrics endpoint.

Do we need to change the port number in the request if we change the service's port number?

Yes, we need to specify the port number in the request.

Conclusion

In this article, we learned about advanced concept of status API in Puppet. We saw status API in Puppet’s service endpoints, metrics endpoints, and plaintext endpoints. We saw the request and response format for every endpoint, along with the examples. Check out the Coding Ninjas Studio library to learn more about Puppet. See: 

• Admin API version 1 in PuppetDB
• SAML Authentication in Puppet
• About Activity service API in Puppet 

 Don't stop yourself here. Also, practice data structures and algorithms, interview questions, DBMS, computer networks, and operating systems to crack the interviews of big tech giants. Explore other fields like machine learning, deep learning, computer vision, and big data. Also, check out Interview Experiences for different companies.

Happy learning!