HUB
Sign inSign up

aeciopires/kube-pires

By aeciopires

•Updated 2 days ago

Web application that show informations of the pod

Image
1

6.3K

aeciopires/kube-pires repository overview

⁠kube-pires

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⁠

Home page of kube-pires in dark mode

⁠Table of contents

⁠Quick reference

ItemValue
Source codehttps://gitlab.com/aeciopires/kube-pires⁠
Changelogapp/CHANGELOG.md⁠
Helm charthelm-chart/⁠ (Helm 4)
Issueshttps://gitlab.com/aeciopires/kube-pires/-/issues⁠
MaintainerAécio dos Santos Pires
LicenseGPL-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.

⁠Features

  • Pod information page (/): hostname (pod name), all network interfaces and IP addresses, OS/architecture, application version and the trace ID of the request.
  • Modern web interface following Material Design 3⁠: dark mode by default and a light/dark selector in the top bar (the choice is saved in the browser), responsive layout for phones and tablets. No JavaScript framework: icons and styles are embedded in the binary.
  • Kubernetes-ready probes: /livez (liveness) and /readyz (readiness, returns 503 while shutting down). /health is kept for compatibility.
  • Graceful shutdown on SIGTERM/SIGINT, with an optional SHUTDOWN_DELAY so load balancers stop sending traffic before the process exits — great for demonstrating zero-downtime rolling updates.
  • Prometheus metrics at /metrics (request count, duration histogram, request/response sizes, URI and status).
  • Structured JSON logs (log/slog), one line per request, including trace_id and span_id for log/trace correlation. Text format available with LOG_FORMAT=text.
  • OpenTelemetry traces exported over OTLP/HTTP, enabled simply by setting OTEL_EXPORTER_OTLP_ENDPOINT.
  • Environment variable viewer (/env) — handy to show ConfigMaps and Secrets injected into a pod, with a warning that the page can show secrets.
  • Minimal and secure image: built 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.
  • Lightweight: ~5 MiB of memory when idle; 0.2 CPU core served ~1,470 requests/s in the benchmark.
  • Companion Helm chart with HPA, PDB, Ingress (nginx, AWS ALB, GCE), ServiceMonitor, Grafana dashboards and Pod Security Standards "restricted" defaults.

⁠Screenshots

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:

Home page of kube-pires in light mode

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

Page /env of kube-pires

On a phone:

Home page of kube-pires on a phone

⁠How to use this image

⁠Pull the image
docker pull aeciopires/kube-pires:latest
⁠Run with Docker
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
⁠Run with Docker Compose
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
⁠Run on Kubernetes

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.

⁠Endpoints

EndpointDescription
/Hostname, network interfaces and IP addresses, OS and architecture, version and trace ID
/livezLiveness: 200 while the process is running
/readyzReadiness: 200 when ready, 503 while shutting down
/healthOriginal health check, always 200 (kept for compatibility)
/envEnvironment variables of the process (sensitive)
/metricsMetrics in the Prometheus format
/cssStylesheet of the pages
/favicon.icoIcon of the pages

⁠Environment variables

VariableDefaultDescription
PORT3000Port where the web server listens
ADDRESS0.0.0.0Address where the web server listens
PROTOCOLhttpProtocol shown in the startup log message
GIN_MODEreleaseGin framework mode: debug, release or test
LOG_LEVELinfoMinimum log level: debug, info, warn or error
LOG_FORMATjsonLog format: json or text
TRUSTED_PROXIES(empty)Comma-separated IPs/CIDRs of reverse proxies trusted for X-Forwarded-For
SHUTDOWN_DELAY0sAfter 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_NAMEkube-piresService 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.

⁠Observability

PillarHow kube-pires produces it
Metrics/metrics endpoint in the Prometheus format
LogsOne JSON line per request on stdout, with trace_id and span_id
TracesOpenTelemetry 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

Grafana dashboard kube-pires / Overview

⁠Resource usage

ItemValue (measured)
Container port3000/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

⁠Security notes

  • The image runs as a non-root user (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.

⁠Documentation

New to programming, Kubernetes or observability? The repository has a beginner-friendly reading path:

Contributions are welcome — see CONTRIBUTING.md⁠.

⁠License

GPL-3.0⁠ © 2026 Aécio dos Santos Pires

Tag summary

Content type

Image

Digest

sha256:12659e07c…

Size

10 MB

Last updated

2 days ago

docker pull aeciopires/kube-pires