Latest Content

How to Create a Cluster Using an Instance Template

Updated on 21 April, 2026

Create a Vultr cluster using a reusable instance template that defines the plan, OS, SSH keys, and startup script for consistent deployments.

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 
    $ curl "https://api.vultr.com/v2/instances/templates" \
    -X GET \
    -H "Authorization: Bearer ${VULTR_API_KEY}"

    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 
    $ 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
    }'

    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 
    $ curl "https://api.vultr.com/v2/clusters/{cluster-id}" \
    -X GET \
    -H "Authorization: Bearer ${VULTR_API_KEY}"

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

Comments