0lucho0/echo-back repository overview
Echo-Back
A customizable default backend written in Go for use with the Ingress-NGINX controller.
EchoBack provides friendly HTML and JSON error responses for unmatched routes or backend failures in your Kubernetes cluster.
⚠️ This project is designed to be used as the
default-backendin the Ingress-NGINX controller configuration.
✨ Features
- 🧾 Dual-format response: HTML & JSON
- 🔍 Rich metadata in response: request headers, client IP, method, URI
- 🧩 Easy-to-customize HTML templates
- 🚀 Lightweight and high-performance Go binary
- 📊 Built-in metrics with Prometheus support
🏗️ Architecture
flowchart TD
client["Client"]
nginx_proxy["Ingress-NGINX"]
default_go["Default Backend (Go)"]
service_python["Service (Python)"]
client --> nginx_proxy
nginx_proxy -->|HTTP Request| service_python
service_python -->|HTTP Response| nginx_proxy
nginx_proxy -- http-errors --> default_go
default_go -->|HTTP Response| nginx_proxy
nginx_proxy -->|HTTP Response| client
⚙️ Environment Variables
| Variable | Description | Default |
|---|---|---|
PORT | Port the server listens on | 3000 |
TEMPLATE_HTML | Path to HTML template | templates/simple.html |
DEBUG | Enables debug mode (logs body, etc.) | true |
LOG_LEVEL | Logging level (debug, info, ...) | info |
LOG_FORMAT | Logging format (text, json) | text |
📘 API Reference
Endpoint: /
The root endpoint catches all unmatched requests and returns an HTML or JSON response based on request headers.
📥 Request Headers
| Header Name | Description | Required |
|---|---|---|
X-Request-ID | Unique identifier for tracing the request | No |
X-Client-Addr | IP address of the client | No |
X-Code | HTTP status code to return (defaults to 200) | No |
X-Service-Name | Name of the upstream service | No |
X-Service-Port | Port of the upstream service | No |
X-Ingress-Name | Name of the Ingress resource | No |
X-Namespace | Kubernetes namespace where the service resides | No |
Content-Type | Format of the request payload (e.g., application/json) | No |
Accept | Accepted response format (e.g., application/json) | No |
📤 Response
The response format is determined by the Accept or Content-Type headers.
🧾 JSON Response
Returned when Accept or Content-Type is application/json.
{
"api": {
"metadata": {
"name": "echoback",
"version": "v1.0.0",
"commit": "abc123"
},
"spec": {
"request": {
"host": "example.com",
"method": "GET",
"uri": "/",
"request_id": "12345",
"client_addr": "192.168.1.1",
"scheme": "https",
"headers": {
"User-Agent": "...",
"X-Code": "404"
},
"body": {}
},
"response": {
"status": 404,
"status_text": "Not Found",
"status_emoji": "😕",
"service_name": "my-service",
"service_port": "80",
"ingress_name": "my-ingress",
"namespace": "default"
}
}
}
}
🖼️ HTML Response
Returned when Accept or Content-Type is text/html (or not specified). A template-based HTML error page will be rendered.
📦 Example Requests
JSON Request
GET / HTTP/1.1
Host: localhost
X-Request-ID: 12345
X-Client-Addr: 192.168.1.1
Content-Type: application/json
Accept: application/json
HTML Request
GET / HTTP/1.1
Host: localhost
X-Request-ID: 12345
X-Client-Addr: 192.168.1.1
Content-Type: text/html
Accept: text/html
🚀 Deployment (Helm Chart)
To use EchoBack as your Ingress-NGINX default backend, configure your values like this:
controller:
defaultBackend:
enabled: true
image:
repository: docker.io/0lucho0/echo-back
tag: latest
Or deploy directly as a service in Kubernetes behind a catch-all ingress path.
🛠️ Build & Run Locally
make build
dist/echoback
Or run with Docker:
make docker-build
# or
docker compose up -d --build
🤝 Contributing
Pull requests and suggestions are welcome! Please open an issue first if you want to propose major changes.
📜 License
This project is licensed under the MIT License. See the LICENSE file for more details.
Tag summary
Content type
Image
Digest
sha256:9e5775c6e…
Size
4.6 MB
Last updated
over 1 year ago
docker pull 0lucho0/echo-back