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, 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. A check that returns a value has run to its end before its timeout starts, so the timeout does not bound it: it blocks the event loop while it runs, as any code that blocks does, and the timeouts of its own client bound it, as connect_timeout of a database, and a library that refuses a running loop of asyncio, as the ORM of Django, runs in Pyjo.IOLoop.blocking(). 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. So an endpoint takes the path from the routes of the application, and from an application that Pyjoyment.Plugin.Mount mounts: one with a /healthz of its own, which its monitors request, keeps it with healthz=None.

A server whose workers serve one connection at a time, as prefork -c 1 for an application that blocks, keeps a probe in the backlog while every worker is busy, so that a liveness probe of HTTP restarts a container that is only busy. Its liveness probe connects to the port, as tcpSocket of Kubernetes, which the kernel accepts into the backlog, as Pyjoyment.Command.Author.generate.kubernetes makes it with --liveness-probe, and /readyz stays its readiness probe.

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 of a promise, a coroutine or another
awaitable 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.