Status API: services endpoint

The /services endpoints provide machine-consumable information about running services. They are intended for scripting and integration with other services.

GET /status/v1/services

Retrieves statuses for all Puppet Enterprise (PE) services on a specific port.

Request format

When Forming status API requests to this endpoint, you must specify the port associated with the PE services you want to query. The default ports and their associated services are as follows:
Port Service(s)
4433
  • RBAC
  • Activity Service
  • Classifier
8140
  • Code Manager
  • File sync client
  • File sync storage
  • Puppet Server

  • PCP broker (compilers)

  • PCP broker v2 (compilers)
8143
  • Orchestrator
  • PCP broker (primary server)
  • PCP broker v2 (primary server)
8081 PuppetDB
Important: If you changed a service's port to something other than the default port, you might need to change the port number in your request.
This endpoint's content type is application/json; charset=utf-8, and you can append these parameters to the URL:
  • level: How thorough of a check to run. Set to critical, debug, or info. The default is info.
  • timeout: Specified in seconds. The default is 30.
For example, this request uses certificate authentication and fetches info status information for PE services running on port 4433: 
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; charset=utf-8" \
--request GET "https://puppet.status.example:4433/status/v1/services?level=info&timeout=60"

Response format

The server uses these response codes:
  • 200 if, and only if, all services report a status of running.
  • 503 if any service’s status is unknown or error.
  • 400 if an invalid level parameter is set (not critical, debug, or info).
A successful response contains a JSON object listing details about the services. Responses use these keys:
Key Definition
service_version Package version of the JAR file containing a given service.
service_status_version The version of the API used to report the status of the service.
detail_level The level of detail shown. One of critical, debug, or info.
state The current state of the service. One of running, error, or unknown.
status An object with the service’s status details. Usually only relevant for error and unknown states.
active_alerts An array of objects containing severity and a message about your replication from pglogical if you have replication enabled; otherwise, it's an empty array.
For example, a request about services on port 4433 (which includes the Activity service, the Classifier, and RBAC) returns a response similar to the following:
{
  "activity-service": {
    "service_version": "2019.8.0.0",
    "service_status_version": 1,
    "detail_level": "info",
    "state": "running",
    "status": {
      "db_up": true,
      "db_pool": {
        "state": "ready"
      },
      "replication": {
        "mode": "none",
        "status": "none"
      }
    },
    "active_alerts": []
  },
  "classifier-service": {
    "service_version": "2019.8.0.0",
    "service_status_version": 1,
    "detail_level": "info",
    "state": "running",
    "status": {
      "db_up": true,
      "db_pool": {
        "state": "ready"
      },
      "rbac_up": true,
      "activity_up": true,
      "replication": {
        "mode": "none",
        "status": "none"
      }
    },
    "active_alerts": []
  },
  "rbac-service": {
    "service_version": "2019.8.0.0",
    "service_status_version": 1,
    "detail_level": "info",
    "state": "running",
    "status": {
      "db_up": true,
      "db_pool": {
        "state": "ready"
      },
      "activity_up": true,
      "replication": {
        "mode": "none",
        "status": "none"
      }
    },
    "active_alerts": []
  },
  "status-service": {
    "service_version": "1.1.0",
    "service_status_version": 1,
    "detail_level": "info",
    "state": "running",
    "status": {},
    "active_alerts": []
  }
}

GET /status/v1/services/<SERVICE NAME>

Retrieves the status of one Puppet Enterprise (PE) service.

Request format

When Forming status API requests to this endpoint, your request must include a properly-formatted service name and the corresponding port. Service names and default ports are as follows:
Service Port
activity-service 4433
broker-service 8143 (primary server)

8140 (compilers)
classifier-service 4433
code-manager-service 8140
orchestrator-service 8143
puppetdb-service 8081
rbac-service 4433
server (Puppet Server) 8140
Important: If you changed a service's port to something other than the default port, you might need to change the port number in your request.
This endpoint's content type is application/json; charset=utf-8, and you can specify these parameters in your request:
  • level: How thorough of a check to run. Set to critical, debug, or info. The default is info.
  • timeout: Specified in seconds. The default is 30.
For example, this request uses certificate authentication and fetches info status information for the RBAC 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; charset=utf-8" \
--request GET "https://puppet.example.com:4433/status/v1/services/rbac-service?level=info&timeout=60"

Response format

The server uses these response codes:
  • 200 if, and only if, all services report a status of running.
  • 503 if any service’s status is unknown or error.
  • 400 if an invalid level parameter is set (not critical, debug, or info).
  • 404 if no service matching the supplied service name is found.
A successful response contains a JSON object listing details about the service using these keys:
Key Definition
service_version Package version of the JAR file containing a given service.
service_status_version The version of the API used to report the status of the service.
detail_level The level of detail shown. One of critical, debug, or info.
state The current state of the service. One of running, error, or unknown.
status An object with the service’s status details. Usually only relevant for error and unknown states.
active_alerts An array of objects containing severity and a message about your replication from pglogical if you have replication enabled; otherwise, it's an empty array.
For example, this response contains information about the RBAC service:
{
  "rbac-service": 
    {"service_version": "1.8.11-SNAPSHOT", 
     "service_status_version": 1, 
     "detail_level": "info", 
     "state": "running", 
     "status": {
                "activity_up": true, 
                "db_up": true,
                "db_pool": { "state": "ready" },
                "replication": { "mode": "none", "status": "none" }
               }, 
      "active_alerts": [] 
    }
}