Volume Management

Note

Volume management via configure.flexfs is an Enterprise-only feature. Community edition supports a single pre-configured volume created during free.flexfs init creds.

A volume is the fundamental unit of storage in flexFS. Each volume is an independent filesystem backed by a block store (object storage bucket) and a metadata store (metadata server). Mount clients authenticate with a volume token and mount the volume as a POSIX filesystem.

Creating a Volume

configure.flexfs create volume \
  --name <volume-name> \
  --metaStoreID 1 \
  --blockStoreID 1 \
  --blockSize 4MiB \
  --compression lz4 \
  --retention 7d

Volume Fields

For the full list of volume create/update fields, their flags, types, and defaults, see Volume Fields in the configure.flexfs CLI reference. The sections below cover the fields that need extra explanation.

Block Size

The block size determines how file data is divided into blocks stored in object storage. It is set at volume creation and cannot be changed afterward.

Accepted values use human-readable suffixes: 256KiB, 512KiB, 1MiB, 2MiB, 4MiB, 8MiB (or plain byte counts). The suffix is case-insensitive and supports KiB, MiB, GiB, KB, MB, GB, K, M, G forms.

Block Size	Best For
256KiB - 512KiB	Small files, random I/O patterns
1MiB - 2MiB	Mixed workloads
4MiB (default)	General purpose, large sequential reads
8MiB	Very large files, streaming workloads

Larger block sizes reduce the number of object storage requests for sequential reads but increase the minimum read/write granularity. Smaller block sizes improve random I/O at the cost of more metadata overhead.

Compression

Compression is applied to each block before it is stored in object storage. Choose an algorithm at volume creation:

Algorithm	Flag Value	Characteristics
LZ4	lz4 (default)	Very fast compression and decompression; moderate ratio
Snappy	snappy	Fast, lightweight; slightly lower ratio than LZ4
Zstandard	zstd	Higher compression ratio; somewhat slower
None	none	No compression; lowest CPU usage

Compression is set at volume creation and cannot be changed afterward.

End-to-End Encryption

When --encryption is set to true, file contents, file and directory names, symbolic link targets, and extended attribute names and values are encrypted with AES-256 before leaving the mount client. The encryption key is derived from a passphrase using Argon2id and never leaves the client.

Caution

End-to-end encryption cannot be enabled after volume creation. Once a volume is created without it, its blocks cannot be retroactively encrypted.

After creating an encrypted volume, mount clients must provide the encryption secret when mounting. See End-to-End Encryption for setup details.

Retention

Retention controls how long deleted data is preserved before being permanently purged. This applies to both metadata (inodes, directory entries, attributes) and block data in object storage. During the retention period, deleted or overwritten files remain accessible via time-travel mounting.

The --retention flag accepts several formats:

Format	Example	Description
Duration with d suffix	7d	7 days
Go duration string	168h, 168h30m	Standard duration
Combined	7d6h30m	7 days, 6 hours, 30 minutes
Seconds	604800	Plain number of seconds
Forever	forever or -1	Never purge deleted data

The default retention is 7d (7 days / 604800 seconds).

Tip

Longer retention periods increase metadata storage requirements. Use forever only when compliance or audit requirements demand indefinite history.

Retention can be changed on an existing volume with update:

configure.flexfs update volume <volume-name> --retention 30d

Quotas

Volumes support two types of quotas to control resource usage:

Block Quota (--maxBlocks)

Limits the total number of data blocks stored in the volume. Each block is blockSize bytes, so the effective storage limit is maxBlocks * blockSize. A value of 0 means unlimited. Writes that would exceed the limit fail with ENOSPC, and every mount then sees the file as it was last successfully committed.

Caution

Not for volumes provisioned dynamically by the CSI driver. Those take their quota from the PersistentVolumeClaim that created them; setting it here leaves the claim advertising a size the volume no longer enforces.

Inode Quota (--maxInodes)

Limits the total number of files and directories (inodes) in the volume. A value of 0 means unlimited.

Proxy Block Limit (--maxProxied)

Limits how many blocks of each file, counted from the start of the file, are routed through proxy servers. Blocks beyond that count go directly to object storage. This controls proxy cache consumption for volumes with very large files. It is not a quota and never causes a write to fail. A value of 0 means every block is proxied.

Volume Flags

The --flags field sets default mount flags for all mounts of this volume. Multiple flags are comma-separated:

configure.flexfs create volume --name secure-vol \
  --metaStoreID 1 --blockStoreID 1 \
  --flags "ro,noatime,acl,xattr"

For the accepted flag vocabulary, see Accepted Volume and Token Flags in the configure.flexfs CLI reference.

Flags set at the volume level apply to all mounts. A volume token can add boolean flags, but a key=value flag set on the token replaces the volume’s value — including with a more permissive one.

A volume’s flags are merged into every token issued for it, so the --flags field here takes mount options only. The admin flag, which grants reporting access to a volume’s metadata, belongs on an individual volume token and is rejected here. Flags are validated wherever a volume is created or updated, including by the CSI driver’s StorageClass flags parameter.

Updating a Volume

Update mutable fields on an existing volume:

configure.flexfs update volume <volume-name> \
  --maxBlocks 1000000 \
  --maxInodes 500000 \
  --notes "Production data volume"

Updatable fields: metaStoreID, blockStoreID, name, maxBlocks, maxInodes, maxProxied, flags, retention, notes.

Block size, compression, and end-to-end encryption cannot be changed after creation.

Viewing Volumes

configure.flexfs list volumes
configure.flexfs show volume <volume-name>

The show command displays full details including the associated account, metadata store address, and block store endpoint. Volumes can be referenced by name or UUID.

Retiring a Volume

Deleting a volume retires it:

configure.flexfs delete volume <volume-name>

The volume’s retired_at timestamp is set and its volume tokens are deleted: new mounts are refused, and existing mounts lose access within about a minute. The metadata server then permanently deletes the volume’s files and blocks. The retention period does not apply, so a retired volume cannot be recovered or mounted at an earlier point in time. Once its data is deleted, the volume is marked cleaned and no longer appears in list volumes; list volumes --cleaned shows it.

Caution

Retiring cannot be undone. The volume’s record is kept and can no longer be updated. Its name cannot be reused until the record is deleted, and the metadata store and block store it used cannot be deleted until its data has been deleted.

Deleting a Retired Volume

Once a retired volume is marked cleaned, deleting it again removes its record, which frees its name:

configure.flexfs delete volume <volume-name>

Before its data has been deleted, this is refused with 409: volume data is still being deleted. Deleting the meta store, block store, region, or provider a cleaned volume used also deletes the volume’s record.