Architecture
What runs in your clusters, what runs in the hub, and how data moves between them.
Who does what
From infrastructure to an approved change
- 01
Collect
The read-only agent sends cluster snapshots. Billing exports or rate cards provide the cost basis.
Agent + billing
- 02
Allocate
The hub assigns cost to workloads and teams, separates shared and idle spend, and reconciles the totals.
KubeOn hub
- 03
Review
A proposal brings together the saving, evidence, risk and patch. An authorized reviewer records a decision.
Your reviewers
- 04
Apply + verify
Merge the pull request, or let KubeOn apply the change where you granted write access. The saving is then measured.
Your pipeline or KubeOn
Read-only by default. KubeOn changes a cluster only where you grant write access, feature by feature.
Read the workflowOn this page
Components
| Component | Where it runs | What it does |
|---|---|---|
| Agent | Each cluster, as a CronJob | Lists the Kubernetes API read-only, reads usage from metrics-server and optionally Prometheus, sends one snapshot per hour to KubeOn |
| Snapshot storage | KubeOn, a bucket per organization | Holds the gzipped NDJSON snapshots the agent sends. The agent cannot send them anywhere else |
| API | Hub | Serves the app and the REST API, enforces roles and team scope |
| Worker | Hub | Ingests snapshots and billing, allocates, reconciles, computes savings and proposals |
| Scheduler | Hub, single replica | Runs the job chain on time; a single replica so no job fires twice |
| Database | PostgreSQL 16 | Allocations, ownership, budgets, proposals and the audit log |
| Cache and broker | Redis 7 with TLS | Job queue and precomputed views |
Data flow
- On the hour, the agent lists nodes, namespaces, workloads, pods, PersistentVolumes, PVCs and services, 500 objects per page.
- It reads current pod usage from
metrics.k8s.ioand, ifprometheus.urlis set, the last full hour of CPU, memory and volume usage. - It sends one gzipped snapshot on an upload link KubeOn issues for your organization. The first line records the schema version, row counts per kind, collection errors, agent version and peak memory.
- KubeOn ingests the snapshot as soon as the upload completes. A snapshot whose rows do not match its header is rejected, and the job reports the failure.
- Daily (06:00 UTC by default) the hub reads billing. The last 3 days are re-read because providers restate recent line items.
- The hub allocates each cluster-day that has both usage and billing, reconciles it to the bill, and repairs any day in the last 7 once late data arrives. Older days, up to 92 back, are re-run from Data health.
- Savings are recomputed every 30 minutes; change proposals are regenerated daily.
- Budgets, alert rules and anomalies are evaluated hourly at :50.
Network paths
Every connection starts inside your environment and goes out. The hub never opens a connection to a cluster's API server, and the agent exposes nothing.
| From | To | Port | Purpose |
|---|---|---|---|
| Agent | Kubernetes API (in cluster) | 443 | Read-only list and watch |
| Agent | Prometheus (in cluster, optional) | 9090 | Usage history |
| Agent | app.kubeon.io, and KubeOn's storage unless kubeon.directUpload is false | 443 | Send the snapshot |
| Hub | Billing APIs (Athena, Blob Storage, BigQuery) | 443 | Read billing |
| Hub | Slack, Teams, SMTP, webhooks | 443 / 587 | Notifications you configure |
Identity
The agent authenticates to KubeOn with its cluster's token. The token can only send that cluster's data into your organization, and you revoke it in Settings > Integrations. The agent needs no cloud identity: no IAM role, workload identity or storage credentials in your accounts. It cannot read, list or delete snapshots.