Pyjoyment.Plugin.Health - Liveness and readiness plugin

# Pyjoyment
app.plugin('Health')

# Pyjoyment.Lite
plugin('Health')

# The checks of readiness, of a function, a coroutine function or one that returns a promise
app.plugin('Health', checks={'db': lambda c: db.ping(), 'queue': queue_ready_p}, timeout=2)

# A check that another plugin adds
app.health.check('cache', lambda c: cache.connected)

Pyjoyment.Plugin.Health answers the probes of containers and orchestrators, as the liveness, readiness and startup probes of Kubernetes, the probes of Cloud Run, the health checks of load balancers and the HEALTHCHECK of Docker, with the endpoints of Kubernetes itself.

GET /livez

Liveness: 200 OK with ok while the server answers, as a server whose event loop is blocked does not answer. It has no checks of the application, as an orchestrator restarts a container whose liveness fails, and a database that is down does not get up with it.

GET /healthz

The same as /livez, under the name of the probes of Docker and of load balancers.

GET /readyz

Readiness: 200 OK with ok once the checks of the application pass, and 503 Service Unavailable with the list of the checks while one of them fails, so that an orchestrator or a load balancer sends the requests to another instance. The check shutdown fails from the moment that the server stops gracefully, also during its shutdown_delay, as Pyjo.IOLoop.Pyjo_IOLoop.is_stopping of the event loop of the thread, Pyjo.IOLoop.singleton, which is the one of every server of Pyjoyment, and its workers, tells: a client whose connection is kept alive gets 503 with its last response.

The checks run at the same time, each with a timeout, and a check passes unless it raises an exception, returns False, or returns a promise, a coroutine or another awaitable that is rejected, is fulfilled with False, or does not settle within its timeout. The reason of a failure goes to the log, as the warn message Health check "db" failed: ..., not to the response, which withholds it.

A query of verbose lists the checks on success too, exclude leaves a check out, as many times as there are checks to leave out, and a check of its own is under the name of the endpoint, as /readyz/db, as Kubernetes has them.

$ curl 'http://127.0.0.1:3000/readyz?verbose'
[+]shutdown ok
[+]db ok
readyz check passed

$ curl 'http://127.0.0.1:3000/readyz?exclude=db'
ok

$ curl -i 'http://127.0.0.1:3000/readyz/db'
HTTP/1.1 503 Service Unavailable
...
[-]db failed: reason withheld
readyz check failed

The endpoints are answered in a hook of around_dispatch, before the hooks of before_dispatch, the static files and the routes, so that a probe is cheap, is not logged but on the level trace, and is answered also where a hook rejects it, as Pyjoyment.Plugin.AllowedHosts would reject the Host of the address of a pod, which a probe of Kubernetes sends. A hook of around_dispatch that the application registers before the plugin wraps the probes too.

See Pyjoyment.Plugins for a list of plugins that are available by default.

Options

Pyjoyment.Plugin.Health supports the following options.

checks

app.plugin('Health', checks={'db': lambda c: db.ping()})

The checks of readiness, the names and the functions that take the
controller of the probe, defaults to none.

healthz

app.plugin('Health', healthz='/health')
app.plugin('Health', healthz=None)

The path of the alias of liveness, defaults to ``/healthz``, ``None``
leaves it out.

livez

app.plugin('Health', livez='/-/live')

The path of liveness, defaults to ``/livez``, ``None`` leaves it out.

readyz

app.plugin('Health', readyz='/-/ready')

The path of readiness, defaults to ``/readyz``, ``None`` leaves it out.

timeout

app.plugin('Health', timeout=0.5)

The time in seconds that a check may take, defaults to ``1``, the
timeout of a probe of Kubernetes.

Helpers

Pyjoyment.Plugin.Health implements the following helpers.

health.check

app.health.check('db', lambda c: db.ping())
app.health.check('search', search_ready_p, timeout=5)

Add a check of readiness, with a timeout of its own, or replace the
check of the name, as a plugin that connects to a service does.

health.path

path = c.health.path('livez')

The path of an endpoint, ``livez``, ``readyz`` or ``healthz``, or
``None`` for one that is left out, as
:mod:`Pyjoyment.Command.Author.generate.dockerfile` takes it for the
``HEALTHCHECK`` of the image.

See also

Pyjoyment, https://mojolicious.org.

It has no counterpart in Mojolicious.

Classes

class Pyjoyment.Plugin.Health.Pyjoyment_Plugin_Health[source]

Pyjoyment.Plugin.Health inherits all methods from Pyjoyment.Plugin and implements the following new ones.

register(app: Pyjoyment_App, conf: dict[str, Any] | None = None) → None[source]
plugin.register(Pyjoyment.new())
plugin.register(Pyjoyment.new(), {'checks': {'db': lambda c: True}})

Register the hook and the helpers in Pyjoyment application.