Volume Set - Control Plane

Overview

A volume set is a collection of storage volumes, which may be linked to one or more workloads running on Control Plane. The behavior varies greatly depending on your choice of filesystem.

Traditional File Systems (ext4, xfs)

Control Plane provisions a unique volume for each replica in the linked workload.
Each volume set can be used by at most one workload, which must be of type stateful or vm.
Each volume in the set is bound to a single workload replica
Data is not replicated between volumes. If you require data sharing or replication, this must be accomplished at the application level (e.g. by using WAL streaming between two Postgresql instances)

Shared File System

Control Plane provisions a single volume per location
The volume set can be attached to any number of workloads
All attached workload replicas in a given location use the same volume
On a BYOK location, it needs a one-time object storage setup; see Shared File System on BYOK

Caveats

The shared filesystem does not support:

snapshots
certain commands:
- createVolumeSnapshot
- deleteVolumeSnapshot
- restoreVolume
- deleteVolume
- shrinkVolume
- copyVolume

Capacity and Billing

When a volume is created, it will have an initial capacity defined by the spec of your volume set.
Volume capacity can be increased by sending an expandVolume command.
Volume capacity can be decreased using the shrinkVolume command, which copies the data to a smaller volume (see Volume Shrinkage below).
The bill for a volume set is calculated by summing the reserved GB of all volumes.

Autoscaling

One Volume Per Replica

This only applies to volume sets using traditional file systems (e.g. ext4, xfs)

Like workloads, volume sets scale horizontally. Every replica in the linked workload is automatically assigned a volume.
When the linked workload scales down, the volumes are preserved. Volumes are only deleted when you send a deleteVolume command, or when the volume set itself is deleted.

Automatic Expansion (Reactive)

The spec.autoscaling object allows you to specify rules for automatically expanding volumes in the set. When a volume’s free space drops below a threshold, Control Plane expands it. The available options are:

maxCapacity: The largest allowable size (in GB) for any volume in the set.
minFreePercentage: This must be a number between 1 and 100. When the free percentage on any volume drops below this threshold, Control Plane will issue an expandVolume command automatically.
scalingFactor: This must be a number 1. Applied as a multiplier when calculating the new capacity, providing headroom beyond the minimum needed to restore minFreePercentage.

When a volume needs expansion, the new capacity is calculated as:

newCapacity = usedGB / (1 - minFreePercentage/100) × scalingFactor

The result is capped at maxCapacity. Example calculation: Suppose a 10 GB volume has 8 GB used (2 GB free, 20%), and the configuration is minFreePercentage: 20, scalingFactor: 2.

Step	Calculation	Result
Current state	8 GB used, 2 GB free	20% free — threshold met
Minimum capacity for 20% free	8 / (1 - 0.20)	10 GB
Apply `scalingFactor`	10 2	20 GB

The volume expands to 20 GB (assuming this is maxCapacity).

Volume Set with Reactive Autoscaling

{
  ...
  "spec": {
    ...
    "autoscaling": {
       "maxCapacity": 100,
       "minFreePercentage": 20,
       "scalingFactor": 2
    }
  }
}

Predictive Scaling

Reactive scaling responds to low free space after it happens. In most cases this is sufficient, but workloads that experience rapid surges in storage consumption can outpace reactive scaling — the volume fills up faster than the expansion can complete. Predictive scaling addresses this by projecting future usage and expanding volumes before they run low. It is a supplement to reactive scaling, not a replacement. On each evaluation cycle, Control Plane computes both a reactive target and a predictive target, then uses whichever is larger (capped at maxCapacity). This means reactive scaling always acts as a safety net.

How It Works

When predictive scaling is enabled, Control Plane:

Queries volume usage over a configurable lookback window.
Fits a linear regression to compute the average growth rate.
Projects usage forward over a configurable projection window.
Calculates a predictive target capacity using the same formula as reactive scaling, but substituting projected usage for current usage:

predictiveCapacity = projectedUsedGB / (1 - minFreePercentage/100) × predictiveScalingFactor

Compares the predictive and reactive targets, and uses the larger of the two.

Predictive scaling is skipped (falling back to reactive only) when any of the following are true:

The volume’s growth rate is below minGrowthRateGBPerHour.
Fewer than minDataPoints data points are available in the lookback window, meaning the projection is not yet considered reliable.

Configuration

Add a predictive object inside autoscaling to enable predictive scaling:

Field	Type	Default	Description
`enabled`	boolean	`false`	Enable predictive scaling based on historical growth rates.
`lookbackHours`	number	`24`	Hours of historical data to analyze for the growth rate calculation. Min: 1, Max: 168 (1 week).
`projectionHours`	number	`6`	Hours into the future to project storage needs. Min: 1, Max: 72.
`minDataPoints`	number	`10`	Minimum number of historical data points required before a projection is considered reliable. Prevents premature scaling decisions when insufficient data is available. Min: 2, Max: 100.
`minGrowthRateGBPerHour`	number	`0.01`	Minimum growth rate (GB/hour) to trigger predictive expansion. Volumes growing slower than this rate will not trigger predictive scaling.
`scalingFactor`	number	(inherited)	Scaling factor for predictive expansion. If not set, uses the parent `autoscaling.scalingFactor`. A lower value (e.g., 1.2) is recommended for gentler proactive scaling. Min: 1.1.

When predictive.enabled is true, the parent autoscaling.minFreePercentage and autoscaling.scalingFactor fields are required.

Example

Volume Set with Predictive Scaling

{
  ...
  "spec": {
    ...
    "autoscaling": {
       "maxCapacity": 100,
       "minFreePercentage": 20,
       "scalingFactor": 2,
       "predictive": {
         "enabled": true,
         "lookbackHours": 48,
         "projectionHours": 12,
         "minDataPoints": 10,
         "minGrowthRateGBPerHour": 0.1,
         "scalingFactor": 1.2
       }
    }
  }
}

Example calculation: Suppose a 50 GB volume currently has 40 GB used (10 GB free), and its growth rate over the past 48 hours is 0.5 GB/hour. Reactive target:

Step	Calculation	Result
Current state	40 GB used, 10 GB free	20% free — threshold met
Minimum capacity for 20% free	40 / (1 - 0.20)	50 GB
Apply `scalingFactor` (2.0)	50 2.0	100 GB

Predictive target:

Step	Calculation	Result
Project usage 12 hours ahead	40 + (0.5 12)	46 GB
Minimum capacity for 20% free	46 / (1 - 0.20)	57.5 GB
Apply predictive `scalingFactor` (1.2)	57.5 1.2	⌈69⌉ = 69 GB

Control Plane compares the two targets: reactive (100 GB) vs. predictive (69 GB). Since reactive is larger, the volume expands to 100 GB (which also equals maxCapacity in this configuration). In a different scenario — say the volume still has plenty of free space but is growing rapidly — the predictive target could exceed the reactive target. The key principle is: whichever target is larger gets used, ensuring the volume is sized for both current needs and anticipated growth.

Snapshots

Snapshots can be taken at any time and (optionally) on a regular schedule. To set up automatic snapshotting, you may use the spec.snapshots object. Options include:

retentionDuration: The length of time to retain a newly created snapshot. This should be a floating point number followed by either d, h, or m (for day, hour or minute)
schedule: A cron expression describing the snapshot frequency. Snapshots cannot be taken more frequently than once per hour.

File System Type

Currently supported file systems are:

ext4
xfs
shared

Mount Resources

For the shared file system only, you will be charged CPU and memory per mount point. Shared volumes must be mounted once per node.

There will be at most one mount point per replica.

You can control the minimum and maximum resource allocations per mount point using the mountOptions property. e.g.

{
  "kind": "volumeset",
  "name": "my-shared-volumeset",
  "description": "",
  "tags": {},
  "spec": {
    "fileSystemType": "shared",
    "initialCapacity": 10,
    "mountOptions": {
      "resources": {
        "maxCpu": "200m",
        "maxMemory": "128Mi",
        "minCpu": "100m",
        "minMemory": "128Mi"
      }
    },
    "performanceClass": "shared"
  }
}

Resource Constraints

minCpu and maxCpu can be at most 4000m apart
The ratio between minCpu and maxCpu must be at least 1:4
minMemory and maxMemory can be at most 4096Mi apart
The ratio between minMemory and maxMemory must be at least 1:4

Performance Classes

Each volume set has a single, immutable, performance class. The performance class determines:

How many Megabytes per second can be transferred to and from the volume (MB/second)
How many I/O operations can be processed per second. (IOPS)
Read/write latency

Because these drives are served over the network, IOPS/throughput is limited per VM. The performance of individual drives will vary.

Volume performance varies widely by cloud service provider.

General-Purpose SSD

Name: general-purpose-ssd Minimum Capacity: 10Gb Maximum Capacity: 65536Gb

Service Provider	Max Throughput	Max IOPS
AWS	125 MB/s	3000
GCP	1200 MB/s	80000
Azure	125 MB/s	3000

High-Throughput SSD

In general, IOPS/throughput capacity varies linearly with storage capacity. The values shown below are the maximum possible values, and may only be achievable with large volume sizes.

Name: high-throughput-ssd Minimum Capacity: 200Gb Maximum Capacity: 65536Gb

Service Provider	Max Throughput	Max IOPS
AWS	400 MB/s	4600
GCP	1200 MB/s	100000
Azure	1200 MB/s	15500

Custom Encryption (AWS)

Control Plane encrypts all volumes by default. The custom encryption feature allows you to specify your own AWS KMS keys for encrypting volumes in a volume set, giving you complete control over the encryption keys used for your data.

When to Use Custom Encryption

Use custom encryption when you need to:

Meet specific compliance or regulatory requirements that mandate customer-managed keys
Maintain control over key lifecycle management (rotation, revocation, etc.)
Use separate encryption keys for different environments or applications
Integrate with existing key management workflows

Custom encryption is currently only available for AWS. Support for other cloud providers is not yet available.

Prerequisites

Before configuring custom encryption, you need:

An AWS KMS key in each region where you want to use custom encryption
Appropriate KMS key policies configured for the KMS key to allow volume encryption

Required Key Policies

Your KMS key policy must permit to Control Plane to use the key for volume encryption. The policies below grant the necessary permissions. You must add these policies to any KMS key used with Control Plan volume sets.

[
  {
    "Sid": "GrantAccessToControlPlane",
    "Effect": "Allow",
    "Principal": {
      "AWS": [
        "arn:aws:iam::957753459089:root"
      ]
    },
    "Action": [
      "kms:Decrypt",
      "kms:DescribeKey",
      "kms:Encrypt",
      "kms:GenerateDataKey",
      "kms:GenerateDataKeyWithoutPlaintext",
      "kms:ReEncrypt*",
      "kms:CreateGrant",
      "kms:RetireGrant",
      "kms:RevokeGrant"
    ],
    "Resource": "*"
  },
  {
    "Sid": "GrantAccessToControlPlaneEC2",
    "Effect": "Allow",
    "Principal": {
      "Service": "ec2.amazonaws.com"
    },
    "Action": [
      "kms:CreateGrant",
      "kms:Decrypt",
      "kms:DescribeKey",
      "kms:GenerateDataKey"
    ],
    "Resource": "*",
    "Condition": {
      "StringEquals": {
        "kms:ViaService": "ec2.{REGION}.amazonaws.com",
        "kms:CallerAccount": "957753459089"
      }
    }
  }
]

Configuration Schema

Custom encryption is configured in the volume set spec using the customEncryption object:

{
  "spec": {
    "customEncryption": {
      "regions": {
        "{cloud-provider}-{region}": {
          "keyId": "arn:aws:kms:region:account:key/key-id"
        }
      }
    }
  }
}

Field Descriptions:

customEncryption.regions: An object mapping region names to encryption configurations
{cloud-provider}-{region}: The region identifier in Control Plane format (e.g., aws-us-east-1, aws-eu-west-1)
keyId: The full ARN of the AWS KMS key to use for volumes in that region

Region Naming Format

Region names must follow the format: aws-{aws-region-name} Examples:

aws-us-east-1 for US East (N. Virginia)
aws-us-west-2 for US West (Oregon)
aws-eu-west-1 for EU (Ireland)
aws-ap-southeast-1 for Asia Pacific (Singapore)

Complete Example

Here’s a full example of a volume set with custom encryption configured for two AWS regions:

Volume Set with Custom Encryption

{
  "kind": "volumeset",
  "name": "my-encrypted-volumeset",
  "description": "Production database volumes with custom encryption",
  "tags": {
    "app": "database",
    "env": "production"
  },
  "spec": {
    "fileSystemType": "ext4",
    "initialCapacity": 100,
    "performanceClass": "high-throughput-ssd",
    "autoscaling": {
      "maxCapacity": 500,
      "minFreePercentage": 20,
      "scalingFactor": 1.5
    },
    "snapshots": {
      "retentionDuration": "7d",
      "schedule": "0 2 * * *"
    },
    "customEncryption": {
      "regions": {
        "aws-us-east-1": {
          "keyId": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
        },
        "aws-eu-west-1": {
          "keyId": "arn:aws:kms:eu-west-1:123456789012:key/abcdefab-abcd-abcd-abcd-abcdefabcdef"
        }
      }
    }
  }
}

Important Constraints

Be aware of the following constraints when using custom encryption:

Key Immutability

Once a volume is created with a specific KMS key, the encryption key cannot be changed
To use a different key, you must create new volumes

Regional Configuration

Encryption keys are configured per region, not globally
Each region can have its own KMS key
If a region is not specified in customEncryption.regions, volumes in that region will use AWS default encryption

File System Support

Custom encryption only works with traditional file systems: ext4 and xfs
The shared file system does not support custom encryption

BYOK Clusters

This feature is for Control Plane-managed clusters only
For BYOK clusters you have full control over your storage classes, and therefore the encryption method as well.

Commands

Volume sets support imperative operations on individual volumes and snapshots. Each one is an asynchronous command whose progress you can follow. To issue a command, send a POST to the volume set’s -command endpoint. e.g. POST https://api.cpln.io/org/my-org/gvc/my-gvc/volumeset/my-volume-set/-command. These commands can also be created using the Control Plane console at https://console.cpln.io

Volume Expansion

Volumes can be expanded on-demand by issuing an expandVolume command. A volume in use by a workload keeps serving: ext4 and xfs volumes are resized online, and shared volumes need no restart. If an online resize times out, the command either restarts the replica to finish the resize or reverts it, depending on the storage driver.

You can only expand a volume 4 times in a rolling 24-hour period. Please plan accordingly.

Volumes cannot be “expanded” to a smaller size.

expandVolume

Spec:

location
volumeIndex
newStorageCapacity

For example:

expandVolume Command

{
  "type": "expandVolume",
  "spec": {
    "location": "aws-sa-east-1",
    "volumeIndex": 0,
    "newStorageCapacity": 11
  }
}

Volume Shrinkage

Volumes can be shrunk on-demand by issuing a shrinkVolume command. If the volume set is in-use by a workload, the corresponding workload replica will be restarted. The shrinkVolume command provisions a new volume at the smaller size, copies the existing data to it, and swaps it in. If the copy fails, the volume keeps its original storage device and data.

A volume cannot be shrunk below the volume set’s initialCapacity or below its used bytes plus 5%. The command is also refused when no current usage metric is available for the volume.

The shrinkVolume command is only available for ext4 and xfs filesystems. It is not supported for shared filesystems.

shrinkVolume

Spec:

location
volumeIndex
newStorageCapacity

For example:

shrinkVolume Command

{
  "type": "shrinkVolume",
  "spec": {
    "location": "aws-sa-east-1",
    "volumeIndex": 0,
    "newStorageCapacity": 10
  }
}

Volume Copy

A copyVolume command copies one volume into another location of the same volume set, or into a volume of another volume set in the same org, including one in another GVC. The copy lands on the same volume index at the destination and replaces the volume there. The source volume is never modified.

The destination volume is replaced, and its storage device is DELETED.Whatever storage device occupies the volume at volumeIndex in the destination is deleted once the copy is committed, and its data is lost. Every copyVolume command must set acknowledgeDestinationVolumeDeletion to true, even when the volume set status shows no device at the destination: status can lag behind reality.

copyVolume is only available for ext4 and xfs volume sets, on both ends. It is not supported for shared file systems.

copyVolume

Spec:

location: the location the volume is copied from. Required.
volumeIndex: the index of the volume to copy. The copy replaces the volume at the same index at the destination. Required.
targetLocation: the location the volume is copied to. Required.
acknowledgeDestinationVolumeDeletion: must be true. Confirms that the destination volume is replaced and its storage device deleted.
targetVolumeSet: optional. A link to the volume set that receives the copy, in the same org. It defaults to the volume set the command is issued on. It accepts these forms:
- //volumeset/VOLUME_SET: a volume set in the same GVC
- //gvc/GVC/volumeset/VOLUME_SET
- /org/ORG/gvc/GVC/volumeset/VOLUME_SET

To copy a volume into another location of the same volume set:

copyVolume Command

{
  "type": "copyVolume",
  "spec": {
    "location": "aws-us-east-2",
    "volumeIndex": 0,
    "targetLocation": "aws-us-west-2",
    "acknowledgeDestinationVolumeDeletion": true
  }
}

To copy a volume into a volume set in another GVC:

copyVolume Command (another volume set)

{
  "type": "copyVolume",
  "spec": {
    "location": "aws-us-east-2",
    "volumeIndex": 0,
    "targetLocation": "aws-us-west-2",
    "targetVolumeSet": "//gvc/my-other-gvc/volumeset/my-volume-set",
    "acknowledgeDestinationVolumeDeletion": true
  }
}

Volume Copy

copyVolume is only available for ext4 and xfs volume sets, on both ends. It is not supported for shared file systems.

copyVolume

Spec:

location: the location the volume is copied from. Required.
volumeIndex: the index of the volume to copy. The copy replaces the volume at the same index at the destination. Required.
targetLocation: the location the volume is copied to. Required.
acknowledgeDestinationVolumeDeletion: must be true. Confirms that the destination volume is replaced and its storage device deleted.
targetVolumeSet: optional. A link to the volume set that receives the copy, in the same org. It defaults to the volume set the command is issued on. It accepts these forms:
- //volumeset/VOLUME_SET: a volume set in the same GVC
- //gvc/GVC/volumeset/VOLUME_SET
- /org/ORG/gvc/GVC/volumeset/VOLUME_SET

To copy a volume into another location of the same volume set:

copyVolume Command

{
  "type": "copyVolume",
  "spec": {
    "location": "aws-us-east-2",
    "volumeIndex": 0,
    "targetLocation": "aws-us-west-2",
    "acknowledgeDestinationVolumeDeletion": true
  }
}

To copy a volume into a volume set in another GVC:

copyVolume Command (another volume set)

{
  "type": "copyVolume",
  "spec": {
    "location": "aws-us-east-2",
    "volumeIndex": 0,
    "targetLocation": "aws-us-west-2",
    "targetVolumeSet": "//gvc/my-other-gvc/volumeset/my-volume-set",
    "acknowledgeDestinationVolumeDeletion": true
  }
}

Copy Volume Rules

Source: the volume must have a storage device. A replica using the source volume keeps running during the copy, so the copy isn’t crash-consistent. Stop the workload first if you need a consistent copy.
Destination: the destination location doesn’t need a volume at that index yet; the copy creates it. The destination GVC must include targetLocation. The destination volume ends up the same size as the source.
Same location: within one volume set, targetLocation must differ from location. A same-location copy is allowed into another volume set, but only when both GVCs run on the same cluster in that location.
Destination workload: if a workload replica uses the destination volume, it keeps running on its old volume until the copy is committed. Control Plane then waits for all of the workload’s replicas to be ready, restarts that replica onto the copied volume, and deletes the old storage device.
Permissions: the caller needs exec.copyVolume on both the source and target volume sets.
Conflicts: a copy conflicts with restoreVolume, expandVolume, shrinkVolume, deleteVolume, and other copyVolume commands on the same volume, at either end. A snapshot of the source can run alongside it. A deleteVolume issued on either end while a copy runs isn’t refused: it marks the copy failed.

Run a Volume Copy

Console
CLI
API

Open the source volume set and go to its Volumes page.
In the Actions menu of the volume to copy, select Copy Volume. It is disabled when the volume has no storage device.
Under Destination Volume Set, leave the field empty to copy into another location of this volume set, or pick any volume set in the org.
Choose the Destination Location.
Tick the acknowledgement that the destination volume will be replaced and its storage device deleted. If the destination is known to hold a storage device, also type the confirmation text shown.
Select Copy. The copy’s progress shows in the Copy operations panel on the source volume set’s Volumes page. A destination in another volume set doesn’t list the copy.

Use cpln volumeset copy:

cpln volumeset copy my-volume-set --gvc my-gvc --location aws-us-east-2 --target-location aws-us-west-2 --volume-index 0 --acknowledge-destination-deletion

To copy into another volume set, add --target-volumeset with its name or link, such as --target-volumeset //gvc/my-other-gvc/volumeset/my-volume-set. Without --volume-index, every volume in --location that has a storage device is copied, each to its own index.

curl -X POST "https://api.cpln.io/org/my-org/gvc/my-gvc/volumeset/my-volume-set/-command" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @copy.json

$TOKEN is a user or service account token; cpln profile token prints one for the current profile.

Follow a Volume Copy

A copy is an asynchronous command. The API POST returns the created command, including its id. cpln volumeset copy doesn’t print the ID, so list the source volume set’s running commands to find it:

cpln rest get "/org/my-org/gvc/my-gvc/volumeset/my-volume-set/-command?lifecycleStage=running"

Get the command by ID from the source volume set until its lifecycleStage is completed, cancelled, or failed:

cpln rest get /org/my-org/gvc/my-gvc/volumeset/my-volume-set/-command/COMMAND_ID

Each end of the copy reports its own progress in status:

status.source.stage: capture-source, await-receiver, apply-source-egress, run-bulk-sync, then cleanup-k8s.
status.target.stage: prepare-destination, apply-receiver, await-bulk-sync, commit-and-prepare-swap, shutdown-target-replica, await-target-replica-termination, then cleanup-k8s. shutdown-target-replica and await-target-replica-termination are skipped when no workload replica uses the destination volume.
Either end’s stage is fail when that end has failed; the command is then cancelled (see Cancel a Volume Copy).
status.source.messages and status.target.messages explain what each end is doing or why it failed.
status.bulkSyncProgressPercent, status.bulkSyncTransferredBytes, status.bulkSyncRate and status.bulkSyncEta report the transfer’s progress. They refresh about every 10 seconds.

The command is completed once both ends have finished and cleaned up.

Cancel a Volume Copy

A copy has no time limit. To stop one that is in progress or taking too long, request its cancellation. This needs exec.copyVolume on the source volume set:

echo '{"lifecycleStage": "cancellation-requested"}' > cancel.json
cpln rest patch /org/my-org/gvc/my-gvc/volumeset/my-volume-set/-command/COMMAND_ID --file cancel.json

What a cancellation does depends on how far the copy got: The copy is committed at the destination’s commit-and-prepare-swap stage, when the volume set is pointed at the copied volume.

Before the copy is committed: the new volume is deleted, and the destination keeps its original storage device.
After the copy is committed: the volume set already points at the copied volume, so the copy is rolled forward. The destination replica is moved onto the copied volume, and the old storage device is deleted.

Either way, the command ends in cancelled only after both ends have removed the temporary resources they created.

A copy that fails on its own also ends in cancelled, not failed: a failing end cancels the command so that both ends clean up, with the same before- and after-commit outcomes. Read status.source.messages and status.target.messages for the reason. The source makes up to 3 bulk-sync attempts before it fails. A copy ends in failed only when a deleteVolume on either end overrides it.

The console has no cancel action for a copy; use the CLI or API.

Copy Volume Errors

The POST is refused with 400, 403 or 409 when the copy can’t run. The messages include:

Message	Fix
`This command replaces the volume at index N in LOCATION with a copy from LOCATION. ... Set spec.acknowledgeDestinationVolumeDeletion to confirm.`	Set `acknowledgeDestinationVolumeDeletion` to `true` after confirming that the destination volume can be deleted.
`targetLocation must differ from location unless targetVolumeSet names another volume set`	Pick another `targetLocation`, or set `targetVolumeSet` to copy into another volume set.
`targetLocation must differ from location when the copy stays within one volume set`	`targetVolumeSet` names the source volume set itself. Pick another `targetLocation`.
`spec.targetVolumeSet must be //volumeset/<name>, //gvc/<gvc>/volumeset/<name> or /org/ORG/gvc/<gvc>/volumeset/<name>, got ...`	Use one of the three link forms.
`The volume at index N in LOCATION has no underlying storage device, so there is nothing to copy.`	The source volume has no data yet. Pick a volume that has a storage device.
`GVC GVC is not scheduled in LOCATION, so no actuator there can receive the volume. Add the location to the GVC and retry.`	Add `targetLocation` to the destination GVC’s locations.
`spec.targetVolumeSet must be in org ORG; a volume cannot be copied across orgs`	Copy into a volume set in the same org.
`spec.targetVolumeSet ... does not exist`	Check the link, and that the volume set exists and is ready.
`GVC A and GVC B run on different clusters in LOCATION ..., so a same-location copy cannot reach both volumes.`	Copy into another location of the destination GVC.
`Cannot copy into VolumeSet ... because it has a fileSystemType of shared`	Copy into an `ext4` or `xfs` volume set.
`Cannot create a copyVolume command on VolumeSet ... because it has a fileSystemType of shared`	The source is a `shared` volume set, which can’t be copied.
`PRINCIPAL is not granted [exec.copyVolume] on VOLUME_SET` (`403`)	Grant `exec.copyVolume` on that volume set.
`There is a conflicting TYPE command for volume: ... (conflicting command id = ID).` (`409`)	Wait for that command to finish, then retry.

Volume Deletion

To delete a volume, issue a deleteVolume command.

deleteVolume

This command deletes the specified volume’s storage device. Note: the metadata for the volume at the specified index will not be removed from the volume set. Only your data will be deleted.

Deleting an in-use volume

If the volume set is in-use by a workload, a new storage device may be immediately created. e.g. if the volume set is in-use by a workload with one replica, and you delete the volume at index 0, Control Plane will:

Create an empty volume to service the workload
Delete the old volume as requested
Restart the workload replica, binding it to the volume created in step 1.

For example:

deleteVolume Command

{
  "type": "deleteVolume",
  "spec": {
    "location": "aws-sa-east-1",
    "volumeIndex": 0
  }
}

Snapshots

Each volume in a set has its own list of snapshots. You manipulate snapshots by issuing commands to the volume set.

createVolumeSnapshot

Take a snapshot for a given volume (specified by location and volume index). snapshotName must be unique for the target volume. Spec:

location
volumeIndex
snapshotName
snapshotExpirationDate
tags
- Specify any key/value pair here.

For example:

createVolumeSnapshot Command

{
  "type": "createVolumeSnapshot",
  "spec": {
    "location": "aws-sa-east-1",
    "volumeIndex": 0,
    "snapshotName": "snap-0",
    "snapshotExpirationDate": "2025-01-01T00:00:00Z",
    "tags": {
      "my-tag-key": "my-tag-value"
    }
  }
}

deleteVolumeSnapshot

Delete the specified snapshot. Spec:

location
volumeIndex
snapshotName

For example:

deleteVolumeSnapshot Command

{
  "type": "deleteVolumeSnapshot",
  "spec": {
    "location": "aws-sa-east-1",
    "volumeIndex": 0,
    "snapshotName": "snap-0"
  }
}

restoreVolume

Restore the specified volume to one of its snapshots. If this volume set is in-use by a workload, the corresponding workload replica will restart.

This operation creates an entirely new volume using the given snapshot. All unsaved data on the original volume will be lost.

Spec:

location
volumeIndex
snapshotName

For example:

restoreVolume Command

{
  "type": "restoreVolume",
  "spec": {
    "location": "aws-sa-east-1",
    "volumeIndex": 0,
    "snapshotName": "snap-0"
  }
}

BYOK Support

Volume sets are supported in BYOK locations as long as the following prerequisites are met:

The cluster must have a CSI-compatible storage driver installed.
You must create storage classes which use the CSI-compatible provisioner, with the following names:
- general-purpose-ssd-ext4
- general-purpose-ssd-xfs
- premium-low-latency-ssd-ext4
- premium-low-latency-ssd-xfs
- general-purpose-ssd-ext4-command
- general-purpose-ssd-xfs-command
- premium-low-latency-ssd-ext4-command
- premium-low-latency-ssd-xfs-command

Planned Features

Automatic volume expansion.

Permissions

The permissions below are used to define policies together with one or more of the four principal types:

Permission	Description	Implies
create	Create new volumesets
delete	Delete existing volumesets
edit	Modify existing volumesets	view
exec	Execute commands	exec.restoreVolume, exec.createVolumeSnapshot, exec.expandVolume, exec.deleteVolume, exec.deleteVolumeSnapshot, exec.deleteOrphanedVolume
exec.copyVolume	Copy a volume into another location
exec.createVolumeSnapshot	Create a snapshot of a volume
exec.deleteOrphanedVolume	Delete a volume which is no longer in the cluster
exec.deleteVolume	Delete a volume
exec.deleteVolumeSnapshot	Delete a volume snapshot
exec.expandVolume	Increase the storage capacity of a volume
exec.restoreVolume	Restore a volume to a snapshot
exec.shrinkVolume	Decrease the storage capacity of a volume
manage	Full access	create, delete, edit, exec, exec.copyVolume, exec.createVolumeSnapshot, exec.deleteOrphanedVolume, exec.deleteVolume, exec.deleteVolumeSnapshot, exec.expandVolume, exec.restoreVolume, exec.shrinkVolume, view
view	Read-only access

exec doesn’t include exec.copyVolume or exec.shrinkVolume. Both destroy a storage device, so they must be granted explicitly or through manage.

Access Report

Displays the permissions granted to principals for the volume set. See Access Report for what each entry shows, how to open it from the Console, CLI, or API, and how groups, query targets, and implied permissions appear in it.

Event Log

Lists the events recorded for the volume set. See the Event Log reference for field details.

CLI

To view the CLI documentation for Volume Sets, see the Volume Set CLI reference.

​Overview

​Traditional File Systems (ext4, xfs)

​Shared File System

​Caveats

​Capacity and Billing

​Autoscaling

​One Volume Per Replica

​Automatic Expansion (Reactive)

​Predictive Scaling

​How It Works

​Configuration

​Example

​Snapshots

​File System Type

​Mount Resources

​Resource Constraints

​Performance Classes

​General-Purpose SSD

​High-Throughput SSD

​Custom Encryption (AWS)

​When to Use Custom Encryption

​Prerequisites

​Required Key Policies

​Configuration Schema

​Region Naming Format

​Complete Example

​Important Constraints

​Commands

​Volume Expansion

​expandVolume

​Volume Shrinkage

​shrinkVolume

​Volume Copy

​copyVolume

​Volume Copy

​copyVolume

​Copy Volume Rules

​Run a Volume Copy

​Follow a Volume Copy

​Cancel a Volume Copy

​Copy Volume Errors

​Volume Deletion

​deleteVolume

​Deleting an in-use volume

​Snapshots

​createVolumeSnapshot

​deleteVolumeSnapshot

​restoreVolume

​BYOK Support

​Planned Features

​Permissions

​Access Report

​Event Log

​CLI

Overview

Traditional File Systems (ext4, xfs)

Shared File System

Caveats

Capacity and Billing

Autoscaling

One Volume Per Replica

Automatic Expansion (Reactive)

Predictive Scaling

How It Works

Configuration

Example

Snapshots

File System Type

Mount Resources

Resource Constraints

Performance Classes

General-Purpose SSD

High-Throughput SSD

Custom Encryption (AWS)

When to Use Custom Encryption

Prerequisites

Required Key Policies

Configuration Schema

Region Naming Format

Complete Example

Important Constraints

Commands

Volume Expansion

expandVolume

Volume Shrinkage

shrinkVolume

Volume Copy

copyVolume

Volume Copy

copyVolume

Copy Volume Rules

Run a Volume Copy

Follow a Volume Copy

Cancel a Volume Copy

Copy Volume Errors

Volume Deletion

deleteVolume

Deleting an in-use volume

Snapshots

createVolumeSnapshot

deleteVolumeSnapshot

restoreVolume

BYOK Support

Planned Features

Permissions

Access Report

Event Log

CLI