Operations on bouine

Lifecycle

Mon, 01 Jan 0001 00:00:00 +0000

Starting bouine

bouine serve --config /etc/bouine/config.yaml --log-format json

On Kubernetes the StatefulSet container runs this command via the Helm chart (see deploy/helm/bouine/templates/statefulset.yaml). The --log-format json flag ensures structured logging for aggregation.

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

All write endpoints require Authorization: Bearer <token>. The token is resolved in priority order:

BOUINE_ADMIN_TOKEN environment variable (recommended for Kubernetes / Vault injection)
admin.token in the config file
Auto-generated random token (logged as WARN at startup)

Environment variable

Set BOUINE_ADMIN_TOKEN to inject the token without baking it into the config ConfigMap:

Cache invalidation

Mon, 01 Jan 0001 00:00:00 +0000

Purge (exact URL)

# CLI
bouine purge https://example.com/products/123 --token <token>

# API
curl -X POST http://127.0.0.1:9000/v1/purge \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{"url":"https://example.com/products/123"}'

In a cluster, the purge is forwarded to all live peers via HTTP fan-out (in strong mode) or gossiped via the memberlist broadcast queue (in eventual mode).

Cluster consistency modes

Mon, 01 Jan 0001 00:00:00 +0000

Verify your mode

# Prometheus metric: always 1 with the mode label.
curl -s http://127.0.0.1:9000/metrics | grep bouine_cluster_mode_info

# Admin API: /v1/cluster/peers returns all members in every mode.
curl -s http://127.0.0.1:9000/v1/cluster/peers \
 -H "Authorization: Bearer ${BOUINE_ADMIN_TOKEN}"

# CLI
bouine cluster peers --server 127.0.0.1:9000 --token "${BOUINE_ADMIN_TOKEN}"

Expected: every node reports the same mode label. If they disagree, the cluster has a configuration drift — every pod must use the same mode.

Monitoring

Mon, 01 Jan 0001 00:00:00 +0000

Prometheus metrics

All metrics are exposed at GET /metrics on the admin port (default :9000) in Prometheus text format. No authentication is required to scrape this endpoint.

Traffic (RED)

Metric	Labels	Description
`bouine_requests_total`	`method`, `status`, `cache_result`, `source`, `route`	Total requests processed. This is the primary RED counter.
`bouine_request_duration_seconds`	`method`, `status`, `cache_result`, `source`, `route`	Request latency histogram. Includes native histogram buckets for higher-resolution percentiles. Carries Prometheus exemplars linking high-latency observations to a trace ID when tracing is enabled.
`bouine_response_bytes_total`	`method`, `cache_result`, `source`, `route`	Total bytes written in responses.

cache_result values: HIT, MISS, STALE, REVALIDATED, BYPASS.

Dashboard

Mon, 01 Jan 0001 00:00:00 +0000

The operator dashboard is embedded directly in the admin server — no extra process, no Node toolchain. Open it at:

http://<admin-addr>/dashboard/

Default on localhost: http://localhost:9000/dashboard/

Logging in

The dashboard uses a session cookie derived from the admin bearer token.

Kubernetes operations

Mon, 01 Jan 0001 00:00:00 +0000

Scaling

kubectl scale statefulset/bouine -n <namespace> --replicas=3

Gossip auto-discovers peers via the headless Service DNS. New pods join the cluster within 60s.

Rolling update (zero 5xx)

kubectl rollout restart statefulset/bouine -n <namespace>
kubectl rollout status statefulset/bouine -n <namespace> --timeout=180s

StatefulSet rolls one pod at a time (reverse ordinal). Each pod must pass the readiness probe (GET /readyz) before the next is replaced.

Observability guide

Mon, 01 Jan 0001 00:00:00 +0000

This guide walks you through deploying a complete observability stack for bouine using the Grafana LGTM components (Loki, Grafana, Tempo, Mimir/Prometheus) and Grafana Alloy as the unified collection agent.

Architecture

 monitoring namespace
 ┌──────────────────────────────────────────────────┐
 │ Grafana ──queries──▶ Prometheus (metrics) │
 │ Loki (logs) │
 │ Tempo (traces) │
 │ ▲ ▲ ▲ │
 │ Grafana Alloy (single agent) │
 └─────────────────────│────│────│──────────────────┘
 scrape :9000│ │OTLP :4318
 tail pod logs (k8s API) │
 │
 bouine pods

Grafana Alloy replaces three separate agents:

Cloudflare CDN propagation

Mon, 01 Jan 0001 00:00:00 +0000

Overview

When bouine sits behind Cloudflare (or any scenario where Cloudflare caches responses delivered through bouine), invalidating a URL in bouine is not enough — the entry may also be cached at the Cloudflare edge.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Quick reference

Symptom	Severity	Jump to
Pods don’t discover each other	Critical	Cluster discovery
Rolling restart produces 503/502	High	Rolling restart
Purge doesn’t propagate	High	Purge propagation
HIT p99 spikes to 50–100 ms under load	High	GC stop-the-world pauses
`X-Cache` always MISS	Medium	Cache misses
Stale reads on one node	Medium	Stale reads
Low hit rate in eventual mode	Low	Low hit rate
Docker build slow on Apple Silicon	Low	Docker build

Cluster discovery

Pods do not discover each other

Check the headless Service: