Liveness and readiness - $liveness, $readiness

Description

It can be useful to check whether Firely Server is still up and running, and ready to handle requests. Either just for notification, or for automatic failover. A prominent use case is to start dependent services only after Firely Server is up and running, e.g. in a docker-compose or in a Helm chart.

Firely Server provides two endpoints, each in the form a of a FHIR custom operation, for different purposes:

  • GET <base>/$liveness

  • GET <base>/$readiness

These align - intentionally - with the use of liveness and readiness probes in Kubernetes.

The major difference is in the ability to handle requests. Some operations on Firely Server can trigger a long running process during which the server cannot reliably handle requests, see the Long running tasks plugin. If this is the case, the $liveness operation will return a 200 OK status regardless, indicating the server is up and should not be restarted (that would just delay the long running process). The $readiness operation however, would return 423 Locked in this case. If no long running processes are active, both operations will have the same output, namely 200 OK.

If you have assigned different endpoints to different FHIR versions (see here), you can also invoke it on each FHIR version. The result is always the same for all versions that are configured in the server. E.g:

GET <base-url>/$liveness
GET <base-url>/STU3/$liveness
GET <base-url>/R4/$liveness

Results

The $liveness operation may return one of these http status codes:

  1. 200 OK: Firely Server is up and running (but may still be blocked by a long running process).

  2. 402 Payment Required: The license is expired or otherwise invalid.

  3. 500 or higher: An unexpected error happened, the server is not running or not reachable (in the latter case the error originates from a component in front of Firely Server).

The $readiness operation may return one of these http status codes:

  1. 200 OK: Firely Server is up and running and ready to process requests.

  2. 423 Locked: Firely Server is busy with a long running operation and cannot process requests. This could among others be a database migration or an import of conformance resources. The response will have an OperationOutcome with additional details.

  3. 402 Payment Required: The license is expired or otherwise invalid.

  4. 500 or higher: An unexpected error happened, the server is not running or not reachable (in the latter case the error originates from a component in front of Firely Server).

Configuration

Both operations should be configured in the pipeline, see the plugin reference for $liveness and $readiness. In the default settings this is the case. Both plugins have no further configuration in the appsettings.