TRY ME

Try Valo for free

We want to show you something amazing.

We'll send you a link to download a fully functional Valo copy to play with.



Great! Check your email and enjoy Valo



Apologies, we seem to be having a problem processing your input, please try again

Cluster API

Get the cluster state

GET /cluster

Get the current state of the cluster. Returns all the sub-resources as one large document.

Clients can subscribe to the status of the cluster using the live SSE cluster channel.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "nodes":   "see format in /cluster/nodes"
    "tenants": "see format in /cluster/tenants"
}

Get the cluster nodes

GET /cluster/nodes

Get the nodes currently in the cluster.

A cluster node can in the following states:

  • Pending: the node is starting up the data repositories.
  • Joining: the node is taking ownership of data from other nodes in the cluster.
  • Joined: the node is up and running normally.
  • Leaving: the node is transferring ownership of data to other nodes in the cluster to become ready to remove
  • Left: the node has been removed from the cluster.

Nodes may also become unavailable in any of the states above (apart from Left). This means the remote Valo process has stopped or the remote machine is not reachable across the network. The availability status is published in the available flag.

Clients can subscribe to changes in node status using live SSE cluster channel.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "nodes": [
        {
            "name": "my-node-a",
            "zone": "EMEA",
            "publicKey": "6GLbYBg9q)]!6SJS$EJepU(hU/XZM#o#K&WVdIw@",
            "address": "192.168.124.1",
            "port": 2551,
            "version": {
                "number": "0.5.0",
                "revision": "8510ae91cc91dcab27b6c16e1d3a431de293464d"
            },
            "state": "Joined",
            "available": "true"
        }
    ]
}

Get a cluster node state

GET /cluster/nodes/:name

Get information about the node with a given name.

GET /cluster/nodes/my-node-a HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
    "node": {
        "name": "my-node-a",
        "zone": "EMEA",
        "publicKey": "6GLbYBg9q)]!6SJS$EJepU(hU/XZM#o#K&WVdIw@",
        "address": "192.168.124.1",
        "port": 2551,
        "version": {
            "number": "0.5.0",
            "revision": "8510ae91cc91dcab27b6c16e1d3a431de293464d"
        },
        "state": "Joined",
        "available": "true"
    }
}
Status Codes:

Get the local node state

GET /cluster/localNode

Get information about this Valo node. The format is the same as /cluster/nodes/:name.

GET /cluster/localNode HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json

{
    "node": {
        "name": "my-node-a",
        "zone": "EMEA",
        "publicKey": "6GLbYBg9q)]!6SJS$EJepU(hU/XZM#o#K&WVdIw@",
        "address": "192.168.124.1",
        "port": 2551,
        "version": {
            "number": "0.5.0",
            "revision": "8510ae91cc91dcab27b6c16e1d3a431de293464d"
        },
        "state": "Joined",
        "available": "true"
    }
}

Get the tenants

GET /cluster/tenants

List the tenants defined in the cluster.

Currently just the tenant names are returned. More data will be added in future versions of the API.

Example request

GET /cluster/tenants HTTP/1.1

Example response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "tenants": [
        { "name": "demo" }, {"name": "equities"}
    ]
}

Get a tenant state

GET /cluster/tenants/:name

Get information about a tenant in the cluster.

Currently, just the tenant name is returned. More information will be included in future versions of the API.

Example request:

GET /cluster/tenants/newTenant HTTP/1.1

{
    "name": "myTenant"
}
Status Codes:

Put a tenant

PUT /cluster/tenants/:name

Add a new tenant to the cluster.

The tenant is considered active when the TENANT_ADDED event is fired on the updates URI.

Example request:

PUT /cluster/tenants/newTenant HTTP/1.1

{}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
}
Status Codes:

Get the output channel

GET /output/cluster

An SSE output channel that can be used to monitor changes in the state of the cluster.

Each message has a top level type field that can be used to discriminate the different events:

When a client first connects to the channel, a CLUSTER_STATE message is sent, followed by further updates. Note that this event is also sent to other clients on the channel, so expect to receive the state event at any time.

Event Type
CLUSTER_STATE
NODE_STATE_UPDATED
TENANT_ADDED

Cluster State

{
    "type": "CLUSTER_STATE",
    "state": "same format as /cluster"
}

Node state updated

{
    "type": "NODE_STATE_UPDATED",
    "node": "my-node-c",
    "state": "Joining"
}

Tenant added

{
    "type": "TENANT_ADDED",
    "tenant": {
        "name": "newTenantName"
    }
}

Add nodes

POST /cluster/nodes

Adds nodes to the cluster

Example request:

POST /cluster/cluster/nodes HTTP/1.1

{
   "nodes" : [
     {
       "name": "valo1",
       "publicKey" : "y/0L){oT1/zPPeR*Mn%BEk[$<Njz(LY/<)3S1%J0",
       "address": "localhost",
       "port": 2552
     },
     {
        "name": "valo2",
        "publicKey" : "y/0L){oT1/zPPeR*Mn%BEk[$<Njz(LY/<)3S1%J0",
        "host": "otherhost",
        "port": 2553
     }
   ]
}

Example response:

The same as GET /cluster

Remove a node

DELETE /cluster/nodes/:name

Permanently Removes a node to the cluster

Example request:

DELETE /cluster/nodes/node1 HTTP/1.1

Example response:

The same as GET /cluster

Data Transfers

GET /cluster/transfers

Return information about the progress of data transfers that are running. Transfers are caused when nodes join or leave the cluster. A node will only move to Joined or be removed from the cluster once all transfers are complete.

Example request:

GET /cluster/transfers HTTP/1.1

Example response:

{
    "actions":[
        {
            "type":"repo_data_transfer",
            "repo":"KV",
            "from":"valo0",
            "to":"valo1",
            "complete":false,
            "percentComplete": 0,
            "info":{}
        },
        {
            "type":"repo_data_transfer",
            "repo":"ssr",
            "from":"valo0",
            "to":"valo1",
            "complete":false,
            "percentComplete": 50,
            "info":{}
        },
        {
            "type":"repo_data_transfer",
            "repo":"tsr",
            "from":"valo0",
            "to":"valo1",
            "complete":true,
            "percentComplete": 100,
            "info":{}
        }
    ]
}