Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Demos

This page provides various demonstrations of running WebAssembly workloads with Runwasi.

Prerequisites

Before running these demos, make sure you have:

  1. Installed the Runwasi shims as described in the Installation Guide
  2. Installed containerd and its CLI tool ctr

Demo 1: Using Container Image with Wasm Module

This demo runs a WebAssembly module from a regular OCI container image that contains the Wasm module in its filesystem.

Setup

Pull the test image:

make pull-app
# or
sudo ctr images pull ghcr.io/containerd/runwasi/wasi-demo-app:latest

Running the Demo

Run the image with your preferred runtime:

sudo ctr run --rm --runtime=io.containerd.wasmtime.v1 ghcr.io/containerd/runwasi/wasi-demo-app:latest testwasm

You can also specify a particular command:

sudo ctr run --rm --runtime=io.containerd.wasmtime.v1 ghcr.io/containerd/runwasi/wasi-demo-app:latest testwasm /wasi-demo-app.wasm echo 'hello'

The output should look like:

This is a song that never ends.
Yes, it goes on and on my friends.
Some people started singing it not knowing what it was,
So they'll continue singing it forever just because...

To kill the process, run in another terminal:

sudo ctr task kill -s SIGKILL testwasm

The test binary supports various commands for different types of functionality. Check crates/wasi-demo-app/src/main.rs to explore more options.

Demo 2: Using OCI Images with Custom WASM Layers

This demo showcases a more advanced approach using OCI Images with custom WASM layers. This approach doesn’t include the Wasm module in the container’s filesystem but instead stores it as a separate layer in the OCI image. This provides better cross-platform support and de-duplication in the Containerd content store.

Note: This requires containerd 2.0+, 1.7.7+ or 1.6.25+. If you don’t have these patches for both containerd and ctr, you’ll encounter an error message like mismatched image rootfs and manifest layers. Latest versions of k3s and kind have the necessary containerd versions.

Setup

Pull the OCI image with WASM layers:

make pull
# or
sudo ctr images pull ghcr.io/containerd/runwasi/wasi-demo-oci:latest

Running the Demo

Run the image with your preferred runtime:

sudo ctr run --rm --runtime=io.containerd.wasmtime.v1 ghcr.io/containerd/runwasi/wasi-demo-oci:latest testwasmoci wasi-demo-oci.wasm echo 'hello'

Expected output:

hello
exiting

To learn more about this approach, check the design document.

Demo 3: Using Wasm OCI Artifact

The CNCF tag-runtime wasm working group has defined an OCI Artifact format for Wasm. This new artifact type enables usage across projects beyond just Runwasi.

make test/k8s-oci-wasmtime

Note: We use a Kubernetes cluster to run this demo since containerd’s ctr has a bug that results in: unknown image config media type application/vnd.wasm.config.v0+json

WASI/HTTP Demo for Wasmtime Shim

The wasmtime-shim includes support for the WASI/HTTP specification. For details on running HTTP-based WebAssembly modules, see the wasmtime-shim documentation.

WASI/HTTP

The wasmtime-shim supports wasi/http and can be used to serve requests from a wasi/http proxy component. The shim code will try to detect components targeting http/proxy, and start up a hyper server to listen for incoming connections, forwarding the requests to the WASM component for handling.

This behavior is very similar to what the wasmtime serve command currently offers. The server task is terminated upon receiving a terminate or interrupt signal in the container.

This is particularly useful on Wasm-first platforms to enable instance-per-request isolation:

Each Wasm instance serves only one HTTP request, and then goes away.
This improves security and bug mitigation: the blast radius of an exploit or guest-runtime bug is limited to a single request, and cannot access data from other users or other requests by the same user. 3

The server can be customized using environment variables passed to the RuntimeContext:

  • WASMTIME_HTTP_PROXY_SOCKET_ADDR: Defines the socket address to bind to (default: 0.0.0.0:8080).
  • WASMTIME_HTTP_PROXY_BACKLOG: Defines the maximum number of pending connections in the queue (default: 100).

Using Different WebAssembly Runtimes

All demos can be run using any of the available Runwasi shims by replacing wasmtime with the runtime of your choice:

  • Wasmtime: io.containerd.wasmtime.v1
  • WasmEdge: io.containerd.wasmedge.v1
  • Wasmer: io.containerd.wasmer.v1
  • WAMR: io.containerd.wamr.v1

For example:

sudo ctr run --rm --runtime=io.containerd.wasmedge.v1 ghcr.io/containerd/runwasi/wasi-demo-app:latest testwasm

Next Steps