Volumes

Volume responses return source_image and source_snapshot as resource references with id, crn and optional name. Each is null when the volume has no source of that kind. The same fields appear when reading the volume through an instance’s attached-volume collection.

Creating a volume

Creation is asynchronous. POST /v1/volumes answers 202 with the volume in creating; poll GET /v1/volumes/{volume_id} until status becomes available or error. error means an active error fault — read faults. See Resource faults.

Console
API
CLI
Go

Go to Storage → Volumes and choose Create Volume. Give it a Name, leave Source on Blank volume, then set Size (GB) and pick a Tier — SSD or NVMe. The Tags card takes the same key/value pairs the API does.Both tiers include 3,000 IOPS and 125 MiB/s, independent of size. You can provision additional IOPS and throughput in the performance fields.

POST https://storage.sa-saopaulo-1.basaltic.sh/v1/volumes
{
  "name": "app-data-01",
  "volume_type": "ssd",
  "size_gb": 100,
  "tags": { "env": "production" }
}

basaltic storage volume create \
  --name app-data-01 --volume-type ssd --size-gb 100 \
  --tags env=production

cfg, err := basaltic.NewConfig(ctx,
    basaltic.WithClientCredentials(os.Getenv("BASALTIC_ACCESS_KEY_ID"), os.Getenv("BASALTIC_SECRET_ACCESS_KEY")),
    basaltic.WithRegion("sa-saopaulo-1"),
)
if err != nil {
    log.Fatal(err)
}

vol, err := storage.New(cfg).CreateVolume(ctx, &storage.VolumeCreateRequest{
    Name:       "app-data-01",
    VolumeType: "ssd",
    SizeGB:     100,
    Tags:       storage.Tags{"env": "production"},
})

The call returns with the volume in creating; poll GetVolume until it reaches available.

unique within your account

Matches ^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$. It appears in the CRN, so it has to be URL-safe. A duplicate name is 409 VOLUME_NAME_EXISTS. The name is fixed after creation because IAM policies address the volume by its CRN. Updates containing name return a validation error, including unchanged, empty or null values. Existing volumes retain their current names.

1–16384

required

The ceiling matches what a single block device is capped at elsewhere in the industry. It is a per-volume sanity bound, not your quota — aggregate usage is gated separately.

ssd | nvme

required

See below. GET /v1/volume-types lists exactly what you may create on.

Send an Idempotency-Key header. Retrying with the same key returns the original outcome instead of creating a second volume; reusing the key with a different body is rejected with 422.

Volume types

GET /v1/volume-types lists the available storage tiers. New volumes on both tiers include 3,000 IOPS and 125 MiB/s, independent of capacity.

ssd

SSD block storage with 3,000 IOPS / 125 MiB/s included.

nvme

NVMe block storage with 3,000 IOPS / 125 MiB/s included.

The limits apply to reads and writes combined, per volume. Whichever limit the workload reaches first determines its maximum rate. All volumes have sustained limits without burst credits. Increasing capacity does not increase IOPS or throughput. Existing and new volumes include exactly 3,000 IOPS / 125 MiB/s, with no capacity-based exceptions or burst credits. Additional performance is enabled only when you explicitly provision it. The volume’s included_io_limits response and its console details show this fixed baseline. bytes_per_sec is expressed in bytes per second; 125 MiB/s is 131,072,000 bytes per second.

These limits are performance ceilings, not a latency guarantee. Actual results depend on operation size, concurrency, the guest workload and available storage capacity. At 4 KiB per operation, 3,000 IOPS is approximately 11.72 MiB/s; reaching 125 MiB/s requires larger operations.

The type is fixed at creation, and there is no call that changes it. Moving to a different tier means creating a volume of the type you want and copying the data across from inside the guest.

Provisioning more performance

Increase IOPS, throughput, or both without increasing disk capacity or restarting your instance. The selectable totals for a standard volume are:

Tier	Included IOPS / MiB/s	Maximum IOPS / MiB/s
SSD	3,000 / 125	8,000 / 250
NVMe	3,000 / 125	12,000 / 500

Additional performance costs R $0.02 per IOPS-month** and **R$ 0.20 per MiB/s-month, above the included 3,000 IOPS / 125 MiB/s. The same rates apply to both tiers. At 3,000 IOPS and 500 MiB/s, a standard NVMe volume adds R

75 for a full month; at 12,000 IOPS and 500 MiB/s it adds R

255. Storage capacity is billed separately. Read the current rates from the public price catalog, filtered with resource_type=volume-performance. Charges are prorated from when a setting is applied, using elapsed time in the actual UTC billing month. You pay for the provisioned allocation even while a volume is detached or its instance is stopped. Actual operations and transferred bytes do not determine this charge. Returning to the included allowance removes the extra charge once the lower limits are applied; deleting the volume also ends the allocation.

Console
API
CLI
Go

Open the volume in Storage → Volumes and choose Change performance. Set Provisioned IOPS and Provisioned throughput (MiB/s), review the additional monthly price, and apply the change. Use included performance restores the included values in the form; apply them to remove the add-on.You can also choose these settings when creating a volume. The Summary shows Additional performance separately from storage capacity and adds it once to the total. For example, 3,500 IOPS / 250 MiB/s adds R$35/month. Instance creation offers the same controls for each new boot and data disk.

POST https://storage.sa-saopaulo-1.basaltic.sh/v1/volumes/{volume_id}/performance
{
  "iops": 6000,
  "throughput_mib_s": 250
}

Send an Idempotency-Key header for safe retries. To select performance during creation, put the same fields in the request’s performance object.

basaltic storage volume update-performance <volume-id> \
  --iops 6000 --throughput-mib-s 250 \
  --idempotency-key report-volume-performance-1

iops, throughput := 6000, 250.0
vol, err := storage.New(cfg).UpdateVolumePerformance(ctx, volumeID,
    &storage.VolumePerformanceRequest{
        IOPS:           &iops,
        ThroughputMiBS: &throughput,
    }, basaltic.WithIdempotencyKey("report-volume-performance-1"))

The API returns 202. While the change is pending, the volume has status updating. performance.requested is the target, while performance.applied is the acknowledged setting. Poll until the requested and applied limits match. Those objects express throughput as bytes_per_sec. The old applied rate continues to be billed while a change is pending. Failures appear in faults and set the volume status to error; the change is retried automatically. At least one dimension is required for an update; omitted dimensions retain their current values. Use whole IOPS and MiB/s. An exact fractional legacy throughput allowance can also be selected to remove extras. Values must stay between the volume’s included allowance and the tier ceiling; any higher included allowance remains available without an extra charge. Resize, restart, reattachment and migration preserve your selection. An increase also requires account quota, regional capacity and healthy storage. A rejected increase does not create a new billable allocation. If another change is pending, retry the same target or wait for it to finish before choosing a different target. These remain combined read/write ceilings on shared storage, not a dedicated reservation or a latency guarantee.

Attaching to an instance

Attachment is a compute operation — the device binding, the guest hot-plug and the boot order all live on the instance side:

Console
API
CLI
Go

Open the volume from Storage → Volumes and choose Attach to instance. Pick the Instance; Device name, Mount path and Filesystem are optional. Leaving Device name blank assigns the next available name, and setting a Mount path mounts the volume there inside the guest — formatting it first only if it is blank.

POST /v1/instances/{instance_id}/volumes
{ "volume": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }

basaltic compute instance attach-volume <instance-id> --volume <volume-id>

--device, --mount-path and --fstype are optional and behave as the console’s fields do.

att, err := compute.New(cfg).AttachInstanceVolume(ctx, instanceID,
    &compute.AttachInstanceVolumeRequest{
        Volume: volumeID,
    })

Attachment lives on the compute client, not storage — the device binding and boot order belong to the instance.

The volume moves from available to in_use, and detaching puts it back to available. See compute for the device slots, mount options and the detach call.

A volume attaches to one instance at a time. There is no multi-attach: the binding is unique per volume, so a second attach is refused rather than handing two guests the same block device.

What happens when the instance is deleted

Each attachment carries a delete_on_termination flag, and the default differs by how the volume got there:

Volume	`delete_on_termination`	Result when the instance is deleted
Boot volume created with the instance	`true`	Destroyed with the instance.
Data volume you attached	`false`	Survives, returns to `available`.

PATCH /v1/instances/{instance_id}/volumes/{volume_id} changes the flag on an existing attachment. Set it deliberately on anything holding data you care about — the boot volume default is the one that deletes. In the console the flag is a Delete on termination switch in the instance’s list of attached volumes, not on the volume’s own page. It belongs to the attachment, so that is where it lives. The boot disk itself cannot be detached: unplugging it would take the guest’s root filesystem with it, so the call is refused. You can grow it while attached.

Growing a volume

Console
API
CLI
Go

Open the volume and choose Extend, or use the Extend row action on Storage → Volumes. The Extend Volume dialog shows Current Size and takes a New Size (GB).

POST /v1/volumes/{volume_id}/extend
{ "new_size_gb": 200 }

basaltic storage volume extend <volume-id> --new-size-gb 200

vol, err := storage.New(cfg).ExtendVolume(ctx, volumeID, &storage.VolumeExtendRequest{
    NewSizeGB: 200,
})

The call answers 202 with the volume in extending and returns to available for a detached volume or in_use for an attached volume, at the new size. Boot and data volumes can grow with the instance running or stopped; no detach is needed. new_size_gb must be strictly greater than the current size; anything else is 400 VOLUME_SIZE_INVALID.

A volume cannot shrink. There is no call that reduces size_gb, and the quota you committed at the larger size stays committed. Grow in the steps you actually need.

Growing the volume does not grow its partition or filesystem. Wait until the volume leaves extending, then check the device size inside the guest:

lsblk -o NAME,SIZE,FSTYPE,MOUNTPOINTS

The instance’s block device is refreshed automatically. If the guest still shows the old size, use the rescan method supported by its device driver, or restart the instance. For a driver exposing a rescan file (not all virtio block devices do), the command is:

# Only if this file exists and vda is the volume you extended:
echo 1 | sudo tee /sys/class/block/vda/device/rescan

For an ext4 filesystem directly on partition 1 of /dev/vda, with free space immediately after that partition, the following grows the partition and filesystem. Confirm the device and layout with lsblk first and take a backup. These commands run inside your instance; they are not run by the service.

sudo growpart /dev/vda 1
sudo resize2fs /dev/vda1

For an unpartitioned ext4 volume, run resize2fs on the volume’s device instead and skip growpart. XFS, LVM, encrypted disks and other partition layouts need their own growth steps; do not use the ext4 example for them.

Deleting a volume

DELETE /v1/volumes/{volume_id} answers 202, flips the row to deleting and tears the volume down asynchronously. Poll until the volume disappears. Two refusals to know about:

409 VOLUME_IN_USE

The volume is attached. Detach it from the instance first. Delete is also refused during the transient states — creating, extending, deleting — so a second operation cannot race the first.

409 VOLUME_HAS_SNAPSHOTS

A volume that still has snapshots will not delete, because those snapshots are children of the volume’s data and removing the parent underneath them is not possible. Delete the snapshots first, then the volume.This is a clean refusal rather than a partial teardown, so nothing is lost by trying.

Deleting a volume also removes all its snapshot policies — the schedules have nothing left to snapshot. Your quota is released once the teardown finishes, not when the call is accepted, so capacity and your reported usage stay aligned while a delete is in flight.

Get started

Products

Platform

Help

Creating a volume

Volume types

ssd

nvme

Provisioning more performance

Attaching to an instance

What happens when the instance is deleted

Growing a volume

Deleting a volume

​Creating a volume

​Volume types

ssd

nvme

​Provisioning more performance

​Attaching to an instance

​What happens when the instance is deleted

​Growing a volume

​Deleting a volume

Creating a volume

Volume types

Provisioning more performance

Attaching to an instance

What happens when the instance is deleted

Growing a volume

Deleting a volume