Kromgo

docker run -d \
  -e KROMGO_PROMETHEUS_URL=http://prometheus:9090 \
  -v /path/to/config.yaml:/config/config.yaml \
  -p 8080:8080 \
  ghcr.io/home-operations/kromgo:latest

<img src="http://localhost:8080/badges/node_cpu_usage" />

services:
  kromgo:
    image: ghcr.io/home-operations/kromgo:latest
    environment:
      KROMGO_PROMETHEUS_URL: http://prometheus:9090
    volumes:
      - ./config.yaml:/config/config.yaml:ro
    ports:
      - "8080:8080"

helm install kromgo oci://ghcr.io/home-operations/charts/kromgo \
  --namespace kromgo --create-namespace \
  --set config.prometheus='http://prometheus-operated.monitoring.svc.cluster.local:9090'

The config value is rendered verbatim into a ConfigMap mounted at /config/config.yaml, so the config schema below maps directly onto it. Notable values (see charts/kromgo/values.yaml):

| Value | Purpose | | ------------------------------------------ | ----------------------------------------------------------------------------- | | config.prometheus | Prometheus URL kromgo queries | | config.badges / config.graphs | the endpoint definitions (same schema as the config file) | | existingConfigMap | mount a ConfigMap you manage elsewhere instead of rendering config | | secret.prometheusUrl / .existingSecret | inject KROMGO_PROMETHEUS_URL from a Secret when the URL carries credentials | | ingress.enabled | expose the app via an Ingress | | httpRoute.enabled | expose the app via a Gateway API HTTPRoute (set parentRefs + hostnames) | | monitoring.serviceMonitor.enabled | scrape /metrics on the metrics port (Prometheus Operator) |

Every value is documented in the chart's generated README, charts/kromgo/README.md, built from values.yaml — which also ships a values.schema.json for editor autocompletion and helm install-time validation.

Configuration

kromgo reads its endpoint definitions from /config/config.yaml inside the container. Mount your config file there (or pass -config /path/to/config.yaml).

Minimal example:

badges:
  - id: node_cpu_usage
    query: "round(cluster:node_cpu:ratio_rate5m * 100, 0.1)"
    valueExpr: string(result) + "%"

A JSON Schema for editor validation is published at config.schema.json; point your editor's YAML language server at it for inline completion and validation.

Environment variables

| Variable | Required | Default | Description | | ----------------------------- | -------- | ------- | -------------------------------------------- | | KROMGO_PROMETHEUS_URL | yes | — | URL of your Prometheus instance | | KROMGO_SERVER_HOST | no | _(all)_ | Bind host; empty = all families (dual-stack) | | KROMGO_SERVER_PORT | no | 8080 | Port for the main server | | KROMGO_METRICS_HOST | no | _(all)_ | Bind host for the metrics listener | | KROMGO_METRICS_ENABLED | no | true | Serve Prometheus /metrics; off ⇒ no listener | | KROMGO_METRICS_PORT | no | 8081 | Metrics listen port (/metrics only) | | KROMGO_SERVER_LOGGING | no | false | Enable HTTP request access logging | | KROMGO_SERVER_READ_TIMEOUT | no | — | HTTP read timeout (e.g. 5s) | | KROMGO_SERVER_WRITE_TIMEOUT | no | — | HTTP write timeout (e.g. 10s) | | KROMGO_QUERY_TIMEOUT | no | 30s | Timeout applied to each Prometheus query | | KROMGO_LOG_LEVEL | no | info | Log level: debug, info, warn, error | | KROMGO_LOG_FORMAT | no | json | Log format: json or text |

Defaults

defaults sets the baseline for the per-endpoint fields that support it; each endpoint overrides the same-named field. All keys are optional.

defaults:
  badge:
    font: dejavu-sans # dejavu-sans (default, shields.io-style), dejavu-sans-bold, comic-neue, comic-neue-bold
    size: 11 # badge font size in points
    style: flat # flat (default), flat-square, plastic, or for-the-badge
    gallery:
      hidden: false # list badges in the gallery (default); true hides them
  graph:
    maxDuration: 1h # cap on a graph's requested window ("0" = unlimited)
    width: 600 # image width in px
    height: 200 # image height in px
    legend: true # show the series legend
    theme: light # color theme — see Themes below
    font: dejavu-sans # text font — see Themes below
    gallery:
      hidden: false # list graphs in the gallery (default); true hides them

The gallery page itself is toggled separately at the top level — see Gallery.

Badges

Each entry under badges: defines an instant-value endpoint at /badges/{id}.

| Field | Required | Description | | ------------ | -------- | ------------------------------------------------------------------------------------ | | id | yes | URL path segment — cpu → GET /badges/cpu | | query | yes | PromQL expression returning a single scalar or vector value | | title | no | Display label on the badge (defaults to id) | | type | no | instant (default) or range — see Range badges | | range | no\* | Range-query window when type: range | | valueExpr | no | CEL expression for the displayed string — see Value and color | | colorExpr | no | CEL expression for the color — see Value and color | | labelColor | no | Left-segment (label) color — a name or hex; a fixed value, not a CEL expression | | style | no | flat (default), flat-square, plastic, or for-the-badge (see below) | | icon | no | An icon on the SVG badge, e.g. mdi:server-outline or si:kubernetes — see below | | gallery | no | Per-badge gallery settings, e.g. gallery: {hidden: true} — see Gallery |

Styles

flat (the default), flat-square, and plastic are the familiar shields.io looks — a 20px badge that honors defaults.badge.font/size. for-the-badge is the chunky shields variant: a fixed 28px badge with uppercased, letter-spaced text and a bold value segment. Being a faithful port of shields' own geometry, it is fixed-size — it ignores defaults.badge.font/size (the value's bold weight is the configured face's bold companion). It pairs naturally with an icon and, with no title, collapses to a single logo+value segment — the shields "empty label" form:

badges:
  - id: kubernetes
    query: kubernetes_build_info
    valueExpr: labels[?"git_version"].orValue("unknown")
    style: for-the-badge
    icon: si:kubernetes
    colorExpr: '"blue"'

Icons

icon renders an icon on the left of the SVG badge, written as : for one of two sets:

• mdi: — a Material Design Icon, e.g. mdi:server-outline.
• si: — a Simple Icons brand logo, e.g. si:kubernetes.

badges:
  - id: nodes
    query: count(kube_node_info)
    icon: mdi:server-outline
    title: Nodes
  - id: version
    query: kubernetes_build_info
    icon: si:kubernetes
    title: Kubernetes

Both entire sets are embedded in the binary — no network or disk access at runtime — so any mdi: from the MDI library (~7,400 glyphs, e.g. mdi:database-outline, mdi:rocket-launch) or any si: from Simple Icons (~3,400 logos, e.g. si:docker, si:grafana, si:prometheus) works. The sets are stored compressed (~0.8 MB MDI, ~1.9 MB Simple Icons) and each is decoded into memory only on first use. An unknown set or name fails fast at startup. The icon data is built from the @mdi/svg and simple-icons npm packages at build time (not committed) — see Building from source.

Range badges

By default a badge's value comes from an instant query at "now". Set type: range to instead run a range query over a window and reduce it to a single value — useful for averages, peaks, or comparing against an earlier period. The window is end = now - offset, start = end - last.

badges:
  - id: cpu_prev_week_avg
    type: range
    query: "cluster:node_cpu:ratio_rate5m * 100"
    range:
      last: "7d" # window length (required)
      offset: "7d" # shift the window back; here: 14d ago .. 7d ago (default: ends now)
      step: "1h" # resolution (default: last/100, min 1m)
      reduce: avg # last (default), first, avg, min, max, sum
    valueExpr: string(result) + "%"

reduce collapses each series to one value; non-finite samples (NaN/Inf) are skipped.

Value and color

valueExpr and colorExpr are CEL expressions (the Expr suffix marks the CEL-evaluated fields; query is PromQL and labelColor is a static value). CEL is sandboxed (no environment, file, or network access) and compiled once at startup, so a malformed expression fails fast rather than per request. Each expression receives two variables:

| Variable | Type | Description | | -------- | --------------------- | -------------------------------------------------------- | | result | double | The sample value (for type: range, the reduced value). | | labels | map(string, string) | The sample's labels, e.g. labels["instance"]. |

• valueExpr must return a string — the message shown on the badge. Defaults to string(result).
• colorExpr must return a string — a shields.io color name (green,

Text color adapts to the background for legibility — dark text on light colors, white on dark — the same way shields.io does, so a light custom colorExpr stays readable. Every badge also carries role="img", an aria-label, and a