Skip to content

[WIP] crd api #140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
lowzzz wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[WIP] crd api #140

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 26 additions & 62 deletions docs/build/api/cpu_cloud.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,96 +14,60 @@ For information on authentication and general request formatting, see the [API i

Base URL: `https://api.fluence.dev`

### Marketplace
### Compute

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/marketplace/offers` | Search for available offers |
| `GET` | `/marketplace/basic_configurations` | List available basic configurations |
| `GET` | `/marketplace/countries` | List available data center countries |
| `GET` | `/marketplace/hardware` | List available hardware specifications |
| `GET` | `/v1/marketplace/datacenters` | List available data centers |
| Method | Path | Description |
|--------|---------------------------------------|----------------------------------------------------------|
| `GET` | `/v1/datacenters` | List available datacenters |
| `GET` | `/v1/clusters` | List available clusters |
| `GET` | `/v1/clusters/{cluster_id}/resources` | List available resources and configurations in a cluster |

### Virtual machines

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/vms/v3` | Deploy one or more VMs |
| `GET` | `/vms/v3` | List running VMs |
| `GET` | `/vms/v3/status` | Get VM statuses and IP info |
| `PATCH` | `/vms/v3` | Update VM name and ports |
| `DELETE` | `/vms/v3` | Delete one or more VMs |
| `GET` | `/vms/v3/default_images` | List default OS images |
| `POST` | `/vms/v3/estimate` | Estimate deployment cost |

## Browse the marketplace

`POST /marketplace/offers` accepts optional filters in the request body. All filters are optional — send an empty `{}` to get all available offers.

Available filters: basic configuration, hardware specs (CPU, memory, storage), data center country, and maximum price per epoch.
| Method | Path | Description |
|---------|-----------------------------|--------------------------|
| `POST` | `/v2/vms` | Deploy a VM |
| `GET` | `/v2/vms ` | List VMs |
| `PATCH` | `/v2/vms` | Update VM name |
| `POST` | `/v2/vms/{vm_id}/terminate` | Terminate VM |
| `GET` | `/v1/default_images` | List default OS images |
| `POST` | `/v1/prices/cost` | Estimate deployment cost |

### Basic configurations

The API uses predefined configuration slugs that follow the pattern `cpu-{cores}-ram-{memory}gb-storage-{size}gb` (e.g., `cpu-4-ram-8gb-storage-25gb`). Each represents a fixed package of vCPU, RAM, and base storage. You can request additional storage on top.
The API uses predefined VM configuration slugs that follow the pattern `{configuration-family}-{vcpu_num}-{memory_gb}` (e.g., `cpu-regular-2vcpu-4gb`). Each represents a fixed package of vCPU and RAM. Storages and Public IPs are added on top of the basic configuration.

### Discovery endpoints

Use these to list valid filter values:
Use these to find out entities IDs required for deployment and management, as well as available configuration options:

- `GET /marketplace/basic_configurations` — available configuration slugs
- `GET /marketplace/countries` — ISO country codes with active offers
- `GET /marketplace/hardware` — available CPU architectures, memory types, storage types
- `GET /v1/datacenters` — available data center locations
- `GET /v1/clusters` — available clusters (groupings of hardware resources within data centers)
- `GET /v1/clusters/{cluster_id}/resources` — available resources and configurations within a cluster

:::info
`additionalResources` (extra storage beyond the basic configuration) can only be used together with the `hardware.storage` filter.
:::

:::tip
You can skip marketplace exploration entirely and just submit a deploy request with your constraints — the system will automatically match you with the best available offer.
:::

### Estimate cost

`POST /vms/v3/estimate` accepts the same constraints as the deploy endpoint plus an `instances` count, and returns the expected deposit amount and per-epoch pricing without committing to a deployment.
`POST /v1/prices/cost` estimates the cost of a deployment based on the specified configuration. The request body includes the cluster_id, vm configuration slug, storage type and public ips. The response returns the estimated total cost in USD.

## Deploy VMs

`POST /vms/v3` deploys one or more VMs. The request has three parts:

- **constraints** (optional) — same filters as marketplace search. If omitted or partially specified, the system auto-selects (smallest configuration, cheapest price).
- **instances** — number of VMs to deploy with this configuration.
- **vmConfiguration** — name, open ports, hostname, OS image URL, and SSH keys.
`POST /2/vms` deploys VMs. The request contain target cluster ID, VM configuration ID, name, SSH keys and optional parameters for storages (boot and data disks) public IPs. Existing entities are referenced by their IDs, while new ones are created on the fly based on the provided parameters. For example, you can specify a new storage by providing its type and size, or reference an existing one by ID.

Things to know:

- **OS image**: provide a download URL. Use `GET /vms/v3/default_images` for pre-built options, or supply your own (must be publicly downloadable; supported formats: `.qcow2`, `.img`, `.raw`, `.raw.xz`, `.raw.gz`, `.img.xz`, `.img.gz`).
- **Ports**: only port 22 (TCP) is open by default. You must explicitly specify any additional ports. Port 10250 is reserved.

- **SSH keys**: at least one key is required. You can provide a raw public key string or reference an existing key by name from your [SSH keys](./ssh_keys.md).

### After deployment

VMs start with in `New` and `Launching` status. Once provisioned (typically a few minutes), the status changes to `Active` and a public IP is assigned. Use `GET /vms/v3` or `GET /vms/v3/status` to check. Read more about instance statuses and transitions in [CPU Cloud concepts](../cpu_cloud/overview.md).
VMs start with in `New` and `Launching` status. Once provisioned (typically a few minutes), the status changes to `Launched`. Use `GET /v1/vms` with optional filter by vm ids to check. Read more about instance statuses and transitions in [CPU Cloud concepts](../cpu_cloud/overview.md).

## Manage VMs

### Update name and ports

`PATCH /vms/v3` accepts an array of updates, each targeting a VM by ID. You can change the name and/or open ports.
### Update name

:::warning
When updating `openPorts`, you must include **all** ports that should remain open. Any ports omitted from the update will be closed. This can lock you out if you forget to include port 22.
:::
`PATCH /v1/vms`provides a way to update the name of an active VM.

### Delete VMs

`DELETE /vms/v3` accepts an array of VM IDs to delete in a single request.

## Error responses

All CPU Cloud API errors return a JSON body with an `error` string:

```json
{
"error": "No suitable offer found"
}
```
`POST /v2/vms/{vm_id}/terminate` terminates a VM. The instance is deprovisioned and removed from your account.
76 changes: 5 additions & 71 deletions docs/build/cpu_cloud/manage_vm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,81 +12,15 @@ Each instance appears as a card with its name, location, hardware summary, IP ad

Click the three-dot menu on an instance card to access the available actions:

- **Edit VM name** — rename the instance.
- **Terminate** — stop the instance and end the rental agreement. Any unused reserved balance is returned to your account.
- **Edit name** — rename the instance.
- **Reboot** — restart the instance. Restart is required to apply certain changes, such as attaching a new storage or Public Ip. Rebooting does not affect the reserved balance or billing.
- **Remove** — stop the instance and end the rental agreement. Any unused reserved balance is returned to your account.

![Instance management](./assets/manage_vm/vm_manage.webp)

## Billing history

The history of your charges can be found on the **Billing page** in the **Billing History** section.
The history of your charges can be found on the **Billing page** in form of downloadable CSV files.

![Billing history](./assets/manage_vm/billing_history.webp)

## Handling provider-terminated instances

When a compute provider terminates an instance that you are actively using, the instance is moved to `Terminated` status.
Terminated instances are no longer accessible, and data stored on them is lost.
Even though a provider has terminated your instance, its record will still appear in your list with its balance reserved. You need to perform a final step to remove this record, which releases the funds back to your main balance.

### Reasons for termination

The Fluence compute marketplace sources from established compute providers with high standards of security and reliability supported by Tier 3 and 4 certifications. Termination is a last resort for providers when handling exceptions and usually results from adverse user behavior such as:

- Not paying for the instance (reserved balance reached 0)
- Violating the terms of service
- Using the instance for illegal activities or running malicious workloads

### Identification of terminated instances

Status updates about instance termination are available in the Fluence Console on the **Running Instances** page, or via the API when you request your active instances using the [list instances](../api/cpu_cloud.md#manage-vms) endpoint.

#### Fluence Console

**Banner notification.** You will see an informational banner on the Running Instances page with the message: _"Certain virtual machines were stopped by the provider. View details"_. Click **View details** to see the list of terminated instances.

**Status display.** The instance will be clearly marked with a `Terminated` status.

![Running Instances page with a banner notification and a terminated instance](./assets/manage_vm/terminated_vms_general.png)

**Filtering.** You can use the status filter on the Running Instances page and select `Terminated` to view only these instances.

![Running Instances page with a status filter](./assets/manage_vm/terminated_vms_filtered.png)

#### API

In the response from the list instances endpoint, the `status` field for the affected instance will be `"Terminated"`. The `publicIp` field will be `null`, and location information within the `datacenter` object may be absent.

```json
{
"id": "0x68bd60079721AE2A04759d00Fc516148aCF479e4",
"vmName": "apricot-wolf-5354",
"status": "Terminated",
"pricePerEpoch": "0.30697",
"resources": [ ... ],
"osImage": "...",
"datacenter": null,
"publicIp": null,
"ports": [
{
"port": 22,
"protocol": "tcp"
}
],
"reservedBalance": ".30697",
"totalSpent": "2.45576",
"createdAt": "2025-05-07T16:20:43Z"
}
```

### Finalization and reserved funds release

After identifying instances terminated by a provider, you need to finalize the termination to release the reserved funds:

#### Fluence Console

Click **Terminate** on the instance with `Terminated` status to remove its record and release its reserved funds. See [instance management](#instance-management) for details.

#### API

Use the [delete endpoint](../api/cpu_cloud.md#delete-vms) with the instance ID to remove its record and release its reserved funds.

65 changes: 29 additions & 36 deletions docs/build/cpu_cloud/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,55 +4,48 @@ sidebar_position: 0

# Concepts

Fluence CPU Cloud is a decentralized compute marketplace where you can rent virtual machine instances from enterprise-grade providers worldwide, predominantly in Tier-3 and Tier-4 data centers.
Fluence CPU Cloud is a compute marketplace where you can rent virtual machine instances from enterprise-grade providers
worldwide, predominantly in Tier-3 and Tier-4 data centers.

## Marketplace
## Workload types

The marketplace aggregates compute supply from independent providers. The marketplace connects you with providers through several layers:
Fluence CPU Cloud allows following workload to be deployed and managed:

- **Offer** — a listing from a provider that includes one or more compute peers with identical specifications, located in the same data center, available at a set price.
- **Compute peer** — a physical server referenced in an offer. Each peer has its own hardware resources and is the actual machine that runs your workload.
- **Resource** — a distinct resource on a peer: vCPU, RAM, storage, or public IP.
- **Hardware specification** — metadata describing a resource (CPU architecture, memory generation, storage medium, etc.).

Compute resources are currently allocated in multiples of a **compute unit** — 2 vCPUs and 4 GB of RAM. Storage starts at a minimum of 25 GB.
| Workload type | Description |
|-------------------|--------------------------------------------------------------------------------------------------------------------|
| `Virtual machine` | A virtualized compute instance with customizable resources (vCPU, RAM) |
| `Storage` | A block storage device that can be attached to a virtual machine for additional storage capacity or as a boot disk |
| `Public IP` | A public IPv4 address that can be attached to a virtual machine for external access |

## Instance lifecycle

Each instance goes through the following statuses during its lifetime:

| Status | Description |
|--------|-------------|
| `New` | Instance is created and is about to be provisioned |
| `Launching` | Instance is being provisioned, no public IP yet |
| `Active` | Instance is running and accessible |
| `SmallBalance` | Not enough funds for the next billing period |
| `InsufficientFunds` | Instance balance is 0 and the grace period passed |
| `Terminated` | Instance was terminated by the provider — workload is no longer running. See [provider termination handling](./manage_vm.md#handling-provider-terminated-instances). |
| `Stopped` | Instance was ended by the user |
| Status | Description |
|-----------------|----------------------------------------------------------------------------------------|
| `New` | Instance is created and is about to be provisioned |
| `Launching` | Instance is being provisioned by the provider — workload is not running yet |
| `Launched` | Instance is running and accessible |
| `Failed` | Instance failed to launch due to a provisioning error — workload is no longer running. |
| `Updating` | Instance is being updated after configuration changes |
| `Terminating` | Instance is being ended by the user or system |
| `Terminated` | Instance is terminated and the workload is no longer running |
| `Suspending` | Instance is being suspended by the user or system |
| `Suspended` | Instance was suspended |
| `Restarting` | Instance is being restarted by the user or system |
| `SoftRebooting` | Instance is being soft rebooted by the user or system |

## Billing model

CPU Cloud uses daily billing in USDC. Each instance has its own 24-hour billing period that starts at activation time and repeats every 24 hours.

### Instance balance

Every instance has its own reserved balance that covers ongoing rent. When you deploy an instance, the system deducts 2 days' worth of rent from your account — one day is charged immediately upon starting the instance, and the other stays as a reserve for the next billing period.

### Automatic top-ups of instance's balance

After each daily charge, the system automatically tops up the reserved balance from your account to maintain one day of reserve.

### Insufficient funds

If your account balance cannot cover a top-up, the system keeps retrying the top-up. Your instance continues running through any period that has already been paid for. Termination happens only when the next charge fails because the reserved balance has been fully spent.

### Refunds on termination

When you stop or terminate an instance, any unused funds on its reserved balance are returned to your account.
CPU Cloud uses hourly billing in USDC. Each instance has its own billing period that starts at activation time and
repeats every hour.
The system reports charges the user balance in the beginning of each billing period, and if the balance is insufficient,
user's vms are terminated. However, the storages are charged separately and are not terminated when the balance runs
out. If the balance is replenished, the user can deploy new instances and attach existing storages to them.

## OS images

You can use a pre-defined OS image from Fluence or provide a URL to a custom image. Custom images must be publicly downloadable and configured for remote instances.
You can use a pre-defined OS image from Fluence or provide a URL to a custom image for boot disks. Custom images must be
publicly downloadable and configured for remote instances.

Supported formats: `.qcow2`, `.img`, `.raw`, `.raw.xz`, `.raw.gz`, `.img.xz`, `.img.gz`.
Loading