PingDirectory

The availability state servlet

There are cases in which you want to obtain basic information about the state of the server over HTTP, or ideally, HTTPS.

These might include:

  • When server HTTP endpoints are fronted by a load balancer capable of issuing and interpreting the results of HTTP requests for health-checking purposes.

  • When using an orchestration framework such as Kubernetes, you can assess the current state of the server to determine if the instance is in a state that is ready to be used or if it has encountered an issue that has caused it to become degraded or unavailable. In this case,you can call the availability servlet in a liveness or readiness probe.

To assist with this, the PingDirectory server includes an availability state HTTP servlet that can be used to determine whether the server considers itself to be available, degraded, or unavailable. It is accessed using the GET, POST, or HEAD methods, and it returns a configurable status code and optional JSON-encoded response body that can be used to determine the server’s self-assessed health state.

There are two instances of this servlet configured by default:

  • One that uses a path of /available-state that returns an HTTP status code of 200 (OK) if the server considers itself available or an HTTP status code of 503 (Service Unavailable) if the server considers itself degraded or unavailable

  • One that uses a path of /available-or-degraded-state that returns an HTTP status code of 200 if the server considers itself available or degraded or an HTTP status code of 503 if the server considers itself unavailable

The server’s assessment of its health state is based on the presence of any unavailable or degraded alert types that are active in the server. If the server currently has one or more unavailable alert types, then it considers itself unavailable. If the server does not have any unavailable alert types but has one or more degraded alert types, then it considers itself degraded. If the server does not have any unavailable or degraded alert types, then it considers itself available.