Streaming API

Purpose: For developers, provides openCenter Streaming API endpoints and CRD configuration fields.

Planned Feature

This API is planned for a future release and is not available in CLI v1.0.0. The endpoints and event formats described below represent the intended design and may change before release.

Overview

The Streaming API provides real-time cluster status updates over Server-Sent Events (SSE). It is served by the openCenter backend and consumed by the web UI and CLI for live progress tracking during cluster operations.

Endpoints

GET /api/v1/clusters/{cluster}/events

Opens an SSE stream for cluster lifecycle events.

Parameter	Type	Required	Description
cluster	path	yes	Cluster identifier

Response: text/event-stream with events in the following format:

event: status
data: {"phase":"provisioning","step":"terraform-apply","progress":45,"message":"Creating VM 3 of 6"}

event: status
data: {"phase":"provisioning","step":"terraform-apply","progress":60,"message":"Creating VM 5 of 6"}

event: complete
data: {"phase":"provisioning","step":"terraform-apply","progress":100,"message":"Infrastructure ready"}

Event Types

Event	Description
status	Progress update for the current operation
complete	Operation phase completed
error	Operation failed (includes error detail)
log	Log line from the running operation

Event Data Fields

Field	Type	Description
phase	string	Lifecycle phase: provisioning, kubernetes, bootstrap, services
step	string	Current step within the phase
progress	integer	Percentage complete (0–100)
message	string	Human-readable status message
error	string	Error detail (only on error events)

GET /api/v1/clusters/{cluster}/status

Returns the current cluster status as a single JSON response (non-streaming).

{
  "cluster": "prod-cluster",
  "phase": "running",
  "nodes": {
    "ready": 6,
    "total": 6
  },
  "flux": {
    "kustomizations": {"ready": 12, "total": 12},
    "helmreleases": {"ready": 10, "total": 10}
  }
}

Authentication

All streaming endpoints require a valid bearer token in the Authorization header:

Authorization: Bearer <token>

Tokens are issued by Keycloak and validated by the backend. The CLI obtains tokens automatically when opencenter cluster env has been evaluated.

Connection Behavior

Setting	Value	Description
Reconnect interval	5 seconds	Client should retry on disconnect
Heartbeat	30 seconds	Server sends :keepalive comments
Timeout	None	Stream stays open until the client closes

Client Usage

The CLI connects to the streaming API during long-running operations:

opencenter cluster setup prod-cluster
# CLI streams progress events to the terminal in real time

For custom integrations, any SSE-compatible client works:

curl -N -H "Authorization: Bearer $TOKEN" \
  https://api.opencenter.example.com/api/v1/clusters/prod-cluster/events