Cluster Deployment using APIs

Step-by-step guide for developers to deploy, price, and manage GPU clusters programmatically using io.net Cloud VMaaS APIs.

This page outlines the end-to-end flow for deploying a GPU cluster using io.net Cloud VMaaS APIs. It is intended to help you understand the steps you can take and API calls needed to provision, price, and manage a cluster programmatically.

Workflow Summary

The cluster deployment process consists of the following steps:

1. Retrieve available hardware

   Use the GET Hardware List endpoint to fetch all supported GPU hardware configurations, including available GPU counts, locations, and resource specifications.

2. Select hardware and configuration
   From the hardware list response, select the desired hardware type, number of GPUs per VM, and deployment region.

3. Validate deployment pricing (optional)
   Use the GET Deployment Price endpoint to calculate the expected cost for the selected hardware configuration and duration.

4. Deploy the cluster

   Use the POST Deploy VM endpoint to provision the cluster using the selected hardware, GPU count, location, and duration.

5. Manage the cluster lifecycle

   After deployment, manage the cluster using one of the following endpoints:

   • POST Extend Cluster endpoint to increase the deployment duration.
   • DELETE Destroy Deployment endpoint to terminate the cluster early.

The first hour of usage is non-refundable.

1. Retrieving Available Hardware

   Using the GET Hardware List endpoint, retrieve all currently available GPU hardware configurations.

   Request Example

   curl -X 'GET' \
     'https://api.io.solutions/enterprise/v1/io-cloud/vmaas/hardware' \
     -H 'accept: application/json' \
     -H 'x-api-key: <api-key>'
   

   Response Example

   {
       "data": {
           "hardware": [
               {
                   "id": "12__2",
                   "deploy_id": 12,
                   "name": "GeForce RTX 4090",
                   "num_cards": 2,
                   "supplier": "internal",
                   "sold_out": false,
                   "price": 0.6,
                   "vram_per_card": 24,
                   "interconnect": null,
                   "nvlink": false,
                   "storage": 1000,
                   "vcpu": 39,
                   "memory": 125,
                   "location": "US"
               },
               {
                   "id": "12__1",
                   "deploy_id": 12,
                   "name": "GeForce RTX 4090",
                   "num_cards": 1,
                   "supplier": "internal",
                   "sold_out": false,
                   "price": 0.3,
                   "vram_per_card": 24,
                   "interconnect": null,
                   "nvlink": false,
                   "storage": 500,
                   "vcpu": 39,
                   "memory": 125,
                   "location": "US"
               },
               {
                   "id": "B200_sxm6x8__US",
                   "deploy_id": "B200_sxm6x8",
                   "name": "B200",
                   "num_cards": 8,
                   "supplier": "external",
                   "sold_out": false,
                   "price": 39.92,
                   "vram_per_card": 192,
                   "interconnect": "sxm6",
                   "nvlink": false,
                   "storage": 22528,
                   "vcpu": 208,
                   "memory": 2900,
                   "location": "US"
               },
               {
                   "id": "B200_sxm6x8__AU",
                   "deploy_id": "B200_sxm6x8",
                   "name": "B200",
                   "num_cards": 8,
                   "supplier": "external",
                   "sold_out": false,
                   "price": 39.92,
                   "vram_per_card": 192,
                   "interconnect": "sxm6",
                   "nvlink": false,
                   "storage": 22528,
                   "vcpu": 208,
                   "memory": 2900,
                   "location": "AU"
               }
           ]       
        }
   }
   
2. Selecting your Hardware and Configuration

   From the response of the GET Hardware List endpoint, select your chosen GPU and save the following values:

   deploy_id · string/integer · required

   Hardware identifier used for pricing and deployment. Can be a string or integer.

   num_cards · integer · required

   Number of GPUs per VM.

   location · string · required

   Deployment region.

3. Validating your Deployment Price (Optional)

   Using the GET Deployment Price endpoint and the values you have saved, validate the price of your desired deployment before you deploy your cluster.

   Request Example

   curl -X GET "https://api.io.solutions/enterprise/v1/io-cloud/vmaas/price" \
     -H "x-api-key: YOUR_API_KEY" \
     --data-urlencode "hardware_id=12" \
     --data-urlencode "gpus_per_vm=1" \
     --data-urlencode "replica_count=1" \
     --data-urlencode "duration_hours=1" \
     --data-urlencode "currency=usdc" \
     --data-urlencode 'location_ids=["US"]'
   

   Ensure that the following fields have been assigned a value:

   hardware_id · string/integer · required

   Value of deploy_id from the Hardware List response.

   gpus_per_vm · integer · required

   Number of GPUs per VM. Value of num_cards from the Hardware List response.

   duration_hours · integer · required

   Duration of your deployment, in hours.

   currency · string · required

   Pricing currency.

   Example: usdc

   location_ids · string · required

   URL-encoded JSON array of locations. Use --data-urlencode in your cURL request if you use a plain string.

   Example: %5B%22US%22%5D = ["US"]

4. Deploying your Cluster

   Using the POST Deploy VM enndpoint, deploy your selected hardware for the specified duration.

   Request Example

   curl -X POST "https://api.io.solutions/enterprise/v1/io-cloud/vmaas/deploy" \
     -H "Content-Type: application/json" \
     -H 'x-api-key: <api-key>'
     -d '{
       "resource_private_name": "name of cluster",
       "duration_hours": 1,
       "gpus_per_vm": 1,
       "hardware_id": 12,
       "location_ids": ["US"],
       "ssh_keys": {
         "name of key": "<public-key>"
       }
     }'
   

   Ensure that the following fields have been assigned a value:

   resource_private_name · string · required

   The name of your cluster.

   duration_hours · integer · required

   Duration of your deployment, in hours.

   gpus_per_vm · integer · required

   Number of GPUs per VM. Value of num_cards from the Hardware List response.

   hardware_id · string/integer · required

   Value of deploy_id from the Hardware List response.

   location_ids · string · required

   Location of your chosen GPU.

   ssh_keys · object · required

   Your public SSH key, use RSA, ECDSA, or ED25519.

   Format: "name of key": "<public-key>"