Archived

No description

This repository has been archived on 2025-11-11. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.

Find a file

ari 38ab3866b9 Some checks failed ci/woodpecker/push/ci Pipeline failed Details Delete .argocd/ci.yml		2025-11-11 21:54:45 +00:00
.github	add renovate	2025-09-26 13:06:13 +02:00
.woodpecker	show size properly and add fmt	2025-09-29 14:07:18 +02:00
deploy	add deployment examples	2025-09-30 21:13:39 +02:00
docs	Initial Commit	2025-09-25 03:19:57 +02:00
src	remove static file server	2025-10-01 00:08:13 +02:00
test/webroot	remove static file server	2025-10-01 00:08:13 +02:00
.dockerignore	Initial Commit	2025-09-25 03:19:57 +02:00
.gitignore	Initial Commit	2025-09-25 03:19:57 +02:00
Cargo.lock	remove static file server	2025-10-01 00:08:13 +02:00
Cargo.toml	Initial Commit	2025-09-25 03:19:57 +02:00
Dockerfile	use caching in docker builds	2025-09-26 19:01:06 +02:00
Justfile	show size properly and add fmt	2025-09-29 14:07:18 +02:00
README.md	remove redundant header from readme	2025-10-01 19:06:06 +02:00

README.md

squawkend - A multi-domain ingress-nginx error backend

Squawkend is a little app you can run in your Kubernetes cluster to serve custom HTTP error messages on a per-domain basis across multiple sites/services! Essentially, it allows you to replace the boring, drab ingress-nginx error pages...

with something much more fun and whimsical on a per-site basis!

(Art by SpeccyChicken)

Squawkend is implemented as an alternative "default backend" for ingress-nginx. This allows it to slot right into existing setups and means you only need to deploy it once per cluster, instead of per app! While this project is mainly intended as a bit of fun, I did build it with robustness in mind and I hope that you will find it both useful and enjoyable!

Setup

First, you need to provide some custom error page templates and any other files you want to serve. For each domain you can define:

One default.html default error page template
Per-statuscode templates named after the HTTP status (404.html)
Additional static files such as images

Squawkend expects a directory structure like this:

your.domain.name/
  default.html <-- your default error page template
  404.html <-- optional statuscode specific template(s)
  image.png <-- other assets go here
another.domain/
  default.html
default/ <-- fallback when no domain-specific directory exists
  default.html
  403.html

Note that the default directory is optional, Squawkend also has a fallback template builtin. Error page templates are selected in the following order:

(highest) domain-specific and status-code specific (your.domain.name/404.html)
domain-specific default (your.domain.name/default.html)
status-code specific fallback (default/404.html)
default fallback (default/default.html)
(lowest) internal fallback

Creating templates

Squawkend uses Tera to template out your status page files, allowing you to use a single template for all status codes! A simple status page might look something like below:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>{{ reason }}</title>
</head>
<body style="background-color:#1c1512; color:white">
    <center>
        <h1>{{ code }} {{ reason }}</h1>
        <img width="256px" src="data:image/png;base64,<yourbase64encodedpnghere>">
    </center>
</body>
</html>

The following template variables are available:

code: Numeric HTTP status code (e.g. 400)
reason: HTTP status reason (e.g. Unauthorized)
host: HTTP Host that the error originates from (e.g. my.domain.name)
backend_headers: Backend headers sent by ingress-nginx. See here
- code, accept, original_url, namespace, ingress_name, service_name, service_port, request_id

Installation

To use squawkend, you must install the Squawkend app itself and provide it with your templates. Below are some options for how to do this, you can also check out the examples in deploy. All examples use a Deployment and Service to run Squawkend itself (see deploy).

⚠️ Squawkend must be installed into the same namespace as ingress-nginx. Please adjust the manifests according to your ingress-nginx namespace. ⚠️

ConfigMap + EmptyDir

As long as your template are pretty small (<500 kB compressed), you can store them in a ConfigMap and directly mount them into the deployment. Example steps:

Create an archive of your webroot template directory: tar caf webroot.tar.xz --directory path/to/your/webroot .
Upload the archive as a ConfigMap: kubectl create configmap -n <ingress-nginx-namespace> squawkend-webroot --from-file webroot.tar.xz
Use the configMap deployment example to deploy Squawkend: cd deploy/configMap && kubectl apply -f .
- The deployment features an initContainer to unpack the archive before the squawkend container starts
- Ensure that the deployment/service namespace matches the ingress-nginx namespace

PVC Volume

If you have a larger webroot you can put your data onto a PersistentVolume and mount it through a PersistentVolumeClaim.

Create a PV containing your webroot, as well as a PVC. This it outside the scope of this README
- Ensure that the PVC namespace matches the Squawkend namespace == ingress-nginx namespace
Use the pv deployment example, adjusting the claimName to match your PVC, then deploy it: cd deploy/pv && kubectl apply -f .
- Once again, check that the namespaces match

Custom Container Image

Modifying the Squawkend container image is another way to store and deploy your templates to your cluster. For this you can use a very simple Dockerfile + Manifests inside the custom-image example.