How to Create a Cluster

A cluster is a logical container that organizes compute resources under a single definition with shared networking. Creating a cluster provisions the container and optionally deploys instances based on the specified plan and pool count.

Clusters support three types:

• vps: Cloud compute instances available in multiple plan categories including Shared CPU, Dedicated CPU, CPU Optimized, and General Purpose, suitable for a wide range of workloads from web applications to compute-intensive services.
• bare-metal: Single-tenant physical servers dedicated to one customer, offering maximum performance and direct hardware access without a hypervisor layer.
• gpu-fabric: GPU servers interconnected with automated high-performance fabric networking (RoCE or InfiniBand), designed for AI/ML training, distributed inference, and HPC workloads that require low-latency, high-bandwidth communication between nodes.

This guide explains how to create a cluster using a plan directly using the Vultr API. To create a cluster using a reusable instance template, see How to Create a Cluster Using an Instance Template.

1. Send a GET request to the Get Cluster Availability endpoint to check available cluster types in your target region. Replace REGION with the region identifier (e.g., ewr, ord).

   CONSOLE

   Copy

   $ curl "https://api.vultr.com/v2/clusters/availability" \
       -X GET \
       -H "Authorization: Bearer ${VULTR_API_KEY}" \
       -H "Content-Type: application/json" \
       -d '{
           "region": "REGION",
           "type": "vps"
       }'

   Explain Code

   Powered by Vultr AgentBeta

   The response contains the available cluster types and plans for the specified region.

2. Send a POST request to the Create Cluster endpoint to create a new cluster. Replace REGION with the region identifier, PLAN with the compute plan, and CLUSTER-LABEL with a descriptive name. Set type to vps, bare-metal, or gpu-fabric. The desired_pool_count must be equal to or greater than min_pool_count.

   CONSOLE

   Copy

   $ curl "https://api.vultr.com/v2/clusters" \
       -X POST \
       -H "Authorization: Bearer ${VULTR_API_KEY}" \
       -H "Content-Type: application/json" \
       -d '{
           "region": "REGION",
           "plan": "PLAN",
           "label": "CLUSTER-LABEL",
           "type": "vps",
           "min_pool_count": 2,
           "desired_pool_count": 2,
           "os_id": 2284,
           "hostname": "HOSTNAME",
           "notify_activate": true
       }'

   Explain Code

   Powered by Vultr AgentBeta

   A successful request returns an HTTP 200 OK response with the cluster details. Note the cluster id for future operations.

3. Send a GET request to the Get Cluster endpoint to retrieve the cluster details. Replace {cluster-id} with the id from the previous step.

   CONSOLE

   Copy

   $ curl "https://api.vultr.com/v2/clusters/{cluster-id}" \
       -X GET \
       -H "Authorization: Bearer ${VULTR_API_KEY}"

   Explain Code

   Powered by Vultr AgentBeta

   Verify that the cluster status progresses from Pending to Active once all instances are provisioned.