Configuration

bouine is configured via a YAML file passed with --config. Environment variable interpolation is supported: ${VAR} is replaced with the value of VAR, and ${VAR:-default} provides a fallback. $$ escapes to a literal $.

Pages in this section

• Cache policy — TTL selection, stale serving, negative caching, jitter, refresh-before-expiry, and cache keys.
• Static file serving — serve files from a local directory instead of an upstream pool.
• Storage tiers — hot and warm tiers, eviction, sizing guidelines.
• TLS — certificates, SNI, and automatic reload.
• Clustering — consistency modes, gossip, peer fetch, mTLS, invalidation.
• Experimental features — opt-in features like the H1 fast path.
• Helm chart reference — all values.yaml keys with defaults.

Minimal working config

listen:
  http: ":8080"
  admin: ":9000"

storage:
  hot_max_bytes: 256MiB

upstream_pools:
  - name: app
    targets: ["app.default.svc:8080"]

routes:
  - match: { path_prefix: / }
    pool: app
    cache:
      ttl_default: 60s

Full example

listen:
  http: ":80"
  https: ":443"
  admin: ":9000"
  cluster: ":8443"

tls:
  certs:
    - cert_file: /etc/bouine/tls/cert.pem
      key_file: /etc/bouine/tls/key.pem
      sni: ["example.com", "*.example.com"]
  min_version: "1.2"

storage:
  hot_max_bytes: 2GiB
  warm_dir: /var/lib/bouine
  warm_max_bytes: 50GiB

cluster:
  join:
    - "bouine-0.bouine-headless.ns.svc.cluster.local:8443"
    - "bouine-1.bouine-headless.ns.svc.cluster.local:8443"
    - "bouine-2.bouine-headless.ns.svc.cluster.local:8443"
  hop_limit: 2

upstream_pools:
  - name: api
    targets: [api.default.svc:8080]
    tls:
      enabled: false
    health:
      active:
        path: /healthz
        interval: 5s
        timeout: 1s
        unhealthy_threshold: 3
      passive:
        consecutive_5xx: 5
    connect:
      timeout: 10s
      keep_alive: 15s

routes:
  - match: { host: "api.example.com", path_prefix: /v1/ }
    pool: api
    cache:
      ttl_default: 60s
      stale_while_revalidate: 30s
      stale_if_error: 300s
      negative_ttl: 5s
      jitter_percent: 10
      refresh_before_expiry: true
      refresh_margin_percent: 20
      refresh_timeout: 5s
      refresh_concurrency: 16
      refresh_min_hits: 3
      refresh_persist_cycles: 2
      refresh_min_score: 1048576
      refresh_max_rps: 100
      refresh_reactive_first: true
      key:
        include_headers:
          - Accept-Language
        exclude_headers:
          - x-request-id
          - x-trace-id
          - x-forwarded-for

Field reference

listen

storage

cluster

routes[]

Route matching uses host, path_prefix, and optionally methods. Routes are matched in declaration order; the first match wins. Regex-based path matching is not supported in routes — use path_regex in ban predicates for invalidation.

A route must specify exactly one of pool or static.root. The former proxies to an upstream pool; the latter serves files from a local directory. See Static file serving.

routes[].request

routes[].cache

routes[].cache.key

upstream_pools[].connect

Health checks

Active health probes the upstream periodically. Passive ejects after consecutive failures.

health:
  active:
    path: /healthz
    method: GET          # default
    interval: 5s
    timeout: 1s
    healthy_threshold: 1
    unhealthy_threshold: 3
    expected_status_codes: [200]
  passive:
    consecutive_5xx: 5
    eject_for: 30s

admin

tracing

Configure OpenTelemetry span export. Leave endpoint empty (default) to disable tracing.

cloudflare

Optional Cloudflare Cache API propagation. See Cloudflare CDN propagation for full details and Kubernetes secret wiring.

experimental

Opt-in features that are not yet stable. All fields default to off. See Experimental features.

Top-level fields

Hedged fetch

When hedge_timeout is set on an upstream pool, bouine fires a duplicate request to the origin after the specified duration if the first request hasn’t responded. The first response to arrive wins; the other is discarded.

upstream_pools:
  - name: api
    targets: [api.default.svc:8080]
    connect:
      hedge_timeout: 50ms

Use hedging when your origin has occasional high-latency outliers (p99 » p50). It trades a small amount of extra origin load for significantly better tail latency. Do not use hedging for non-idempotent requests or when origin load is already near capacity.

Size units

All byte-size fields (hot_max_bytes, warm_max_bytes) accept any of these suffixes (case-insensitive):

Recommendation: Use IEC binary units (MiB, GiB) for clarity. The Helm chart defaults use GiB.

Config updates

bouine does not support live config reload. All config changes require a process restart. On Kubernetes, use a rolling restart:

kubectl rollout restart statefulset/bouine

For TLS certificate rotation, restart the process or use Kubernetes rolling restarts with cert-manager.