ROMs

Unikraft Cloud supports the ability to attach Read-Only Memory (ROM) blobs to instances. It allows you to create a general-purpose base image and then customize individual instances by attaching code or data as separate ROM blobs. This enables quick deployment of custom functionality to preexisting language environments without rebuilding the entire image.

Overview

With ROMs, you can:

• Deploy variations of an app from a single base image.
• Update app code without rebuilding the base image.
• Reduce image size and deployment time.

The ROM workflow consists of two main components:

1. Base Image: A general-purpose image containing the runtime environment (for example, Python interpreter, Node.js, etc.).
2. ROM Blobs: Separate, lightweight images containing your app code or any other data you want to customize.

This separation allows you to maintain one base image while deploying many different instances with different data.

Setup

This example shows how to deploy Python functions using ROMs on Unikraft Cloud. Ensure you have the kraft CLI installed and configured with your Unikraft Cloud account. Set the following environment variables:

 
export UKC_USER="<your-username>"
export UKC_TOKEN="<your-api-token>"
export UKC_METRO="fra" # or your preferred metro

Base Image

First, create a base image with a Python HTTP server that loads and executes custom Python programs from a ROM.

Dockerfile
 
FROM python:3.12 AS build

RUN set -xe; \
    /usr/sbin/ldconfig /usr/local/lib

FROM scratch

# Python binary
COPY --from=build /usr/local/bin/python3 /usr/bin/python3

# System binaries
COPY --from=build /usr/bin/mount /usr/bin/mount
COPY --from=build /usr/bin/sh /usr/bin/sh
COPY --from=build /usr/bin/mkdir /usr/bin/mkdir

# System Libraries
COPY --from=build /lib/x86_64-linux-gnu/libc.so.6 /lib/x86_64-linux-gnu/libc.so.6
COPY --from=build /lib/x86_64-linux-gnu/libm.so.6 /lib/x86_64-linux-gnu/libm.so.6
COPY --from=build /lib/x86_64-linux-gnu/libmount.so.1 /lib/x86_64-linux-gnu/libmount.so.1
COPY --from=build /lib/x86_64-linux-gnu/libselinux.so.1 /lib/x86_64-linux-gnu/libselinux.so.1
COPY --from=build /lib/x86_64-linux-gnu/libblkid.so.1 /lib/x86_64-linux-gnu/libblkid.so.1
COPY --from=build /lib/x86_64-linux-gnu/libpcre2-8.so.0 /lib/x86_64-linux-gnu/libpcre2-8.so.0
COPY --from=build /usr/lib/x86_64-linux-gnu/libz.so.1 /usr/lib/x86_64-linux-gnu/libz.so.1
COPY --from=build /usr/lib/x86_64-linux-gnu/libcrypto.so.3 /usr/lib/x86_64-linux-gnu/libcrypto.so.3

# Dynamic linker / loader
COPY --from=build /lib64/ld-linux-x86-64.so.2 /lib64/ld-linux-x86-64.so.2
COPY --from=build /etc/ld.so.cache /etc/ld.so.cache

# Python (and other) libraries
COPY --from=build /usr/local/lib /usr/local/lib

# Python application
COPY ./wrapper.sh /wrapper.sh
COPY ./server.py /src/server.py

Ensure that the wrapper.sh script is executable:

 
chmod a+x wrapper.sh

Package and push the base image:

 
kraft pkg \
  --plat kraftcloud \
  --arch x86_64 \
  --name index.unikraft.io/"$UKC_USER"/http-python:latest \
  --rootfs-type erofs \
  --push .

Wait a few seconds for propagation and check that the image is present:

 
kraft cloud image ls

ROM files

To showcase the benefits of using ROMs, create two files, each containing a Python function that the base image will load and execute. Create a separate directory for each of the ROMs:

 
mkdir -p rom1/fs rom2/fs

rom1/fs/rom.py
 
def function():
    return "Hi from 1st ROM!\n"

Package and push the ROMs:

 
cd rom1/
kraft pkg \
  --no-kernel \
  --plat kraftcloud \
  --arch x86_64 \
  --name index.unikraft.io/"$UKC_USER"/my-rom1:latest \
  --rootfs-type erofs \
  --push .

cd ../rom2/
kraft pkg \
  --no-kernel \
  --plat kraftcloud \
  --arch x86_64 \
  --name index.unikraft.io/"$UKC_USER"/my-rom2:latest \
  --rootfs-type erofs \
  --push .

Wait a few seconds for propagation and check that the ROMs are present:

 
kraft cloud image ls

Services

Create two services to expose your instances:

 
curl -X POST \
  -H "Authorization: Bearer ${UKC_TOKEN}" \
  -H "Content-Type: application/json" \
  "${UKC_METRO}/services" \
  -d "[
        {
          'name': 'test-http-python-rom1',
          'services': [
            {
              'port': 443,
              'destination_port': 8080,
              'handlers': ['tls', 'http']
            }
          ],
          'domains': [
            {
              'name': 'test-http-python-rom1'
            }
          ]
        },
        {
          'name': 'test-http-python-rom2',
          'services': [
            {
              'port': 443,
              'destination_port': 8080,
              'handlers': ['tls', 'http']
            }
          ],
          'domains': [
            {
              'name': 'test-http-python-rom2'
            }
          ]
        }
      ]"

Check that the services are up:

 
kraft cloud service get test-http-python-rom1
kraft cloud service get test-http-python-rom2

Instances

Create two instances from the same base image and attach different ROMs:

 
curl -X POST \
  -H "Authorization: Bearer ${UKC_TOKEN}" \
  -H "Content-Type: application/json" \
  "${UKC_METRO}/instances" \
  -d "[
        {
          'name': 'test-http-python-rom1',
          'image': '${UKC_USER}/http-python:latest',
          'service_group': {
            'name': 'test-http-python-rom1'
          },
          'memory_mb': 512,
          'scale_to_zero': {
            'policy': 'on',
            'stateful': false,
            'cooldown_time_ms': 1000
          },
          'autostart': true,
          'roms': [
            {
              'name': 'python_function.py',
              'image': '$UKC_USER/my-rom1:latest'
            }
          ]
        },
        {
          'name': 'test-http-python-rom2',
          'image': '${UKC_USER}/http-python:latest',
          'service_group': {
            'name': 'test-http-python-rom2'
          },
          'memory_mb': 512,
          'scale_to_zero': {
            'policy': 'on',
            'stateful': false,
            'cooldown_time_ms': 1000
          },
          'autostart': true,
          'roms': [
            {
              'name': 'python_function.py',
              'image': '$UKC_USER/my-rom2:latest'
            }
          ]
        }
      ]"

Check that the instances are up:

 
kraft cloud instance get test-http-python-rom1
kraft cloud instance get test-http-python-rom2

Note the roms array in the instances configurations. Each ROM is available as a readable device at /dev/ukp_rom_python_function.py (in the form of an EROFS filesystem in this case), which the server program mounts at /tmp/rom.py and executes.

Testing

Query the instances to call the Python function from the ROM. You should see different responses:

 
$ curl https://test-http-python-rom1.fra.kraft.cloud
Hi from 1st ROM!

 
$ curl https://test-http-python-rom2.fra.kraft.cloud
Hi from 2nd ROM!

Cleanup

When done, remove the instances and services:

 
kraft cloud instance rm test-http-python-rom1 test-http-python-rom2
kraft cloud service rm test-http-python-rom1 test-http-python-rom2

Learn more

• The kraft cloud command-line tool reference, and in particular the instance create subcommand.
• Unikraft Cloud's REST API reference, and in particular the instances API.
• The kraft pkg command reference for packaging images and ROMs.