Managing your Virtual Machines

After deploying virtual machines on the Fluence marketplace, you'll need to monitor and manage them throughout their lifecycle. This guide explains how to view your active VMs, understand their status, and perform management operations like deletion when needed.

In this guide, we'll walk through how to:

1. View your active VMs
2. Understand VM status and resource details
3. Delete VMs when they are no longer needed

Viewing Your Active VMs

To view all your currently active virtual machines, you can use the following API endpoint:

GET https://vodopad.mainnet.fluence.dev/vms/v2 // TODO: change to api.fluence.dev once the new API is deployed

Response structure

The response contains an array of VM objects, each representing a virtual machine you have deployed. Each VM object includes detailed information about its configuration, status, and the resources allocated to it.

Example of a VM object in the response:

{
  "id": "0x0000000000000000000000000000000000000001",
  "vmName": "vm-name",
  "status": "ACTIVE", // TODO: maybe add `LAUNCHING` to reflect Console UI statuses
  "pricePerEpoch": 298160, // TODO: field without precision - may be changed to string with precision 6
  "resources": [
    {
      "type": "VCPU",
      "quantity": 2,
      "details": {
        "model": "7702p"
      },
      "metadata": {
        "architecture": "Zen",
        "brand": "EPYC",
        "generation": "2",
        "manufacturer": "AMD"
      }
    },
    {
      "type": "RAM",
      "quantity": 4096, // TODO: quantity is in MiB. So it's not very readable
      "details": {
        "manufacturer": "Samsung",
        "model": "DGX",
        "speed": 3600
      },
      "metadata": {
        "generation": "4",
        "type": "DDR"
      }
    },
    {
      "type": "STORAGE",
      "quantity": 25600,
      "details": {
        "manufacturer": "WD",
        "sequentialWriteSpeed": 15000
      },
      "metadata": {
        "type": "SSD"
      }
    },
    {
      "type": "PUBLIC_IP",
      "quantity": 1,
      "details": {},
      "metadata": {
        "version": "4"
      }
    }
  ],
  "createdAt": "+002025-04-01T16:50:57.000000000Z",
  "nextBillingAt": "+002025-04-16T17:59:55.000000000Z",
  "osImage": "https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img",
  "datacenter": {
    "id": "0x0000000000000000000000000000000000000000000000000000000000000005",
    "countryCode": "FR",
    "cityCode": "PAR",
    "cityIndex": 1,
    "tier": 4,
    "certifications": ["PCI DSS", "ISO 9001:2015", "ISO/IEC 27001:2022"]
  },
  "publicIp": "154.42.3.159",
  "ports": [
    {
      "port": 22,
      "protocol": "tcp"
    }
  ],
  "reservedBalance": "359440",
  "totalSpent": "17846000"
}

Let's break down the key components of each VM object:

Response Fields

Basic VM Information

• id: The unique identifier for the VM on the Fluence network
• vmName: The name you assigned to the VM when creating it
• status: Current operational status of the VM (currently - only ACTIVE is shown) // TODO: maybe add LAUNCHING to reflect Console UI statuses
• pricePerEpoch: The cost of the VM per epoch (24 hours) in USDC (with 6 decimals)
• createdAt: Timestamp indicating when the VM was created
• nextBillingAt: Timestamp indicating when the next billing cycle will start
• osImage: URL of the operating system image used for the VM
• publicIp: The public IP address assigned to your VM
• reservedBalance: The amount of USDC (with 6 decimals) currently reserved for this VM's operation
• totalSpent: The total amount of USDC (with 6 decimals) spent on this VM since creation

Datacenter Information

The datacenter object provides detailed information about where your VM is physically hosted:

"datacenter": {
  "id": "0x0000000000000000000000000000000000000000000000000000000000000005",
  "countryCode": "FR",
  "cityCode": "PAR",
  "cityIndex": 1,
  "tier": 4,
  "certifications": ["PCI DSS", "ISO 9001:2015", "ISO/IEC 27001:2022"]
}

• id: Unique identifier for the datacenter
• countryCode: ISO country code where the datacenter is located
• cityCode: LOCODE code for the city
• cityIndex: Index if multiple datacenters exist in the same city
• tier: Datacenter tier level (1-4, with 4 being highest reliability)
• certifications: Array of compliance certifications this datacenter holds

Network Configuration

The ports array indicates which network ports are open on your VM:

"ports": [
  {
    "port": 22,
    "protocol": "tcp"
  }
]

• port: The port number that is open
• protocol: The network protocol for this port (e.g., "tcp", "udp")

Open ports are essential for accessing services running on your VM. For example, port 22 is typically used for SSH access.

Resources

The resources array contains detailed information about all resources allocated to your VM. Each resource is represented by an object with the following fields:

• type: The type of resource, which can be one of:
  • VCPU: Virtual CPU cores
  • RAM: Memory in MB
  • STORAGE: Disk space in MB
  • PUBLIC_IP: Public IP address
  • NETWORK_BANDWIDTH: Network bandwidth allocation
• quantity: The amount of this resource allocated to the VM (units depend on the resource type)
• metadata: Categorization and descriptive information about the resource. Corresponds to hardware resource characteristics from Hardware Specifications
• details: Additional technical specifications about the resource. This field is optional for compute providers and may be empty or contain arbitrary data.

Deleting a VM

When you no longer need a VM, you can delete it to release the resources and stop incurring charges. To delete a VM, use the following API endpoint:

DELETE https://api.fluence.dev/vms/v3

Request Format

To delete a VM, you need to specify its ID in the request body:

{
  "vmId": "0x0B08D9233ed01f4697d4b6C5814bc6d9f0cB8F99"
}

Where:

• vmId: The unique identifier of the VM you want to delete (from the list of your active VMs)

A successful deletion request will return a 200 status code. The VM will be marked for deletion and will no longer appear in your list of active VMs once the deletion process is complete.

info

You will be billed for the resources for each epoch of utilization. This means that if an epoch changes at 5:55 PM UTC and you delete the VM at 6:00 PM UTC, you will be charged for work in epoch started at 5:55 PM UTC as well.