What is vStack Center

vStack Center is the management plane for a vStack Hyperconverged Infrastructure cluster (referred to below as vStack HCP). Administrators use it to create virtual data centers (VDCs), networks, and virtual machines (VMs), assign roles, and view the security event log and metrics. The VMs themselves run on the hypervisor on cluster nodes. vStack Center maintains the authoritative cluster state and decides what should run and where.

vStack HCP is an umbrella product with two parts: vStack Center handles management, and vStack OS provides the node operating system, including the hypervisor and storage layer. vStack Center does not interact with nodes directly. It sends a task to Cluster Manager, which delivers it to the nodes. This separation is reflected in API behavior: a VM operation involves an exchange between vStack Center and agents on the nodes, rather than a single database write. Nodes, their installation, hardware requirements, and the node CLI are described in the vStack OS documentation.

A cluster managed by vStack Center operates independently. A separate product, GI, groups multiple clusters into a federation and proxies requests to them, but the cluster is unaware of this: the method set and access rules remain the same.

Two components

vStack Center consists of two services. One accepts external requests; the other executes them.

Component	What it does	What it works with
cluster-endpoint	The cluster HTTPS endpoint. Accepts HTTP POST requests with a JSON-RPC 2.0 body, queues each request, waits for a response, and returns it to the client. Maintains cookie sessions. Proxies WebSocket connections to the VM console	RabbitMQ, the client browser
dispatcher-cluster	The vStack Center core. Reads requests from the queue, checks permissions, tracks entities and asynchronous operations, and routes work to agents	PostgreSQL, SQLite, InfluxDB, Cluster Manager over ZMQ

The client sees only the first component: one HTTPS address and one body format. Everything else is hidden behind the queue.

Request path

Клиент → cluster-endpoint (HTTPS) → RabbitMQ → dispatcher-cluster → PostgreSQL / SQLite / InfluxDB
                                                        │ ZMQ
                                                        └→ Cluster Manager → узлы кластера (AMQP)

Клиент → cluster-endpoint (WSS) → VNC-сервер ВМ

The diagram has two practical implications. First, cluster-endpoint does not store application operation state, so it can be restarted and scaled separately from the core. Second, VM console traffic bypasses the queue: it travels over WebSocket, directly through the endpoint to the machine's VNC server.

One protocol for everything

vStack Center uses only JSON-RPC 2.0: each operation has a name, its own set of arguments, and a consistent response format. The web UI follows the same path as a custom client; vStack Center has no separate interface for the web UI. As a result, anything an administrator does with the mouse can also be done programmatically. The procedure pages in this documentation therefore list the API methods for the same operations at the end.

The response structure is the same for all methods. A successful response contains the payload for the specific operation: an object, an array, or a single value. A failure response contains a numeric code. Codes are grouped by method, so the number identifies where the request stopped. The request and response formats are described in the API overview reference.

Session

The dispatcher does not obtain the caller's identity from the transport. It identifies the caller by a session token: the web UI receives a token at sign-in and presents it with every operation, and a custom client must do the same. The dispatcher rejects requests without a token before running application logic, with code -9494 ("No session token").

A forced password change follows a separate path. A user with this flag receives one-time access valid for 5 minutes instead of a regular session. Until the password is changed, only the password change itself and reading the password policy are available. The web UI therefore immediately displays the new password form, and the other sections become available after the change. Token formats and response fields are described in the Authentication reference.

Who can see what

Permissions in vStack Center are defined by a role and its scope: the cluster or a specific VDC. Method sections describe access in the same terms: "Cluster master — any VM in the cluster" and "regular user — only VMs in VDCs where roles are assigned."

id	Role	Scope
1	Cluster Master	Full access to the entire cluster
2	vDC Admin	VDC administrator
3	vDC User	VDC user
4	vDC Viewer	VDC viewer
5	Resource Viewer	View cluster resources
6	Security Admin	Cluster level: security log and audit
7	VM Developer	VDC level: create and configure virtual machines

VDC management operations, that is, creation, modification, and deletion, are available only to Cluster Master. Work within a VDC is delegated through roles 2–4 and 7. Roles 6 and 7 were introduced in 3.0.3.

Synchronous and asynchronous methods

Some methods respond immediately because they only read or write the database. For example, vm-console returns connection details without contacting a node. Other methods respond after an agent confirms that the work is complete.

vms-create follows a long sequence: parameter validation, pool selection, a database write, a handoff to the Storage agent to create zvols, and then a handoff to the VM agent for registration. The client receives a response after two-phase callback processing, and the response contains a complete description of the created VM. vms-start works the same way: the method sends a command to the agent, and the final response arrives through a callback and contains data.node_id, the node on which the VM started.

The practical implication is that the client must be able to wait. Set the request timeout based on the duration of the actual operation on the node, rather than the speed of the database.

What to know before you start

A request without a session token will not be processed. Reason: the dispatcher identifies the caller only by the session token; transport headers are not used for this. Workaround: present the token in every application call, or the response will contain code -9494.

Some operations finish after the response is returned. Reason: agents on the nodes perform the work, and the dispatcher only waits for their callbacks. Workaround: rely on the method's final response rather than the first one, and allow extra time in the client timeout.

An OS image that is not visible returns "not found" rather than "access denied." Reason: the existence of a private image belonging to another VDC is not disclosed. If you try to select it, vms-create returns -256. Workaround: use a cluster-shared image (is_cluster_shared) or request a visibility grant for the required image for your VDC.

Next steps

The complete path from sign-in to a running VM is covered in the quick start: creating a VDC, assigning a network, creating and starting a machine, and connecting to its console.