What it does
POST /admin/v1/clusters deploys one KynetraDB node, or a primary plus two replicas for the high-availability option, through a provider adapter and records the result. The replicas start in the replica role and point at the primary URL. Profiles whose promised behaviour the code does not configure, such as sharded and PostgreSQL-durability high availability, are refused. The path where every node deploys successfully is not exercised against a provider in the engine tests.
How it works
The cluster routes need platform administrator authority. A request names a registered provider, a plan (a CPU and memory tier), a region, a cluster configuration (single or ha), storage minimum and limit, an engine, and optionally an image, environment variables and a runtime profile. The engine must be kynetradb: other labels, such as postgres, vitess or mysql, are rejected before any provider call, because KynetraDB has no PostgreSQL or MySQL wire protocol. Providers that create PostgreSQL projects or edge gateways, such as Supabase, Neon and Cloudflare, are refused for the same reason.
The server deploys the primary, then for ha two replicas. Replica environments set KYNETRA_ROLE=replica and KYNETRA_PRIMARY_URL to the URL of the primary, which is how a replica node finds the stream it follows. If a node fails to deploy, the record keeps a placeholder marked as an error for it, and the cluster status becomes degraded or error. GET /admin/v1/clusters/{id}/topology polls the health of the members, and DELETE destroys every member.
Runtime profiles are checked against what the deployment code configures. dev-single, tiny-vps, prod-single, edge-read and managed-cloud can be deployed. tiny-vps needs a plan between 512 and 1,024 MiB and a storage limit of at most 64 GB, and locks the file backend with small thread counts. pg-ha-read and sharded-ha are rejected, because the deployment code configures neither PostgreSQL durability nor sharding.
GET /admin/v1/clusters/catalog lists plans, regions, configurations, storage options and the provider catalogue, and POST /admin/v1/clusters/estimate returns a cost estimate computed from the catalogue prices.
Where you reach it
- HTTP
POST /admin/v1/clusters, GET /admin/v1/clusters, GET|DELETE /admin/v1/clusters/:id - HTTP
GET /admin/v1/clusters/catalog, POST /admin/v1/clusters/estimate - HTTP
GET /admin/v1/clusters/:id/topology, GET /admin/v1/clusters/:id/connection - Config
KYNETRA_CLUSTER_IMAGE (default container image for cluster nodes)
Limits
- The success path, where every node deploys, is not exercised against a live or mock provider in the engine repository. The tests cover the catalogue, cost arithmetic, admission refusals, the profile rules and entity round trips.
- High availability here means a primary with two read replicas created together. The cluster code does not elect a leader or move traffic when a node fails. The catalogue text for the option carries an availability label; treat it as descriptive text, not a commitment.
- The storage minimum and limit, the cluster name and the engine label are set on nodes as environment variables that no code in the server reads, so they do not size or cap storage.
- Nodes use the image in the request or in KYNETRA_CLUSTER_IMAGE, with a default compiled into the server. This edition does not document a published image, so set one explicitly. AWS needs an ECR image.
- The role endpoints under a cluster are placeholders. They return a connection string in the PostgreSQL URL form and a role that stays in pending_provision, and KynetraDB does not speak the PostgreSQL wire protocol. Do not use them.
- DELETE destroys each member through its provider adapter and then removes the cluster record even if a member could not be destroyed. Read destroy_errors in the response and check the provider console for anything left running.
- Catalogue prices are descriptive values for the estimate. They are not provider billing.
- No adapter attaches persistent storage, as described under cloud provider adapters.
Evidence
- On this siteDeployment target matrix: target profiles, not installers
- TestsCovered in the engine repository by 16 clusters.rs tests, among them mounted-router tests that a project-scoped caller is refused on every cluster route, that a non-KynetraDB engine and the pg-ha-read profile are rejected before any deployment, and a separate file of 16 catalogue and cost tests that re-implement the arithmetic inline
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.