KubeOpera API

Service: kubeopera-api · Port: 8090 · Database schema: kubeopera

kubeopera-api is the platform's central service. Everything about applications — creating, deploying, observing, changing and rolling them back — goes through it, along with CloudSpaces, clusters, pipelines, builds, federation across clusters and webhook subscriptions.

Design: desired state lives in Git

kubeopera-api never deploys an application by talking to Kubernetes directly. Instead:

1. It records the app and writes its desired state as a KubeOperaApp custom resource.
2. app-controller turns that into manifests and commits them to Git.
3. Flux, inside the tenant's vCluster, applies them.

That's why every app has a full, auditable history, why rollback is simple and safe, and why the cluster always converges to what you asked for.

Creating an app

POST /api/v1/apps is a single, atomic request that carries everything about the app — image or source, port, domain and TLS, resources, autoscaling, environment variables and health checks — so an app is never half-configured.

kubeopera-api then:

1. validates the request and saves the app;
2. computes the app's address server-side — <app>-<cloudspace>.apps.kubeopera.io, or your custom domain — rather than trusting a client-supplied value;
3. creates the KubeOperaApp resource, targeting the right vCluster (a specific one via tenant_cr_name, or the CloudSpace's default).

Saving the app and creating its resource are coordinated through an outbox, so if the Kubernetes API is briefly unavailable the resource is created as soon as it's back — no app is ever left without one.

Knowing when an app is really up

A KubeOperaApp becoming Ready means its manifests were generated and applied — not that users can reach it. GET /api/v1/apps/{appId}/deploy-status answers the real question by checking, in order:

1. GitOps sync — Flux has applied the latest commit;
2. Workload readiness — the Deployment's pods are ready inside the tenant's vCluster;
3. Reachability — an HTTPS request to the app's address succeeds.

Only the last check proves DNS, certificate, ingress and app all work together. The Deploy wizard's progress view polls this endpoint.

Talking to the right vCluster

Every per-app operation — pods, logs, events, metrics, scaling — targets the tenant's own vCluster, never the host cluster. A small resolver reads the tenant's kubeconfig Secret, builds a client for its vCluster and caches it briefly. The same resolver powers the CloudSpace-wide resource views (pods, deployments, services, ingresses, volumes, jobs) on the tenant's Workloads pages.

Deployment history and rollback

Every change to an app's pod template creates a new Kubernetes ReplicaSet with a revision number. kubeopera-api reads that history directly, so it always matches what actually ran.

Rollback takes the chosen revision's configuration (image, port, environment and resources), applies it to the app, and commits it through the normal Git path. Flux converges the app back to that state and a new revision records the rollback.

Instant operations

Scale, restart, stop and start take effect immediately in the vCluster, so they feel instant. They are also committed to Git straight away, so the desired state in Git always matches what's running and a later reconcile never undoes them.

REST API

Applications

Method	Path	Description
GET	/api/v1/apps	List apps.
POST	/api/v1/apps	Create and deploy an app.
GET	/api/v1/apps/{appId}	App detail and live status.
PUT	/api/v1/apps/{appId}	Update an app.
PATCH	/api/v1/apps/{appId}/domain	Change the app's domain.
DELETE	/api/v1/apps/{appId}	Delete an app and everything it created.
POST	/api/v1/apps/{appId}/restart · /scale · /stop · /start	Instant lifecycle operations.
GET	/api/v1/apps/{appId}/deploy-status	GitOps, readiness and reachability status.
GET	/api/v1/apps/{appId}/metrics · /pods · /events · /logs	Live data from the tenant's vCluster.
GET · PUT	/api/v1/apps/{appId}/config	Full app configuration.
GET · PUT	/api/v1/apps/{appId}/config/env-vars	Environment variables.
GET	/api/v1/apps/{appId}/deployments	Revision history.
GET	/api/v1/apps/{appId}/deployments/{deploymentId}	One revision's detail.
GET	/api/v1/apps/{appId}/deployments/{deploymentId}/export	Export a revision's configuration.
POST	/api/v1/apps/{appId}/deployments/{deploymentId}/tags	Tag a revision.
PUT	/api/v1/apps/{appId}/deployments/{deploymentId}/notes	Add notes to a revision.
GET	/api/v1/apps/{appId}/deployments/compare	Compare two revisions.
POST	/api/v1/apps/{appId}/rollback	Roll back ({ "revision": 4 }).
POST	/api/v1/apps/{appId}/clone · /promote	Clone an app, or promote it to another CloudSpace.
GET · PUT	/api/v1/apps/{appId}/deployment-strategy	Rolling, canary or blue/green.
GET · POST	/api/v1/apps/{appId}/canary (/promote, /abort, /pause, /resume)	Control a canary rollout.
GET · POST	/api/v1/apps/{appId}/bluegreen (/switch, /rollback)	Control a blue/green rollout.

Clusters, CloudSpaces and vClusters

Method	Path	Description
GET · POST	/api/v1/clusters	List clusters; register, connect or create one.
GET · DELETE	/api/v1/clusters/{clusterId}	Cluster detail; disconnect or delete.
POST	/api/v1/clusters/register-self	Register the cluster KubeOpera runs on.
GET · POST	/api/v1/cloudspaces	List or create CloudSpaces.
GET · PATCH · DELETE	/api/v1/cloudspaces/{cloudSpaceId}	CloudSpace detail, rename or resize, delete.
GET · POST	/api/v1/cloudspaces/{cloudSpaceId}/vclusters	List or add vClusters.
GET · DELETE	/api/v1/cloudspaces/{cloudSpaceId}/vclusters/{name}	vCluster detail or deletion.
GET	/api/v1/cloudspaces/{cloudSpaceId}/vclusters/{name}/kubeconfig	Download a kubeconfig.
GET	/api/v1/cloudspaces/{cloudSpaceId}/pods · /events · /deployments · /services · /ingresses · /pvcs · /jobs · /cronjobs	CloudSpace-wide resource views.
GET	/api/v1/cloudspaces/{cloudSpaceId}/logs/{podName}	Logs for any pod in the CloudSpace.

Pipelines and builds

kubeopera-api is the tenant-aware front door for cicd-gateway and build-service: it takes the tenant from the caller's token and passes it on, so no tenant can reach another's pipelines or builds.

Method	Path	Description
GET · POST	/api/v1/pipelines	List or create pipelines.
GET · PATCH · DELETE	/api/v1/pipelines/{id}	Pipeline detail, update, delete.
GET	/api/v1/pipelines/{id}/runs	Run history.
GET	/api/v1/pipelines/summary · /api/v1/pipelines/{id}/runs/summary	7-day summaries.
GET · POST	/api/v1/builds	List or start builds.
GET	/api/v1/builds/{id} · /api/v1/builds/{id}/logs	Build status and logs.
GET · POST	/api/v1/build-configs	List or create build-on-push configurations.
DELETE	/api/v1/build-configs/{id}	Remove a configuration.
POST	/api/v1/build-configs/{id}/trigger	Start a build now.

Webhooks

Method	Path	Description
GET · POST	/api/v1/webhooks	List or create webhook subscriptions.
GET · PATCH · DELETE	/api/v1/webhooks/{id}	Detail, update, delete.
GET	/api/v1/webhooks/{id}/deliveries	Recent deliveries and responses.
POST	/api/v1/webhooks/{id}/deliveries/{deliveryId}/redeliver	Send a delivery again.

See Webhooks for events and signatures.

Federation, onboarding and support

Method	Path	Description
GET	/api/v1/federation/overview · /health · /cost · /anomalies · /optimizer	Fleet-wide rollups across every cluster.
POST	/api/v1/onboarding/provision	Provision a new tenant's first CloudSpace.
GET	/api/v1/onboarding/checklist	Onboarding progress.
GET · POST	/api/v1/support/tickets	List or open support tickets.
GET	/api/v1/support/tickets/metrics	Support metrics.
PATCH	/api/v1/support/tickets/{id}	Update a ticket.

Configuration

Variable	Default	Description
DATABASE_URL	—	PostgreSQL connection (required).
AUTH_JWT_ACCESS_SECRET	—	Validates access tokens (required).
FLUX_GIT_URL / FLUX_GIT_BRANCH	— / main	The fleet repository for tenant app manifests.
FLUX_GIT_SECRET_REF	—	Secret holding Git credentials.
FLUX_INTERVAL	1m	Flux reconcile interval for tenant apps.
APPS_BASE_DOMAIN	apps.kubeopera.io	Parent domain for app addresses.
CICD_GATEWAY_BASE_URL	http://cicd-gateway:8087	cicd-gateway, for pipeline routes.
BUILD_SERVICE_BASE_URL	http://build-service:8098	build-service, for build routes.
RABBITMQ_URL	—	Consumes platform events for webhook delivery.
PORT	8090	HTTP port.