Guides

Spin

In this guide we create and deploy a simple Spin HTTP app. This guide is derived from Spin's spin-wagi-http example and shows how to run a Spin application serving routes from two programs written in different languages (Rust and C++) using both the Spin executor and the Wagi executor on Unikraft Cloud. To run it, follow these steps:

1. Install the kraft CLI tool and a container runtime engine, e.g. Docker.

2. Clone the examples repository and cd into the examples/spin-wagi-http/ directory:

Code
 
git clone https://github.com/kraftcloud/examples
cd examples/spin-wagi-http/

Make sure to log into Unikraft Cloud by setting your token and a metro close to you. We use fra0 (Frankfurt, 🇩🇪) in this guide:

Code
 
# Set Unikraft Cloud access token
export UKC_TOKEN=token
# Set metro to Frankfurt, DE
export UKC_METRO=fra0

When done, invoke the following command to deploy this application on Unikraft Cloud:

Code
 
kraft cloud deploy -p 443:3000 -M 2048 .

The output shows the instance URL and other details:

Code
 
[●] Deployed successfully!
 │
 ├────────── name: spin-wagi-http-is72r
 ├────────── uuid: 045c1bda-0f2e-4f8b-98c7-a208bfa7d143
 ├───────── state: running
 ├─────────── url: https://damp-bobo-wg43p36e.fra0.kraft.host
 ├───────── image: spin-wagi-http@sha256:57a5151996d83332af6da521e1cd92271a8c3ac7ae26bc44a7c0dbbc0a30e577
 ├───── boot time: 300.06 ms
 ├──────── memory: 2048 MiB
 ├─────── service: damp-bobo-wg43p36e
 ├── private fqdn: spin-wagi-http-is72r.internal
 ├──── private ip: 172.16.28.16
 └────────── args: /usr/bin/spin up --from /app/spin.toml --listen 0.0.0.0:3000

In this case, the instance name is spin-wagi-http-is72r and the URL is https://damp-bobo-wg43p36e.fra0.kraft.host. They are different for each run.

Then curl the hello route:

Code
 
curl -i https://damp-bobo-wg43p36e.fra0.kraft.host/hello

Hello, Fermyon!

And curl the goodbye route:

Code
 
curl -i https://damp-bobo-wg43p36e.fra0.kraft.host/goodbye

Goodbye, Fermyon!

At any point in time, you can list information about the instance:

Code
 
kraft cloud instance list

Code
 
NAME                  FQDN                                   STATE    CREATED AT    IMAGE                   MEMORY   ARGS                                      BOOT TIME
spin-wagi-http-is72r  damp-bobo-wg43p36e.fra0.kraft.host    running  1 minute ago  spin-wagi-http@sha2...  2.0 GiB  /usr/bin/spin up --from /app/spin.tom...  300064us

When done, you can remove the instance:

Code
 
kraft cloud instance remove spin-wagi-http-is72r

Customize your Application

To customize the application, update the files in the repository, listed below:

• wagi-http-cpp: C++ server handling the hello route
• http-rust: Rust server handling the goodbye route
• Kraftfile: the Unikraft Cloud specification
• Dockerfile: the Docker-specified application filesystem
• spin.toml: The Spin TOML configuration file

Lines in the Kraftfile have the following roles:

• spec: v0.6: The current Kraftfile specification version is 0.6.

• runtime: spin:latest: The Unikraft runtime kernel to use is Spin.

• rootfs: ./Dockerfile: Build the application root filesystem using the Dockerfile.

• cmd: ["/usr/bin/spin", "up", "--from", "/app/spin.toml", "--listen", "0.0.0.0:3000"]: Use spin as the command to start the app, with the given parameters.

The following options are available for customizing the application:

• If only updating the existing files under the wagi-http-cpp and http-rust directories, no other change is required.

• If new files are added, these have to be copied in the application filesystem, using the COPY command in the Dockerfile.

• More extensive changes may require expanding the Dockerfile with additional Dockerfile commands.

Learn More

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

Code
 
kraft cloud --help

Or visit the CLI Reference.