How to Create a Cluster Using an Instance Template

Instance templates define a reusable blueprint for instances including the plan, OS, SSH keys, startup script, VPC, and storage configuration. Using a template when creating a cluster ensures consistent deployments and simplifies scaling.

This guide explains how to create a cluster using an existing instance template via the Vultr API. To create a cluster by specifying a plan directly, see How to Create a Cluster.

1. Send a GET request to the List Instance Templates endpoint to retrieve all available templates. If you do not have a template, create one by following How to Create an Instance Template.

   CONSOLE

   Copy

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

   Explain Code

   Powered by Vultr AgentBeta

   Note the id of the template you want to use.

2. Send a POST request to the Create Cluster endpoint to create a new cluster using the template. Replace REGION with the region identifier, TEMPLATE-ID with the instance template id, and CLUSTER-LABEL with a descriptive name. Set type to vps, bare-metal, or gpu-fabric depending on your cluster configuration. 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",
           "instance_template": "TEMPLATE-ID",
           "label": "CLUSTER-LABEL",
           "type": "vps",
           "min_pool_count": 2,
           "desired_pool_count": 2,
           "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.