# Build and Test Environments Build and test workloads often need dynamic code execution in a controlled runtime. You want to swap test logic, keep startup latency low, and avoid rebuilding full images for every test change. With **Unikraft Cloud**, you can run a reusable Go runtime image and inject test logic via ROMs. At startup, the instance compiles ROM code into a Go plugin and executes it, giving you fast iteration with strong isolation. ## Why run build and test environments on Unikraft Cloud ### Fast test iteration Build and test logic changes frequently. With ROM-based deployment, you package and push a small ROM instead of rebuilding the full runtime image: * Keep the runtime stable. * Update only test payloads. * Roll forward and back by switching ROM image tags. ### Runtime compilation in isolated microVMs Each environment runs in its own microVM. The runtime compiles ROM code inside the instance (`go build -buildmode=plugin`) and loads it as a plugin. This isolates compilation and execution while keeping the runtime reusable. ### Template-based cold start optimization The base image can create an [instance template](/platform/instances#instance-templates). New environments launch from that template, reducing startup time for bursty CI-style workloads. ### Scale-to-zero economics Test environments are often idle between runs. With scale-to-zero enabled, idle instances consume no active resources while still waking when needed. ## Getting started This guide uses the [`build-environments`](https://github.com/unikraft-cloud/examples/tree/main/build-environments) example. The base image contains a Go server (`server.go`) that: 1. Writes to `/uk/libukp/template_instance` to create a template. 2. Reads ROM source from `/rom/rom.go`. 3. Compiles it to `/run/rom.so` using `go build -buildmode=plugin`. 4. Loads the `Handler()` function from the plugin and serves its output over HTTP. ### Prerequisites 1. Install the CLI: Use the [unikraft CLI](/docs/cli/unikraft) or the legacy [kraft CLI](https://unikraft.org/docs/cli/install). You need a [BuildKit](https://github.com/moby/buildkit) builder. The easiest way is via [Docker](https://docs.docker.com/engine/install/). 1. Clone the examples repository and enter the example directory: ```bash git clone https://github.com/unikraft-cloud/examples cd examples/build-environments/ ``` Make sure to log into Unikraft Cloud and pick a [metro](/platform/metros) close to you. This guide uses `fra` (Frankfurt, 🇩🇪): ```bash title="unikraft" unikraft login ``` ```bash title="kraft" # Set Unikraft Cloud access token export UKC_TOKEN=token export UKC_METRO=fra ``` ### Step 1: Package and push the base runtime image Package and push the base Go runtime image (see `server.go` for the runtime implementation): ```bash title="unikraft" unikraft build . --output /go-build-env:latest ``` ```bash title="kraft" kraft pkg \ --name index.unikraft.io//go-build-env:latest \ --plat kraftcloud \ --arch x86_64 \ --rootfs-type erofs \ --push \ . ``` The server in `server.go` loads `/rom/rom.go`, compiles it to `/run/rom.so` using `go build -buildmode=plugin`, and invokes `Handler()` from the plugin. ### Step 2: Create a template from the base image Create a short-lived instance from the base image (without ROM attached). The server writes to `/uk/libukp/template_instance` and turns the instance into a [template](/platform/instances#instance-templates) before serving requests: ```bash title="unikraft" unikraft run --metro fra \ --name go-build-env \ -m 512M \ --image /go-build-env:latest ``` ```bash title="kraft" kraft cloud instance create \ --start \ --name go-build-env \ -M 512Mi \ /go-build-env:latest ``` The output shows the instance address and other details: ```ansi title="unikraft" metro: fra name: go-build-env uuid: 650dbbe7-3949-4c93-88e7-6619a9216e0c state: starting image: /go-build-env resources: memory: 512MiB vcpus: 1 networks: - uuid: 6f7a8b9c-0d1e-2f3a-4b5c-f6a7b8c9d0e1 private-ip: 10.0.5.4 mac: 12:b0:6c:3e:ab:95 timestamps: created: just now ``` ```ansi title="kraft" [●] Deployed successfully! │ ├───────── name: go-build-env ├───────── uuid: 650dbbe7-3949-4c93-88e7-6619a9216e0c ├──────── metro: https://api.fra.unikraft.cloud/v1 ├──────── state: starting ├──────── image: oci://unikraft.io//go-build-env@sha256:1f57e9bb8702d031743acf43164b24cf182158c398f1eda8c5583208ccc9c300 ├─────── memory: 512 MiB ├─ private fqdn: go-build-env.internal └─── private ip: 10.0.5.4 ``` This instance is short-lived, since right before the server starts, it triggers a conversion into a template. To check that the template is ready, run: ```bash title="unikraft" unikraft instances templates list ``` ```bash title="kraft" kraft cloud instance template list ```
```ansi title="unikraft" METRO NAME STATE IMAGE ARGS MEMORY VCPUS CREATED fra go-build-env template /go-build-env 512MiB 1 just now ``` ```ansi title="kraft" NAME IMAGE ARGS CREATED AT go-build-env oci://unikraft.io//go-build-env@sha256:1cbd6474386c9df546820cd0522030a1bd8702c59490548f10ae10fb8b0a6e14 20 seconds ago ``` ### Step 3: Package ROM payloads Each ROM contains a Go function implementation. ```bash title="unikraft" unikraft build rom1/ --output /go-rom1:latest unikraft build rom2/ --output /go-rom2:latest ``` ```bash title="kraft" kraft pkg \ --rom ./fs \ --rom-type erofs \ --plat kraftcloud \ --arch x86_64 \ --name index.unikraft.io//go-rom1:latest \ --push \ rom1/ kraft pkg \ --rom ./fs \ --rom-type erofs \ --plat kraftcloud \ --arch x86_64 \ --name index.unikraft.io//go-rom2:latest \ --push \ rom2/ ``` ### Step 4: Launch test environments from template Create an instance with the first ROM: ```bash title="unikraft" unikraft run --metro fra \ --name go-build-env-rom1 \ -p 443:8080/tls+http \ --scale-to-zero policy=on,cooldown-time=1000,stateful=true \ --rom image=/go-rom1:latest,at=/rom \ --template go-build-env ``` ```bash title="kraft" # kraft does not support creating instances with attached ROMs, but you can use the API directly curl -X POST "$UKC_METRO/instances" \ -H "Accept: application/json" \ -H "Authorization: Bearer $UKC_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "go-build-env-rom1", "template": { "name": "go-build-env" }, "autostart": true, "service_group": { "services": [ { "port": 443, "destination_port": 8080, "handlers": ["tls", "http"] } ] }, "scale_to_zero": { "policy": "on", "stateful": true, "cooldown_time_ms": 1000 }, "roms": [ { "name": "go_function", "image": "index.unikraft.io//go-rom1:latest", "at": "/rom" } ] }' ``` The instance will compile the ROM into a plugin on first start, which may take a few seconds. To check the progress, you can view the instance logs: ```bash title="unikraft" unikraft instances logs go-build-env-rom1 -f ``` ```bash title="kraft" kraft cloud instance logs go-build-env-rom1 -f ``` Create another instance with the second ROM: ```bash title="unikraft" unikraft run --metro fra \ --name go-build-env-rom2 \ -p 443:8080/tls+http \ --scale-to-zero policy=on,cooldown-time=1000,stateful=true \ --rom image=/go-rom2:latest,at=/rom \ --template go-build-env ``` ```bash title="kraft" # kraft does not support creating instances with attached ROMs, but you can use the API directly curl -X POST "$UKC_METRO/instances" \ -H "Accept: application/json" \ -H "Authorization: Bearer $UKC_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "go-build-env-rom2", "template": { "name": "go-build-env" }, "autostart": true, "service_group": { "services": [ { "port": 443, "destination_port": 8080, "handlers": ["tls", "http"] } ] }, "scale_to_zero": { "policy": "on", "stateful": true, "cooldown_time_ms": 1000 }, "roms": [ { "name": "go_function", "image": "index.unikraft.io//go-rom2:latest", "at": "/rom" } ] }' ``` The instance will compile the ROM into a plugin on first start, which may take a few seconds. To check the progress, you can view the instance logs: ```bash title="unikraft" unikraft instances logs go-build-env-rom2 -f ``` ```bash title="kraft" kraft cloud instance logs go-build-env-rom2 -f ``` Both instances run the same base Go runtime, but execute different ROM payloads, demonstrating fast iteration with reusable layers. List the instances and note their FQDN values: ```bash title="unikraft" unikraft instances list ``` ```bash title="kraft" kraft cloud instance list ```
```ansi title="unikraft" METRO NAME STATE IMAGE ARGS MEMORY VCPUS FQDN CREATED fra go-build-env-rom2 standby /go-build-env 512MiB 1 nameless-wood-gw7pbnls.fra.unikraft.app 2 minutes ago fra go-build-env-rom1 standby /go-build-env 512MiB 1 sparkling-dawn-syowlbtj.fra.unikraft.app 3 minutes ago ``` ```ansi title="kraft" NAME FQDN STATE STATUS IMAGE MEMORY VCPUS ARGS BOOT TIME go-build-env-rom2 nameless-wood-gw7pbnls.fra.unikraft.app standby standby oci://unikraft.io//go-build-env@sha256:1cbd64... 512 MiB 1 6.98 ms go-build-env-rom1 sparkling-dawn-syowlbtj.fra.unikraft.app standby standby oci://unikraft.io//go-build-env@sha256:1cbd64... 512 MiB 1 7.86 ms ``` Test both instances using the FQDNs from the listing: ```bash curl https://sparkling-dawn-syowlbtj.fra.unikraft.app curl https://nameless-wood-gw7pbnls.fra.unikraft.app ``` ```text Bye, World! Auf Wiedersehen! ``` ## Why this pattern works This build/test environment uses three reusable layers: 1. **Base runtime image**: A Go server plus toolchain. Build once, reuse many times. 1. **ROM payload**: A source-only image (`rom.go`). Update per test case. 1. **Template snapshot**: A pre-initialized runtime used to speed up new instance startup. ## Cleanup ```bash title="unikraft" unikraft instances delete go-build-env-rom1 go-build-env-rom2 unikraft instances template delete go-build-env ``` ```bash title="kraft" kraft cloud instance remove go-build-env-rom1 go-build-env-rom2 kraft cloud instance template remove go-build-env ``` ## Learn more ```bash title="unikraft" unikraft --help ``` ```bash title="kraft" kraft cloud --help ``` Or visit the [CLI Reference](/docs/cli/unikraft) or the [legacy CLI reference](/docs/cli/kraft/overview).