Add /snapshot, Fleet, and OpenAPI for RL workloads

[dantelex]

What this does

Two new things you can do with the apiserver, plus the OpenAPI contract
that documents them for SDKs.

1. GET /clusters/<id>/control-plane/snapshot

One HTTP call returns everything we're currently watching in a control
plane — straight from in-memory caches, no etcd hit. Fast enough to use
inside a hot RL/agent loop where you want to score a rollout after every
step.

GET /clusters/team-alpha/control-plane/snapshot?resource=pods,configmaps

Optional knobs: resource=, includeEmpty=, warm=.

2. kind: Fleet (kplane.dev/v1)

Declarative N-plane provisioning. You write one YAML, an in-process
controller spins up that many control planes using the same bootstrap
path organic traffic uses, and status.readyReplicas ticks up.

apiVersion: kplane.dev/v1
kind: Fleet
metadata: { name: rl-rollout }
spec:
  replicas: 1000
  namePrefix: rl-

The Fleet CRD installs itself into the root control plane on startup,
so the API is just there once the server boots.

3. OpenAPI

api/openapi/kplane.v1.yaml is the single source of truth for both
endpoints. Embedded into the binary and served live at:

• GET /openapi/kplane.yaml
• GET /openapi/kplane.json

These are public on purpose so SDK generators and CI can fetch them
without a token. A drift-check test in api/openapi/spec_test.go fails
the build if any path or schema the SDK depends on gets removed.

This is what the Python SDK
generates against — see the matching Initial SDK commit there.

Why now

The kplane density story (~3MB, ~47ms per plane) is interesting on its
own, but the actual unlock for AI workloads is being able to:

1. Score a plane's state cheaply (snapshot)
2. Spin up many planes declaratively (Fleet)

Together they turn kplane into an RL environment substrate. See
docs/snapshot-and-fleet.md for the full
design rationale.

What's intentionally out of scope (V0)

• No scenario seeding — Fleets create empty planes; users apply
  manifests with their normal K8s client.
• No TTL-based cleanup — deleting a Fleet leaves member VCPs alive
  (avoids surprise data loss while we settle on finalizer semantics).
• No snapshots of CRD-defined types — only resources with a live MCI
  show up. warm=true forces creation for registered storages.
• No async / streaming snapshots — full reads only.

See docs/snapshot-and-fleet.md for the full out-of-scope list.

Commits

• 3f15822 Add /snapshot and Fleet APIs for RL workloads
• c27cfeb Add OpenAPI doc for snapshot and Fleet

Test plan

• go build ./... clean
• go vet ./... clean
• Unit tests pass (go test ./pkg/... ./cmd/... ./api/...)
• OpenAPI drift-check test passes
• Smoke tests (ETCD_ENDPOINTS=... go test -v ./test/smoke -timeout 10m) — wired in this PR but not run locally; CI's etcd service should cover it
• Manual: curl https://host/openapi/kplane.yaml returns the spec without auth
• Manual: kubectl --server=https://host/clusters/X/control-plane apply -f fleet.yaml provisions members

Related

• SDK PR / first release: https://github.com/kplane-dev/sdk-python

[zachsmith1]

separate repo for experimental work like this would be ideal