Web application that show informations of the pod
6.3K
A tiny web application written in Go to learn and demonstrate Kubernetes concepts: pods, services, load balancing, probes, scaling, rolling updates, secrets and observability (metrics, logs and traces).
Each response shows which pod answered the request (hostname, network interfaces and IP addresses, OS and architecture), so when you refresh the page behind a Kubernetes Service you can watch the load balancing happen.
Source code, Helm chart and documentation: https://gitlab.com/aeciopires/kube-pires

| Item | Value |
|---|---|
| Source code | https://gitlab.com/aeciopires/kube-pires |
| Changelog | app/CHANGELOG.md |
| Helm chart | helm-chart/ (Helm 4) |
| Issues | https://gitlab.com/aeciopires/kube-pires/-/issues |
| Maintainer | Aécio dos Santos Pires |
| License | GPL-3.0 |
Multi-architecture image: linux/amd64, linux/arm64, linux/arm/v7 and linux/arm/v6 (runs on servers, Apple
Silicon, Raspberry Pi and other ARM boards). Docker selects the right variant automatically.
/): hostname (pod name), all network interfaces and IP addresses, OS/architecture,
application version and the trace ID of the request./livez (liveness) and /readyz (readiness, returns 503 while shutting down).
/health is kept for compatibility.SIGTERM/SIGINT, with an optional SHUTDOWN_DELAY so load balancers stop sending
traffic before the process exits — great for demonstrating zero-downtime rolling updates./metrics (request count, duration histogram, request/response sizes, URI and status).log/slog), one line per request, including trace_id and span_id for log/trace
correlation. Text format available with LOG_FORMAT=text.OTEL_EXPORTER_OTLP_ENDPOINT./env) — handy to show ConfigMaps and Secrets injected into a pod, with a
warning that the page can show secrets.FROM scratch with a single static binary (templates, CSS and favicon are
embedded), ~28 MB, runs as non-root UID/GID 65532, scanned with Trivy.The image at the top shows the home page in dark mode (default). The same page in light mode — the hostname is the name of the pod that answered the request:

Page /env, with the variables injected by Kubernetes (Services) and by a Secret (MY_SECRET_LICENSE_KEY):

On a phone:

docker pull aeciopires/kube-pires:latest
docker run -d --name kube-pires -p 3000:3000 aeciopires/kube-pires:latest
Open http://localhost:3000 in your browser (use the Light/Dark selector in the top bar to change the theme), or:
curl http://localhost:3000/health
curl http://localhost:3000/metrics
docker logs -f kube-pires
Changing the configuration, for example text logs at debug level:
docker run -d --name kube-pires -p 3000:3000 \
-e LOG_LEVEL=debug \
-e LOG_FORMAT=text \
aeciopires/kube-pires:latest
Sending traces to an OpenTelemetry collector (Jaeger, Tempo, Grafana Alloy, OpenTelemetry Collector...):
docker run -d --name kube-pires -p 3000:3000 \
-e OTEL_SERVICE_NAME=kube-pires \
-e OTEL_EXPORTER_OTLP_ENDPOINT=http://my-collector:4318 \
aeciopires/kube-pires:latest
Stop and remove it:
docker rm -f kube-pires
services:
kube-pires:
image: aeciopires/kube-pires:latest
container_name: kube-pires
ports:
- "3000:3000"
environment:
LOG_LEVEL: info
LOG_FORMAT: json
restart: always
docker compose up -d
Quick test with kubectl, scaling to 3 replicas to see the load balancing:
kubectl create deployment kube-pires --image=aeciopires/kube-pires:latest --replicas=3 --port=3000
kubectl expose deployment kube-pires --port=80 --target-port=3000
kubectl port-forward service/kube-pires 8080:80
Open http://localhost:8080. Note that kubectl port-forward always connects to a single pod; use an Ingress or a
NodePort/LoadBalancer Service to see different pods answering on each refresh.
For a production-like deployment (probes, resources, HPA, PDB, Ingress, ServiceMonitor, tracing and Grafana dashboards), use the Helm chart (Helm 4 only, Kubernetes >= 1.23):
git clone https://gitlab.com/aeciopires/kube-pires.git
cd kube-pires
helm upgrade --install kube-pires helm-chart/ -n kube-pires --create-namespace --wait
See the chart README for all the parameters.
| Endpoint | Description |
|---|---|
/ | Hostname, network interfaces and IP addresses, OS and architecture, version and trace ID |
/livez | Liveness: 200 while the process is running |
/readyz | Readiness: 200 when ready, 503 while shutting down |
/health | Original health check, always 200 (kept for compatibility) |
/env | Environment variables of the process (sensitive) |
/metrics | Metrics in the Prometheus format |
/css | Stylesheet of the pages |
/favicon.ico | Icon of the pages |
| Variable | Default | Description |
|---|---|---|
PORT | 3000 | Port where the web server listens |
ADDRESS | 0.0.0.0 | Address where the web server listens |
PROTOCOL | http | Protocol shown in the startup log message |
GIN_MODE | release | Gin framework mode: debug, release or test |
LOG_LEVEL | info | Minimum log level: debug, info, warn or error |
LOG_FORMAT | json | Log format: json or text |
TRUSTED_PROXIES | (empty) | Comma-separated IPs/CIDRs of reverse proxies trusted for X-Forwarded-For |
SHUTDOWN_DELAY | 0s | After SIGTERM, time /readyz answers 503 while still serving (Go duration, e.g. 10s) |
OTEL_EXPORTER_OTLP_ENDPOINT | (unset) | OTLP/HTTP endpoint; tracing is enabled only when set |
OTEL_SERVICE_NAME | kube-pires | Service name in the traces |
OTEL_TRACES_SAMPLER / OTEL_TRACES_SAMPLER_ARG | (SDK default) | Standard OpenTelemetry sampling settings |
Invalid values of PORT, LOG_LEVEL, LOG_FORMAT and SHUTDOWN_DELAY stop the application with a clear message.
| Pillar | How kube-pires produces it |
|---|---|
| Metrics | /metrics endpoint in the Prometheus format |
| Logs | One JSON line per request on stdout, with trace_id and span_id |
| Traces | OpenTelemetry over OTLP/HTTP, one span per request plus internal spans |
The repository includes a ready-to-use Docker Compose stack with Grafana, Prometheus, Loki, Tempo, Jaeger and Grafana Alloy, plus four dashboards (Overview, Metrics, Logs, Traces):
git clone https://gitlab.com/aeciopires/kube-pires.git
cd kube-pires
make observability-up # Grafana on http://localhost:3001, kube-pires on http://localhost:3000

| Item | Value (measured) |
|---|---|
| Container port | 3000/TCP |
| Memory | ~5 MiB idle, ~21 MiB with tracing enabled, < 32 MiB under load |
| CPU | ~0 idle; 0.2 core answered ~1,470 requests/s |
| Image size | ~28 MB |
65532:65532) and contains only the application binary — no shell, no
package manager./env shows all environment variables, including Secret values. It exists for learning purposes: do not
expose it publicly in real environments.X-Forwarded-For is trusted only from the proxies listed in TRUSTED_PROXIES.New to programming, Kubernetes or observability? The repository has a beginner-friendly reading path:
Contributions are welcome — see CONTRIBUTING.md.
GPL-3.0 © 2026 Aécio dos Santos Pires
Content type
Image
Digest
sha256:12659e07c…
Size
10 MB
Last updated
2 days ago
docker pull aeciopires/kube-pires