Getting started with FlexVM

Prerequisites

Before you begin, the i3D team has already set up the following for you:

• Tenant (K#) : your unique organization identifier.

  • Each Tenant will have it’s own VLAN and IP Prefixes already assigned to.

• FlexVM Cloud : a dedicated resource pool with compute capacity assigned to your Tenant.

  • You can also create and delete clouds yourself; see Creating a Cloud and Nodes.

Using FlexVM API

API URL prefix is https://api.i3d.net

API Token

Generate an API token, the procedure is documented in API v3 Authentication

• Add IP whitelisting for security (whitelist the IP addresses that will access the API

• Include your API key in every request using this HTTP header:

HTTP Header Name	HTTP Header Value
PRIVATE-TOKEN	YOUR_API_KEY

Pagination

Use the RANGED-DATA header to control result sets (default: start=0, results=25). All GET endpoints that return collections support this header.

Step 1 : Explore Your Environment

• List Your Clouds :

  • GET /v3/flexVM/clouds

  • You should see one cloud with its UUID, name, and capacity details.

• Get Cloud Details :

  • GET /v3/flexVM/clouds/{cloudUuid}

  • Get the details of one specific Cloud

• List Nodes in Your Cloud :

  • GET /v3/flexVM/clouds/{cloudUuid}/nodes

  • Nodes represent the underlying compute hosts.

  • This list the physical server Nodes that are enrolled in the Cloud

• List Available Images :

  • GET /v3/flexVM/images

  • Images are templates you can use when creating a VM.

• List Available Instance Types :

  • GET /v3/flexVM/instanceTypes

  • Instance types defined VM size (vCPU, RAM, disk, pcieDevice passthrough).

Step 2 : Create Your First VM

Use the POST /v3/flexVM/clouds/{cloudUuid}/vms endpoint with a JSON body.

Example request:

POST /v3/flexVM/clouds/{cloudUuid}/vms
Host: api.i3d.net
PRIVATE-TOKEN: YOUR_API_KEY
Content-Type: application/json

{
  "description": "DB1 VM",
  "image_name": "ubuntu-2404-server-amd64",
  "instance_type_name": "vm.gpu.1rtx4000.30c.240g",
  "name": "development.ubuntu-2404",
  "ssh_keys": [
    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTuRa6Gtysdg2EF+SIXheVFVpHJrKYs4kWfNoHQg8ZG6PH4= ecdsa-key-20240131"
  ],
  "tags": [
    "project:odyssey",
    "env:build"
  ]
}

Response (201 Created) returns the VM object including its vmUuid and initial status (provisioning). The VM will transition through provisioning → starting → running. You can monitor its status using the GET VM endpoint.

Step 3 : Manage Your VMs

• List VMs in your Cloud :

  • GET /v3/flexVM/clouds/{cloudUuid}/vms?status=running

  • Optionally filter by status (e.g., running, stopped).

  • This will show timestamp of VM Creation or Deletion alongside IP address and Node

• Get a Specific VM :

  • GET /v3/flexVM/clouds/{cloudUuid}/vms/{vmUuid}

  • This will list only the details of the specified VMuuid

• Execute a Command on a VM :

  • POST /v3/flexVM/clouds/{cloudUuid}/vms/{vmUuid}/commands

  • Supported commands: start, stop, reboot, pause, resume

• Delete a VM

  • DELETE /v3/flexVM/clouds/{cloudUuid}/vms/{vmUuid}

  • This will immediately wipe the LVM disk and the passthrough NVME (if any)

Step 4 : Monitor Monthly Usage

This endpoint will retrieve all usage data across all your Cloud within the time period (default is current calendar month)

GET /v3/flexVM/reports/monthly?start=2026-01-01T00:00:00Z&end=2026-02-01T00:00:00Z
Host: api.i3d.net
PRIVATE-TOKEN: YOUR_API_KEY
Content-Type: application/json
{
}

The usage is displayed according to different aggregates

• by_tag

  • active_vms : number of currently active VM

  • tag : (example env:test)

  • total_vm_hours : total number of hours VM have run

  • total_vms_created : total number of VM created

  • total_vms_released : total number of VM released

• clouds

  • For each Cloud, same as by_tag

• vms

  • Full list of VMs with timestamp for Creation and Deletion

    • cloud_id : Uuid of the Cloud in which the VM was created

    • image : Image name of the VM (e.g. ubuntu-2404-server-amd64)

    • name : Name of the VM

    • plan : InstanceType of the VM

    • site : Site Location of the VM (tied to Cloud)

    • status : Operational Status (e.g. created, deleted, failed, stopped...)

    • tags : Optional array of tags

    • vm_hours : Number of running hours of the VM

Using FlexVM Terraform Provider

FlexVM can be used through our API, or through our Terraform provider.

Refer to the i3D.net Terraform Documentation for more information.

Similar to the API endpoint, you'll need an API token for using the Terraform provider. The procedure is documented in API v3 Authentication

Example Usage:

resource "i3dnet_flexvm_vm" "my-vm" {
  cloud_id           = "019256ab-1554-73a7-b091-f024b0a724ea"
  name               = "test-gaming-vm1"
  description        = "Test Gaming VM 1"
  instance_type_name = "vm.gpu.1rtx4000.30c.240g"
  image_name         = "ubuntu-2404-server-amd64"
  ssh_keys           = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwdgjY0AlmkeLknBpoVmJg/quNSifyBHEK1MREpV4Ri [e-mail]"]
}