From 5619cf42c0dab79e9ecee61fa882768b325c4f47 Mon Sep 17 00:00:00 2001 From: Jerome Jaggi Date: Fri, 13 Mar 2026 15:29:46 +0100 Subject: [PATCH] docs: add volume templates, cloning, and shared volumes sections Signed-off-by: Jerome Jaggi --- pages/platform/volumes.mdx | 116 +++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) diff --git a/pages/platform/volumes.mdx b/pages/platform/volumes.mdx index 8e52294..84645ca 100644 --- a/pages/platform/volumes.mdx +++ b/pages/platform/volumes.mdx @@ -224,6 +224,122 @@ kraft cloud volume detach kraft cloud volume remove ``` +## Volume templates + +A volume template is a volume in the `TEMPLATE` state. +Once a volume transitions to template state, it's immutable: you can clone it but not write to it or delete it while active clones exist. + +The platform creates volume templates automatically when you convert an instance into an [instance template](/platform/instances#instance-templates): the platform converts all volumes attached to that instance into volume templates as an atomic operation. + +Volume templates have their own create, read, update, and delete endpoints at `/v1/volumes/templates`. +They support [delete locks](/platform/delete-locks) and [tags](/platform/tagging). + +## Volume cloning + +A volume clone is an independent copy of an existing volume. +The clone operation is **asynchronous**: the platform creates the new volume immediately in a pending state, and the data copy completes in the background. + +To clone a volume directly: + +```bash title="" +POST /v1/volumes/{name}/clone +``` + +The platform also clones volumes implicitly when you clone an instance or create one from a template. +It clones each attached volume and attaches the clone to the new instance. + +You can't delete a source volume or template while it has active clones (`nactive_clones > 0`). + +## Shared volumes + +More than one instance can mount the same volume simultaneously as long as all mounts are in read-only mode. +Read-only sharing is always permitted regardless of how many other instances have the volume mounted. + +A read-write mount is exclusive. +You can't add one while any other mount exists on that volume, and a volume can't have two read-write mounts at once. + +Specify `readonly: true` when attaching a volume at instance creation or via the attach endpoint: + +```json title="POST /v1/instances" +{ + "volumes": [ + { + "name": "my-shared-volume", + "at": "/data", + "readonly": true + } + ] +} +``` + +### Quota policy + +Volumes support two quota policies that control how the platform allocates storage space: + +| Policy | Description | +|--------|-------------| +| `static` | The platform allocates a fixed quota up front | +| `dynamic` | The platform scales the quota with actual usage | + +### Discard / `TRIM` support + +Block-device volumes support `TRIM`/discard commands, which allow the guest to notify the host about blocks that are no longer in use. +The platform enables discard by default and it applies to volumes backed by a block device (for example, `ext4`-formatted volumes). +Virtiofs-hosted volumes don't use discard. + +This allows guest-initiated `fstrim` runs to release unused blocks, which is useful for reclaiming space in long-lived volumes. + +## Custom filesystems + +By default, volumes use a platform-configured filesystem (typically `ext4` for block volumes and `virtiofs` for hosted volumes). +If the platform operator has registered more named filesystems, you can select one by passing its name in the `filesystem` field when creating a volume: + +```json title="POST /v1/volumes" +{ + "name": "my-volume", + "size_mb": 512, + "filesystem": "xfs" +} +``` + +Available filesystem names depend on the deployment. +An unsupported filesystem name returns an error. + +The operator defines volume operation hooks (format, delete, fscheck) per filesystem via scripts placed under `UKP_STOR_FS_CONFIG_PATH`. +The `args` field passes named string arguments to these scripts: + +```json title="POST /v1/volumes" +{ + "name": "my-volume", + "size_mb": 512, + "filesystem": "custom-fs", + "args": { + "key": "value" + } +} +``` + +## Managed volumes + +A managed volume points to an existing directory on the host rather than a platform-allocated storage file. +This is an advanced feature that requires the `VOLUME_MANAGER` permission. + +Create a managed volume with a `host_path` field instead of `size_mb`: + +```json title="POST /v1/volumes" +{ + "name": "my-managed-volume", + "host_path": "/srv/data/mydir", + "uid": 1000, + "gid": 1000 +} +``` + +- `host_path` must be an absolute, normalised path to an existing directory on the host (no `.`, `..`, or `:` components). +- `uid` and `gid` set the ownership used when accessing the volume from the guest. Both default to `0` if not specified. +- `size_mb` and `template` are mutually exclusive with `host_path`. +- The platform doesn't create, format, resize, or delete the backing directory for managed volumes. + ## Learn more * The `kraft cloud` [CLI reference](/cli/), in particular the [deploy](/cli/deploy) and [volume](/cli/volume) subcommands