Concept of Status API in Puppet

Introduction

In this article, we will learn about the Concept of status API in Puppet, but before that, let us understand what Puppet is. An open-source system management tool called Puppet is used to automate and centralize configuration management. Configuration management involves meticulous logging and updating of data that specifies an organization's hardware and software.

Puppet Enterprise (PE) enables you to manage your IT infrastructure while being productive, agile, and collaborative. PE blends a model-driven approach with imperative task execution to help you manage hybrid infrastructure successfully throughout its lifespan. Puppet Enterprise offers a single vocabulary for all IT business teams to properly implement techniques like version control, code review, automated testing, continuous integration, and automated deployment. In this article, we will discuss Status API in Puppet. I hope you got an idea of Puppet now; let’s move on to this article's main topic, which is the Concept of Status API in Puppet.

Status API

The status API may be used to examine the Puppet Enterprise (PE) components and services. It may automatically monitor your infrastructure, remove unhealthy service instances from a load-balanced pool, check configuration variables, and debug PE issues.

Several ports are used by the status API endpoints. Endpoints can be used to query all services on a specific port or a particular service on a specific port. The following are the ports and services available at each port:

Note: The status API documentation makes use of the default ports. If you change the port of service, you may need to alter the port number in your endpoint request.

Endpoint answers might provide an overall health state (healthy, error, or unknown) as well as particular information like database availability, the health of other needed services, or connection to the parent server.

• Status API authentication

The status API does not need token-based authentication. You may use certificates to authenticate requests or HTTP to access the API without authentication.

• Creating API status requests

When creating status API calls, you must include the port number of the Puppet Enterprise (PE) service you wish to check.

• API Status: services endpoint

The /services endpoints give machine-consumable information about services that are operating. They are designed to be scripted and integrated with other services.

• Status API: plaintext endpoint for services

The plaintext status service endpoints are designed for load balancers that do not allow JSON processing or parameter setting. These endpoints return simple string bodies with a suitable status code (either the service's condition or a basic error message).

• Endpoint Status of the Status API

Puppet Server can track sophisticated Status to provide more information about its performance and health.

Status API Authentication 

The status API does not need token-based authentication. You may use certificates to authenticate requests or HTTP to access the API without authentication.

Certificate verification 

Requests can be authenticated using a certificate from RBAC's certificate allowlist, which can be found at /etc/puppetlabs/console-services/rbac-certificate-allowlist. The certificate allowlist is a basic file that contains certnames that match the host, such as:

test1.example
test2.example
test3.example

If you change the certificate allowlist, you must restart the pe-console-services service (sudo service pe-console-services reload) for the changes to take effect.

You must include the permitted certificate name (that must match a name in the rbac-certificate-allowlist file) and the private key in a curl request to use the certificate. This example explains how to add an acceptable certificate in a curl request using puppet commands:

cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"
uri="https://$(puppet config print server):4433/status/v1/services"


curl --cert "$cert" --cacert "$cacert" --key "$key" "$uri"

HTTP Authentication

Endpoints of the Status API can be provided through HTTP, which does not require authentication. However, this is disabled by default. To enable HTTP:

1. Navigate to the PE Console node group in the PE console.
    
2. Set console_services_plaintext_status_enabled to true on the puppet enterprise::profile::console class.

The HTTP status endpoint port is 8123 by default. To change the port: 

1. Navigate to the PE Console node group in the PE console.
    
2. Set the console_services_plaintext_status_port argument on the puppet enterprise::profile::console class to the appropriate port number.

Forming Status API Requests 

When creating status API calls, you must include the port number of the Puppet Enterprise (PE) service you wish to check.

Status API queries must contain the following URI path:

https://<DNS>:<PORT>/status/v1/<ENDPOINT>

The variables in the route are derived from the following:

• DNS: The DNS name of your PE console host. You can input it manually or use a puppet command.
   
• PORT: The port number connected with the service(s) to be queried.
   
• ENDPOINT: A section or sections that define the endpoint, such as services. Some endpoints, such as the GET /status/v1/services/SERVICE NAME> endpoint, require extra components.

To access the GET /status/v1/services endpoint for all PE services on port 8140, for example, type: GET https://$(puppet config print server):8140/status/v1/service

You might use one of these URLs to reach the GET /status/v1/services/<SERVICE NAME> endpoint for the RBAC service on port 4433:

https://puppet.status.example:4433/status/v1/services/rbac-service
https://(puppet config print server):4433/status/v1/services/rbac-service

To finish a curl command, you must specify suitable curl arguments, Status API authentication, and the content type and/or other parameters applicable to the endpoint you are contacting.

Default Ports

The following are the standard ports for services that may be queried using the status API endpoints. If you modified the port of service in your installation's configuration, you must use that port instead.