Managed Volumes
Limited Access
Managed volumes (permanent storage) are available as part of enterprise plans. To enable them for your account, reach out to the Unikraft Cloud Discord or send an email to support@unikraft.com.
Managed volumes give your instances permanent storage backed by a directory on the host machine. Unlike regular volumes, which have a fixed size, a managed volume exposes an existing host directory to the guest over virtiofs. It has no fixed size limit (only the host's disk bounds it), and the data outlives any individual instance.
This makes managed volumes a good fit for large or shared datasets that you keep on the host and surface inside one or more instances.
How it works
A managed volume maps a host directory (host_path) to a mountpoint (at) inside the guest.
The platform mounts the directory over virtiofs when the instance starts, so the guest reads and writes the host directory directly.
Changes the guest makes appear on the host immediately, and changes on the host appear inside the guest.
Because the data lives on the host rather than in a dedicated block device, a managed volume has no fixed size.
The platform treats its quota policy as dynamic, and counts it toward the number of volumes in your quota but not toward your total volume size quota.
Total volume size quotas aren't yet enforced by the platform for managed volumes, so use them with caution to avoid filling up your host's disk.
On BYOC or on-prem Unikraft Cloud installations, managed volumes can also use custom filesystems.
Custom filesystem drivers can define lifecycle hooks for format, fscheck, mount, unmount, and delete, and can accept backend-specific arguments when you create the volume.
This makes it possible to present shared object storage as a regular filesystem inside instances, for example by using a POSIX layer like JuiceFS on top of S3.
Creating an instance with a managed volume
To attach a managed volume, add an entry with a host_path to the volumes array when you create an instance.
Currently, you drive managed volumes through the API, which you can call with unikraft api or curl.
The fields that describe a managed volume are:
| Field | Description |
|---|---|
at | The mountpoint inside the guest. |
host_path | The directory on the host to mount into the guest. |
uid | The host user ID that the guest's root user maps to. |
gid | The host group ID that the guest's root user maps to. |
After the instance starts, the contents of host_path show up at at inside the guest.
Ownership and permissions
A managed volume maps the guest's root:root ownership onto the host uid:gid you supply.
Every access the guest makes to host_path follows the permissions of that uid:gid on the host.
For example, with uid and gid set to 1001, the guest acts as host user and group 1001 whenever it touches the directory.
To give the guest read-only access, make host_path read-only for that uid:gid on the host.
Setting both uid and gid to 0 gives the guest root access to host_path on the host.
Choose these values carefully in production, and prefer a restricted host user where possible.
Limitations
- Managed volumes don't accept the
size_mbandquota_policyfields. The size has no fixed limit (only host disk space bounds it), and the platform applies adynamicquota policy. - The
uid:gidmust be able to access every parent directory ofhost_path, since the guest traverses them to reach it. - Mounting the same host directory as more than one volume can cause undesirable side effects. Mount each host directory once.
- Managed volumes count toward the number of volumes in your quota, but their size doesn't count toward your volume size quota.
Learn more
- Volumes: fixed-size, block-device volumes managed entirely by the platform.
- Unikraft Cloud's REST API reference, in particular the section on instances.