# 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](/compute/flexvm/creating-a-cloud-and-nodes.md). ## Using FlexVM API {% hint style="info" %} API URL prefix is {% endhint %} ### API Token Generate an API token, the procedure is documented in [API v3 Authentication](https://docs.i3d.net/game-hosting/overview/apiv3-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:** ```http 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" ] } ``` {% hint style="info" %} 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. {% endhint %} ## 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) ```http 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](https://registry.terraform.io/providers/i3dnet/i3dnet/latest/docs) 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](/game-hosting/overview/apiv3-authentication.md) **Example Usage:** ```hcl 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 john.doe@i3d.net"] } ``` --- # 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/getting-started-with-flexvm.md?ask= ``` 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.