Create cluster

Create an autoscaling cluster: a group of instances behind a load balancer that grows and shrinks with CPU load.

To make an app you are already running highly available, use POST /v1/clusters/from-instance instead. It takes the same fields (minus image, plus instance_id), needs no rebuild or redeploy, and keeps your URL.

Endpoint


POST /v1/clusters

Request body


{
  "name": "web-cluster",
  "image": "IMAGE_ID",
  "flavor": "m1.small",
  "min_size": 3,
  "max_size": 5,
  "backend_network_id": "NETWORK_ID",
  "key_name": "KEYPAIR_NAME",
  "port": 80,
  "dnsName": "web-cluster-a1b2c3d4.redu.cloud",
  "scale_out_threshold": 0.7,
  "scale_in_threshold": 0.2
}

Fields

Field	Required	Description
`name`	yes	Cluster name
`image`	yes	Image or snapshot every member boots from
`flavor`	yes	Member size, e.g. `m1.small`
`min_size`	no	Members always running (default 1). Set 3 for high availability
`max_size`	no	Peak members under load (default 5). Must be at least `min_size`
`backend_network_id`	yes	Private network the members sit on
`backend_subnet_id`	no	Derived from `backend_network_id` when omitted
`key_name`	yes	SSH keypair name
`port`	no	Port the load balancer routes to (default 80)
`dnsName`	no	Public name for the load balancer. Auto-generated when omitted
`scale_out_threshold`	no	CPU fraction that adds a member (default `0.7`)
`scale_in_threshold`	no	CPU fraction that removes one (default `0.2`)

Field sources

Field	Where to get it
`image`	List Images
`flavor`	Flavors
`backend_network_id`	List Networks
`key_name`	SSH Keypairs

High availability

min_size: 3 is the difference between an autoscaling cluster and a highly available one:

members are placed on three different physical machines, automatically
a destroyed member is rebuilt without you doing anything, in 1.5 to 5 minutes depending on how it failed (both ends measured on the live platform), while the cluster keeps serving on the members that remain
updates replace members one at a time, each given time to start serving before the next is taken out

Two members is not highly available. Three is the smallest number that survives losing one.

Members come up one at a time, which is what places them on separate machines, so a 3-member cluster takes longer to build than a single instance. GET /v1/clusters reports progress while it does.

Your image must start the app on every boot (a service definition or a container restart policy, not a first-boot script) and bind its port only once it is ready to serve. A replaced member that boots without the app never joins the load balancer, and nothing reports an error.

Example

cURL


curl https://api.redu.cloud/v1/clusters \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-cluster",
    "image": "54f06e50-0459-4699-b0d5-be8df4c220a4",
    "flavor": "m1.small",
    "min_size": 3,
    "max_size": 5,
    "backend_network_id": "32081aab-e6c7-40d8-bb04-90b0dbb7e8ee",
    "key_name": "redu-cli-key",
    "port": 80
  }'

Fetch


await fetch("https://api.redu.cloud/v1/clusters", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "web-cluster",
    image: "IMAGE_ID",
    flavor: "m1.small",
    min_size: 3,
    max_size: 5,
    backend_network_id: "NETWORK_ID",
    key_name: "KEYPAIR_NAME",
    port: 80
  }),
});

Axios


import axios from "axios";
 
await axios.post(
  "https://api.redu.cloud/v1/clusters",
  {
    name: "web-cluster",
    image: "IMAGE_ID",
    flavor: "m1.small",
    min_size: 3,
    max_size: 5,
    backend_network_id: "NETWORK_ID",
    key_name: "KEYPAIR_NAME",
    port: 80
  },
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
    },
  }
);

Python


import requests
 
requests.post(
    "https://api.redu.cloud/v1/clusters",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "name": "web-cluster",
        "image": "IMAGE_ID",
        "flavor": "m1.small",
        "min_size": 3,
        "max_size": 5,
        "backend_network_id": "NETWORK_ID",
        "key_name": "KEYPAIR_NAME",
        "port": 80,
    },
)

Go


// similar to create instance, omitted for brevity

Successful response


{
  "message": "Stack creation started"
}

Creation is asynchronous. Poll GET /v1/clusters until the cluster reports CREATE_COMPLETE.

Notes

Cluster creation is asynchronous, and a 201 means the build started, not that it finished
Members are built one at a time so they land on separate machines
A public name for the load balancer is created for you unless you pass dnsName