Volume Sets

​

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 stateful workload.
• 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

​

Caveats

The shared filesystem does not support:

• snapshots
• certain commands:
  • createVolumeSnapshot
  • deleteVolumeSnapshot
  • restoreVolume
  • deleteVolume

​

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 cannot be decreased.
• The bill for a volume set is calculated by summing the reserved GB of all volumes.

​

Autoscaling

​

One Volume Per Replica

• 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

The spec.autoscaling object allows you to specify rules for automatically expanding volumes in the set. The available options are:

• maxCapacity: The largest allowable size 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. When a volume must be expanded, the new capacity will be (the minimum size to ensure minFreePercentage) scalingFactor. E.g. if a volume is using 8/10 GB, and the minFreePercentage is 50, the new capacity will be 16 scalingFactor, assuming that product is maxCapacity.

For example:

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

​

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.

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

Volume performance varies widely by cloud service provider.

​

General-Purpose SSD

Name: general-purpose-ssd

Minimum Capacity: 10Gb

Maximum Capacity: 16384Gb

​

High-Throughput SSD

Minimum Capacity: 200Gb

Maximum Capacity: 16384Gb

​

Commands

Volume sets support imperative operations on individual volumes and snapshots. 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. If the volume set is in-use by a workload, the corresponding workload replica will be restarted.

​

expandVolume

Spec:

• location
• volumeIndex
• newStorageCapacity

For example:

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

​

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:

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

For example:

{
  "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:

{
  "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:

{
  "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.

Spec:

• location
• volumeIndex
• snapshotName

For example:

{
  "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:

1. The cluster must have a CSI-compatible storage driver installed.

2. 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:

​

Access Report

Displays the permissions granted to principals for the volume set.

​

CLI

To view the CLI documentation for Volume Sets, click here.