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 CLI installed and configured with your Unikraft Cloud account. Make sure to log into Unikraft Cloud and pick a metro close to you. This guide uses fra (Frankfurt, 🇩🇪):

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 app
COPY ./wrapper.sh /wrapper.sh
COPY ./server.py /src/server.py

Package and push the base image:

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

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

Package and push the ROMs:

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

Instances

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

Check that the instances are up:

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 example, the platform mounts it automatically at /rom, and the app reads /rom/rom.py from that mount point.

Testing

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

Code
curl https://test-http-python-rom1.fra.kraft.cloud
curl https://test-http-python-rom2.fra.kraft.cloud

Code
Hi from 1st ROM!
Hi from 2nd ROM!

Cleanup

When done, remove the instances:

Inline ROMs

Instead of pre-packaging and pushing a ROM image to a registry, you can provide file contents directly in the instance creation request. This is useful when you create instances from a template where the snapshot locks ENV and ARGS, but you still need to inject instance-specific data.

To use inline ROMs with unikraft, specify a local directory as source:

unikraft
unikraft run --metro fra \
  --name test-http-python-rom-inline \
  -m 512M \
  -p 443:8080/tls+http \
  --domain test-http-python-rom-inline \
  --scale-to-zero policy=on,cooldown-time=1000,stateful=false \
  --rom dir=./rom1/fs,at=/rom \
  --image <my-org>/http-python:latest

API format

The API allows you to specify the contents of an inline ROM directly in the JSON request body when creating an instance. Add a files array to a ROM entry instead of an image field:

POST /instances
curl -X POST \
  -H "Authorization: Bearer ${UKC_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://api.fra.unikraft.cloud/v1/instances" \
  -d '{
    "image": "<my-org>/my-base:latest",
    "roms": [
      {
        "name": "my-rom",
        "files": [
          {
            "path": "config/settings.json",
            "encoding": "text",
            "data": "{\"debug\": false, \"port\": 8080}"
          },
          {
            "path": "certs/client.pem",
            "encoding": "base64",
            "data": "LS0tLS1CRUdJTi..."
          }
        ],
        "at": "/rom/my-rom"
      }
    ]
  }

Each file in the files array has three fields:

The platform packages the provided files into an EROFS filesystem and attaches it as a ROM device, the same way image-based ROMs work. The at field is optional and works the same as for image-based ROMs—when present, the platform mounts the ROM at the given path automatically.

Combining with image-based ROMs

You can mix inline ROMs and image-based ROMs in the same request:

POST /instances
curl -X POST \
  -H "Authorization: Bearer ${UKC_TOKEN}" \
  -H "Content-Type: application/json" \
  "https://api.fra.unikraft.cloud/v1/instances" \
  -d '{
    "image": "<my-org>/my-base:latest",
    "roms": [
      {
        "name": "app-code",
      "image": "<my-org>/my-rom:latest",
      "at": "/app"
    },
    {
      "name": "instance-config",
      "files": [
        {
          "path": "config.json",
          "encoding": "text",
          "data": "{\"instance_id\": \"abc-123\"}"
        }
      ],
      "at": "/config"
    }
  ]
}

Limits

The platform enforces the following default limits on inline ROMs:

No per-file size limit exists. The total size limit applies to the combined size of all files in a single inline ROM. Since inline ROM data is base64-encoded in the JSON request body, the 8 MB request body limit is the practical upper bound on total data per API call.

Learn more

Use the --help option for detailed information on using Unikraft Cloud:

Or visit the CLI Reference or the legacy CLI reference. For more information on the features used in this use case and how to use them, check out the following documentation:

• Unikraft Cloud's REST API reference, and in particular the instances API.
• Tutorial explaining the difference of storage media on Unikraft Cloud.
• Running serverless functions packaged as ROMs on Unikraft Cloud.
• Running and customizing game servers using ROMs on Unikraft Cloud.