Volumes

A volume is a persistent storage device that keeps data across restarts and even redeployments.

Code
await ukc.volumes.get(name="data").attach(to="web", at="/data")

Typical workflow

Creating a persistent volume

To start, create the volume with the CLI, with size 100 MiB and name my-volume:

Code
unikraft volumes create --metro fra \
  --name my-volume \
  --size 100M

Code
metro:        fra
name:         my-volume
uuid:         4d5576f7-315a-4eab-98b8-6c18fec076e0
state:        available
size:         100MiB
filesystem:   ext4
quota-policy: static
persistent:   true
access-mode:  rwo
timestamps:
  created:    just now

You can list the volume with:

Code
unikraft volumes list

Code
METRO  NAME       STATE      SIZE    CREATED
fra    my-volume  available  100MiB  just now

The volume is in available state because it isn't attached to any instance yet. It's also marked as persistent because it will persist even after instance deletion.

Importing local data

To populate an empty volume with local data, use the CLI import subcommand. For example, assuming the data you want to import is in your my-data directory, you would run:

Code
unikraft volume import \
  my-volume \
  --source ./data

You should see output like:

Code
│ importing data into volume size=16.47KiB volume=my-volume
│ import complete free=89.52MiB total=89.69MiB volume=my-volume

Creating an instance

Start from this guide to create a simple Flask web server:

Code
git clone https://github.com/unikraft-cloud/examples
cd examples/httpserver-python3.12-flask3.0

Replace the contents of server.py with:

server.py
from flask import Flask, send_from_directory
from datetime import datetime
import os

app = Flask(__name__)

file_path = "/mnt/log.txt"

def initialize_file():
  if not os.path.exists(file_path):
    with open(file_path, 'w') as log_file:
      log_file.write("Log file created.\n")

@app.route('/')
def write_to_file():
  initialize_file()

  current_datetime = datetime.now().strftime("%Y-%m-%d %H:%M:%S")

  # Write to file
  with open(file_path, 'a') as log_file:
    log_file.write(f"{current_datetime}\n")

  # Read contents of the file
  with open(file_path, 'r') as log_file:
    file_contents = log_file.read()

  return file_contents

if __name__ == '__main__':
  app.run(host='0.0.0.0', port=8080)

On every request, this simple server will write a timestamp to a file on the mounted persistent volume and print out the current contents of the file.

Build and deploy the Flask web server and mount the my-volume volume at /mnt:

Code
unikraft build . --output <my-org>/httpserver-python312-flask30:latest
unikraft run --metro fra \
  -m 512M \
  -p 443:8080/http+tls \
  -v my-volume:/mnt \
  --image <my-org>/httpserver-python312-flask30:latest

You should see output like:

Code
metro:        fra
name:         httpserver-python312-flask30-bxwxm
uuid:         3ff1ebad-2639-4214-bab4-ed35c4c32fa4
state:        starting
image:        <my-org>/httpserver-python312-flask30
resources:
  memory:     512MiB
  vcpus:      1
service:
  uuid:       2021ca1e-5e47-a35c-bde2-7190f3815c07
  name:       damp-sunset-azd6dtyt
  domains:
  - fqdn:     damp-sunset-azd6dtyt.fra.unikraft.app
volumes:
- name:       my-volume
  uuid:       4d5576f7-315a-4eab-98b8-6c18fec076e0
  at:         /mnt
networks:
- uuid:       4dc3b272-4fa2-ddb4-7ce0-5e66e8112a61
  private-ip: 10.0.6.5
  mac:        12:b0:66:99:b3:3f
timestamps:
  created:    just now

To confirm that the platform attached the volume, run:

Code
unikraft volumes get my-volume

You should see output like:

Code
METRO  NAME       STATE    SIZE    CREATED
fra    my-volume  mounted  100MiB  2 minutes ago

Testing

The Flask server writes the time and date to /mnt/log.txt for each request. Test it by running curl several times. Example output:

Code
$ curl https://holy-bonobo-px345skl.fra.unikraft.app
Log file created.
2024-02-24 08:15:32

$ curl https://holy-bonobo-px345skl.fra.unikraft.app
Log file created.
2024-02-24 08:15:32
2024-02-24 08:15:34

$ curl https://holy-bonobo-px345skl.fra.unikraft.app
Log file created.
2024-02-24 08:15:32
2024-02-24 08:15:34
2024-02-24 08:15:35

To test data persistence, you can stop the instance, then detach the volume from the instance:

Code
unikraft volumes detach my-volume --from httpserver-python312-flask30-bxwxm
unikraft instances delete httpserver-python312-flask30-bxwxm

You should see that the volume is now available again.

Now start another instance with the same volume:

Code
unikraft run --metro fra \
  -m 512M \
  -p 443:8080/http+tls \
  -v my-volume:/mnt \
  --image <my-org>/httpserver-python312-flask30:latest

This should output something like:

Code
metro:        fra
name:         httpserver-python312-flask30-0s9c7
uuid:         59d06415-84b8-4bf5-85c7-997960382011
state:        starting
image:        <my-org>/httpserver-python312-flask30
resources:
  memory:     512MiB
  vcpus:      1
service:
  uuid:       ca8ae7e9-3767-85f6-3d70-b77bcf894a7c
  name:       winter-field-v6m37jgs
  domains:
  - fqdn:     winter-field-v6m37jgs.fra.unikraft.app
volumes:
- name:       my-volume
  uuid:       4d5576f7-315a-4eab-98b8-6c18fec076e0
  at:         /mnt
networks:
- uuid:       935ba4ef-39c2-07e7-d2ae-8cd3c9aae07c
  private-ip: 10.0.6.5
  mac:        12:b0:66:99:b3:3f
timestamps:
  created:    just now

Run one final curl to this new address. You should see the previous contents plus a new entry at the bottom:

Code
$ curl https://winter-field-v6m37jgs.fra.unikraft.app
Log file created.
2024-02-24 08:15:32
2024-02-24 08:15:34
2024-02-24 08:15:35
2024-02-24 08:20:58

Cleaning up

To clean up, first detach the volume from all instances and then remove it:

Code
unikraft instances stop httpserver-python312-flask30-0s9c7
unikraft volumes detach my-volume --from httpserver-python312-flask30-0s9c7
unikraft volumes delete my-volume
unikraft instances delete httpserver-python312-flask30-0s9c7
unikraft instances delete httpserver-python312-flask30-bxwxm

Warm-plug volume operations

The platform supports warm-plug volume operations. This lets you attach volumes in more lifecycle states than before, but with important timing constraints.

What's supported

• You can attach a volume to an instance created from a snapshot (for example, from a template).
• You can attach a volume to an instance that's currently running.

Current behavior and limitations

• Attaching to a running instance isn't applied instantly.
• The platform schedules the attach operation and completes it on the next scale-to-zero cycle.
• This is warm-plug support, not full hot-plug support.
• Detaching a volume still requires the instance to be fully shut down (not only scaled to zero).
• If you request detach while the instance isn't yet shut down, the platform schedules the update and applies it automatically once shutdown happens.

API usage note

For now, volume attach and detach updates are available through dedicated endpoints:

• /v1/volumes/attach
• /v1/volumes/detach

You can invoke these endpoints via the CLI using unikraft volumes attach and unikraft volumes detach.

The instance PATCH endpoint doesn't currently support volume operations.

Volume templates

A volume template is a volume that you can use as a base to create new volumes with the same data. When you create a volume template, the platform converts the source volume to a template.

Volume templates have their own create, read, update, and delete endpoints at /volumes/templates. They support delete locks and tags.

You can create volume templates from existing volumes using the CLI as well:

Code
unikraft volume template create my-volume

Code
metro:      fra
name:       my-volume
uuid:       4d5576f7-315a-4eab-98b8-6c18fec076e0
state:      template
size:       100MiB
filesystem: ext4
persistent: true
timestamps:
  created:  just now

You can list all volume templates with:

Code
unikraft volume template list

Code
METRO  NAME       STATE     SIZE    CREATED
fra    my-volume  template  100MiB  1 minute ago

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 one or more volumes, you can use the POST /volumes/clone endpoint. You can also use the unikraft CLI to clone a volume:

Code
unikraft volume clone my-volume --name my-volume-clone

Code
metro:        fra
name:         my-volume-clone
uuid:         3f0625b4-cad3-4875-8b61-113aad4b02c7
state:        available
size:         100MiB
filesystem:   ext4
quota-policy: static
persistent:   true
access-mode:  rwo
timestamps:
  created:    just now

Filesystems

By default, volumes are block devices with ext4 filesystem. There's also a virtiofs filesystem option, which is a shared filesystem that allows more than one instance to read and write the same volume simultaneously. To specify the filesystem, use the filesystem field when creating a volume with POST /volumes:

POST /volumes
{
  "name": "my-volume",
  "size_mb": 512,
  "filesystem": "virtiofs"
}

You can also use the unikraft CLI:

Code
unikraft volume create --metro fra \
  --name my-volume \
  --size 512M \
  --filesystem virtiofs

Managed volumes

A managed volume points to an existing directory on the host rather than a platform-allocated storage file.

Create a managed volume with a host_path field instead of size_mb when calling POST /volumes:

POST /volumes
{
  "name": "my-managed-volume",
  "host_path": "/srv/data/mydir",
  "uid": 1000,
  "gid": 1000
}

Restrictions apply:

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

Access modes

On creation, you can specify an access_mode that controls how instances can access or share the volume:

You can specify the access mode when creating a volume with the access_mode field:

POST /volumes
{
  "name": "my-volume",
  "size_mb": 512,
  "access_mode": "rwo"
}

You can also use the unikraft CLI:

Code
unikraft volume create --metro fra \
  --name my-volume \
  --size 512M \
  --access-mode rwo

Read-only many

More than one instance can mount the same rox 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.

Specify readonly: true when attaching a volume at instance creation or via the attach endpoint:

POST /instances
{
  ...
  "volumes": [
    {
      "name": "my-shared-volume",
      "at": "/data",
      "readonly": true
    }
  ],
  ...
}

Read-write many

Read-write many (rwx) volumes are only supported for volumes with the virtiofs filesystem. The downside is that virtiofs volumes are slower than block volumes, so only use them for rwx or managed volumes. To create a rwx volume, you can use the POST /volumes endpoint:

POST /volumes
{
  "name": "my-volume",
  "size_mb": 512,
  "access_mode": "rwx",
  "filesystem": "virtiofs"
}

You can also use the unikraft CLI:

Code
unikraft volume create --metro fra \
  --name my-volume \
  --size 512M \
  --filesystem virtiofs \
  --access-mode rwx

Learn more

• The CLI reference.
• Unikraft Cloud's REST API reference, in particular the section on volumes.
• Tutorial explaining the difference of storage media on Unikraft Cloud.