# FlexVM

## Introduction

FlexVM (Flex Virtual Metal) extends the existing FlexMetal bare metal provisioning platform with a managed virtual machine layer. It enables customers to provision GPU-accelerated and general purpose VMs on dedicated hardware through the same API, Terraform provider, and consumption model they already use for FlexMetal bare metal.

The service targets workloads that require near-bare-metal performance with the operational flexibility of virtual machines: game build pipelines, CI/CD, rendering, AI inference, and any workload where GPU/NVMe passthrough and per-tenant isolation are non-negotiable.

FlexVM is not a shared multi-tenant cloud. Each customer's VMs run on hardware exclusively allocated to them. The virtualization layer exists solely to subdivide dedicated machines into deterministic, isolated units with direct hardware access.

## Core Concepts

<table data-header-hidden><thead><tr><th width="212" valign="top">Concept</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top">Tenant</td><td valign="top">i3D.net customer identification (also known as K#)</td></tr><tr><td valign="top">Cloud</td><td valign="top">Your isolated environment (pre‑created). Contains nodes, VMs, and capacity. Tenants have 1 or more Clouds</td></tr><tr><td valign="top">Node</td><td valign="top">A physical compute host inside your cloud. Clouds have 1 or more Node</td></tr><tr><td valign="top">Image</td><td valign="top">An OS template used to create VMs (e.g., Ubuntu 22.04, Windows Server)</td></tr><tr><td valign="top">Instance Type</td><td valign="top">A predefined hardware profile (CPU, RAM, disk, GPU) for VMs</td></tr><tr><td valign="top">VM</td><td valign="top">A virtual machine instance running in your cloud</td></tr><tr><td valign="top">Command</td><td valign="top">An action you can execute on a VM (e.g., start, stop, reboot)</td></tr></tbody></table>

## Prerequisites

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

· Tenant (K#): your unique organisation identifier.

o The Tenant will have it’s own VLAN and IP Prefixes already assigned to.

· FlexVM Cloud: a dedicated cloud resource pool with compute capacity assigned to your tenant.

This diagram below explains the resource hierarchy.

<figure><img src="/files/1GqTHr8jBn2Dbypsa5W0" alt=""><figcaption></figcaption></figure>

## Using FlexVM

For the full API specifications, see <https://docs.i3d.net/api/api_flexvm>

Note: API URL prefix is <https://api.i3d.net>

### API Token

Generate an API token, the procedure is documented in [API v3 Authentication](https://docs.i3d.net/game-hosting/overview/apiv3-authentication)

1. Add IP whitelisting for security (whitelist the IP addresses that will access the API)
2. Include your API key in every request using this HTTP header:

<table data-header-hidden><thead><tr><th valign="top">HTTP Header NameText</th><th valign="top">HTTP Header ValueText</th></tr></thead><tbody><tr><td valign="top">PRIVATE-TOKEN</td><td valign="top">YOUR_API_KEY</td></tr></tbody></table>

### Pagination

Use the RANGED-DATA header to control result sets (default: start=0, results=25).

All GET endpoints that return collections support this header.

### Using FlexVM Terraform Provider

The i3dnet provider includes the resource to manage FlexVM: i3dnet\_flexvm\_vm\
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.15c.248g"
  image_name         = "ubuntu-2404-server-amd64"
  ssh_keys           = ["ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHwdgjY0AlmkeLknBpoVmJg/quNSifyBHEK1MREpV4Ri john.doe@i3d.net"]
}
```

### Explore Your Environment

#### 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.15c.248g",
    "name": "development.ubuntu-2404",
    "ssh_keys": [
        "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTuRa6Gtysdg2EF+SIXheVFVpHJrKYs4kWfNoHQg8ZG6PH4= ecdsa-key-20240131"
        ],
    "tags": [
        "project:odyssey",
        "env:build"
        ]
}
```

**Response**

A successful call returns `201 Created` with the VM object, including its `vmUuid` and an initial status of `provisioning`.

{% hint style="info" %}
The VM transitions through `provisioning` → `starting` → `running`. You can monitor its status using the **GET VM** endpoint.
{% endhint %}

#### Manage Your VMs

* **List Your Clouds**
  * You should see one cloud with its UUID, name, and capacity details.
  * `GET /v3/flexVM/clouds`
* **Get Cloud Details**
  * `GET /v3/flexVM/clouds/{cloudUuid}`
* **List Nodes in Your Cloud**
  * Nodes represent the underlying compute hosts.
  * `GET /v3/flexVM/clouds/{cloudUuid}/nodes`
* **List Available Images**
  * Images are templates you can use when creating a VM.
  * `GET /v3/flexVM/images`
* **List Available Instance Types**
  * Instance types define VM size (vCPU, RAM, disk).
  * `GET /v3/flexVM/instanceTypes`

#### Monitor Monthly Usage

Retrieve a usage report for your organisation (tenant) over a specified period.

`GET /v3/flexVM/reports/monthly?start=2026-01-01T00:00:00Z&end=2026-02-01T00:00:00Z`

* start (inclusive) and end (exclusive) – ISO 8601, UTC.
* If omitted, the period defaults to the current calendar month.

The report includes total VM created, VM released, VM hours, aggregated by VM tags (if applicable).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.i3d.net/compute/flexvm-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.