README.md

Flask-Healthz

Define endpoints in your Flask application that Kubernetes can use as liveness and readiness probes.

Setting it up

Blueprint

Register the blueprint on your Flask application:

from flask import Flask
from flask_healthz import healthz

app = Flask(__name__)
app.register_blueprint(healthz, url_prefix="/healthz")

Define the functions you want to use to check health. To signal an error, raise flask_healthz.HealthError.

from flask_healthz import HealthError

def liveness():
    pass

def readiness():
    try:
        connect_database()
    except Exception:
        raise HealthError("Can't connect to the database")

Now point to those functions in the Flask configuration:

HEALTHZ = {
    "live": "yourapp.checks.liveness",
    "ready": "yourapp.checks.readiness",
}

It is possible to directly set callables in the configuration, so you could write something like:

HEALTHZ = {
    "live": lambda: None,
}

Check that the endpoints actually work:

$ curl http://localhost/yourapp/healthz/live
{"status": 200, "title": "OK"}
$ curl http://localhost/yourapp/healthz/ready
{"status": 200, "title": "OK"}

Now your can configure Kubernetes or OpenShift to check for those endpoints.

Extension

You can also use the provided Flask extension to register the healthz blueprint:

from flask import Flask
from flask_healthz import Healthz

app = Flask(__name__)
Healthz(app)

The rest of the configuration is identical.

The extension has an additional option, no_log, that can disable logging of the HTTP requests handled by your healthz endpoints, to avoid cluttering your web log files with automated requests. At the moment, only the gunicorn web server is supported.

Healthz(app, no_log=True)

Examples

Here's an example of how you could use flask-healthz in OpenShift's deploymentconfig:

kind: DeploymentConfig
spec:
  [...]
  template:
    [...]
    spec:
      containers:
      - name: yourapp
        [...]
        livenessProbe:
          httpGet:
            path: /healthz/live
            port: 8080
          initialDelaySeconds: 5
          timeoutSeconds: 1
        readinessProbe:
          httpGet:
            path: /healthz/ready
            port: 8080
          initialDelaySeconds: 5
          timeoutSeconds: 1

Some projects that have setup flask-healthz:

• Noggin: fedora-infra/noggin#287
• FASJSON: fedora-infra/fasjson#81

License

Copyright 2020-2021 Red Hat

Flask-Healthz is licensed under the same license as Flask itself: BSD 3-clause.