Support envelope and budgets

Support envelope

A supported installation runs on the versions below. kuben doctor checks a running installation against them:

OK for a version in the tested range;
WARN for an untested version;
FAIL for an unsupported version.

Every support bundle includes the envelope.

Dependency	Tested	Works from	Installed by `kuben setup`
Kubernetes	1.31 – 1.36	1.29	k3s v1.36
PostgreSQL	15 – 18	15	17 (chart and host)
Gateway API (standard channel)	1.2 – 1.5	1.1	1.5
cert-manager (with Gateway API support)	1.16 – 1.21	1.15	1.21

Hosts for kuben setup: Ubuntu 22.04 and 24.04, Debian 12 and 13, RHEL, Rocky and AlmaLinux 9 and 10.
Architectures: amd64 and arm64.
Pins: the exact version and digest of everything a release installs are listed in bundle.lock.json, and printed by kuben version --bundle. A test checks that they stay inside this envelope.

What is claimed, and what is not

Area	The Supported MVP
Clusters	One cluster per installation
Placements	One placement (namespace) per environment
Workloads	Stateless web and worker processes; production data in an external PostgreSQL
Availability	A single failure domain. No high-availability claim (planned for M7)
Nodes	Adding, draining and replacing nodes is the operator’s job (planned for M6)
Previews	One preview environment per GitHub pull request, with a lifetime; a fork’s preview gets no secrets
Registries	OCI registries with basic or token auth; GitHub for Git sources
Gateways	One Gateway API implementation. Traefik (k3s) is the tested one

Budgets

Budgets are limits that CI or the server enforces. They are not targets.

Budget	Limit	Enforced by
Server binary (static, UI included)	45 MiB	CI (`scripts/check-budgets.sh binary`)
Server image	50 MiB	the release (`scripts/check-budgets.sh image`)
Console bundle	per chunk	CI (`size-limit`)
Support bundle	8 MiB, newest 3 kept	`kuben support-bundle` (drops old log lines first)
Export and render plan	the envelope bound	the renderer refuses larger plans
Request body, request time	`server.max_body_bytes`, `server.request_timeout_secs`	the API
Organization resources	`quota.*`	admission (see Configuration)

Retention

Rows that only describe the past are removed after their budget. A background pass runs hourly and removes rows in batches:

Data	Kept	Setting
Expired sessions	until they expire	—
Delivered outbox messages	7 days	`retention.outbox_days`
Finished webhook deliveries	30 days	`retention.webhook_delivery_days`
Resolved incidents	180 days	`retention.resolved_incident_days`
Hourly usage of apps	7 days	`retention.usage_days`
Database backups	newest 7	`backup.keep`

Audit events, deployment runs, releases, render plans, SBOMs and scan results are never removed by this pass. They are the history an audit or a rollback depends on.

API compatibility

/api/v1 only grows. A pull request that would break it fails CI’s compatibility gate (oasdiff, comparing the OpenAPI spec with the base branch) unless it is labelled breaking. Breaking changes are recorded in the release notes. Clients generated from packages/api-client keep working across minor releases.

Acceptance runs

A release is a Supported MVP only after the acceptance scenarios S01–S10 pass on a real installation, and a reviewer signs the report. Run the harness on the server, after scripts/vps-acceptance.sh:

sudo KUBEN_URL=https://kuben.apps.example.com DOMAIN=apps.example.com \
  KUBEN_TOKEN=<admin token> KUBEN_APPROVER_TOKEN=<a second admin's token> \
  REVIEWER="Jane Doe" scripts/m4-acceptance.sh | tee m4-acceptance.md

The report lists what was checked, the Kuben and Kubernetes versions, and the date. Each check reads PASS or FAIL. Steps that need a person, a second host or a destructive action read MANUAL. These include:

the outage alert from outside the host;
a restore on a fresh host, with the measured RPO and RTO;
an interrupted upgrade;
a retaining uninstall;
the pilot.

A MANUAL row counts only once its evidence is attached. CI covers the automatable parts of every scenario on each change: the kind end-to-end suite runs export, detach and a support bundle.