From 9b376cae39e018df000e4564473dbeb0cd654720 Mon Sep 17 00:00:00 2001 From: Jiaxiao Zhou Date: Mon, 16 Oct 2023 23:49:58 -0700 Subject: [PATCH] docs: add a version table to README and rewords (#158) * docs: add a version table to README and rewords Signed-off-by: GitHub * update the table Signed-off-by: jiaxiao zhou --------- Signed-off-by: GitHub Signed-off-by: jiaxiao zhou --- README.md | 122 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 67 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 7ed05bde..352c9932 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,99 @@ # Containerd Wasm Shims -This project aims to provide containerd shim implementations that can run Wasm / WASI workloads using [runwasi](https://github.com/deislabs/runwasi) as a library. This means that by installing these shims onto Kubernetes nodes, we can add a runtime class to Kubernetes and schedule Wasm workloads on those nodes. Your Wasm pods and deployments can act just like container workloads! -[runwasi](https://github.com/deislabs/runwasi) is a project that aims to run wasm workloads running on [Wasmtime](https://wasmtime.dev/), a fast and secure runtime for WebAssembly, which is managed by containerd. +This project aims to provide containerd shim implementations that can run [Wasm](https://webassembly.org/) / [WASI](https://github.com/WebAssembly/WASI) workloads using [runwasi](https://github.com/deislabs/runwasi) as a library. This means that by installing these shims onto Kubernetes nodes, we can add a [runtime class](https://kubernetes.io/docs/concepts/containers/runtime-class/) to Kubernetes and schedule Wasm workloads on those nodes. Your Wasm pods and deployments can act just like container workloads! -## Quickstarts +[runwasi](https://github.com/deislabs/runwasi) is a project that aims to run WASI workloads managed by [containerd](https://containerd.io/). -- [Start k3d and run a sample WASM application](./deployments/k3d/README.md#how-to-run-the-example). -- [Create a Spin application on k3d](./containerd-shim-spin-v1/quickstart.md) -- [Deploy a SpiderLightning application with k3d](./containerd-shim-slight-v1/quickstart.md) -- [Deploy a Wasm Workers Server application with k3d](./containerd-shim-slight-v1/quickstart.md) +## Shims -## Containerd Wasm Shims -Each of the shims below leverage runwasi to provide the bridge between K8s and containerd. +This repo currently maintains four shims for Wasm application runtimes/frameworks: -### Spin shim -The Spin shim, as the name implies, is powered by the [Fermyon Spin](https://github.com/fermyon/spin) engine. Spin is an open source framework for building and running fast, secure, and composable cloud microservices with WebAssembly. +1. [Lunatic](https://github.com/lunatic-solutions/lunatic) - an Earlang-inspired runtime for fast, robust and scalable server-side Wasm application. +2. [Spin](https://github.com/fermyon/spin) - a developer tool for building and running serverless Wasm applications. +3. [Slight](https://github.com/deislabs/spiderlightning) - a wasmtime-based runtime for running Wasm applications that use SpiderLightning (aks [WASI-Cloud-Core](https://github.com/WebAssembly/wasi-cloud-core)) capabilities +4. [Wasm Workers Server](https://github.com/vmware-labs/wasm-workers-server) - a tool to develop and run serverless applications server on top of Wasm. -If you are curious, [here is the Spin shim source code](./containerd-shim-spin-v1). +Below is a table of the shims and the the most recent versions of the shims that are supported by this project. -### Slight (SpiderLightning) shim -The slight shim is powered by the [Deislabs SpiderLightning](https://github.com/deislabs/spiderlightning) engine. Slight is an open source host, much like Spin, for building and running fast, secure, and composable cloud microservices with WebAssembly. In addition, the slight shim comes with an increasing [array of WebAssembly component capabilities, including underlying implementations](https://github.com/deislabs/spiderlightning/blob/main/docs/primer.md#spiderlightning-capabilities), to consume common application level services. +| **shim version** | v0.9 | v0.8 | v0.7 | v0.5.1 | v0.5.0 | +| ---------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | +| **spin** | [v1.4.1](https://github.com/fermyon/spin/releases/tag/v1.4.1) | [v1.4.0](https://github.com/fermyon/spin/releases/tag/v1.4.0) | [v1.3.0](https://github.com/fermyon/spin/releases/tag/v1.3.0) | [v1.0.0](https://github.com/fermyon/spin/releases/tag/v1.0.0) | [v0.9.0](https://github.com/fermyon/spin/releases/tag/v0.9.0) | +| **slight** | [v0.5.1](https://github.com/deislabs/spiderlightning/releases/tag/v0.5.1) | [v0.5.0](https://github.com/deislabs/spiderlightning/releases/tag/v0.5.1) | [v0.5.0](https://github.com/deislabs/spiderlightning/releases/tag/v0.5.0) | [v0.4.0](https://github.com/deislabs/spiderlightning/releases/tag/v0.4.0) | [v0.4.0](https://github.com/deislabs/spiderlightning/releases/tag/v0.4.0) | +| **wws** | [v1.5.0](https://github.com/vmware-labs/wasm-workers-server/releases/tag/v1.5.0) | [v1.4.0](https://github.com/vmware-labs/wasm-workers-server/releases/tag/v1.4.0) | [v1.2.0](https://github.com/vmware-labs/wasm-workers-server/releases/tag/v1.2.0) | / | / | +| **lunatic** | [v0.13.2](https://github.com/lunatic-solutions/lunatic/releases/tag/v0.13.2) | / | / | / | / | -If you are curious, [here is the Slight shim source code](./containerd-shim-slight-v1). +## Compare to `runwasi` shims -### Wasm Workers Server (wws) shim -The `wws` shim is powered by the [Wasm Workers Server](https://github.com/vmware-labs/wasm-workers-server) engine. Wasm Workers Server is an open-source project to develop and run serverless applications on top of WebAssembly. It's based on the "workers" concept from the browser, where you have functions that receives a request, processes it, and provides response. It supports multiple languages, so you can develop your workers with Rust, JavaScript, Python, Ruby and more in the future. +As mentioned above, this project uses runwasi's `containerd-shim-wasm` to build shim implementations for higher level Wasm application runtimes/frameworks. The `runwasi` shims are more lower level that are intended to run WASI-compatible Wasm modules, instead of Wasm applicaitons that are built on top of a framework. If you are looking for `Wasmtime`, `WasmEdge` or `Wasmer` shims, please check out [runwasi](https://github.com/deislabs/runwasi). -If you are curious, [here is the Wasm Workers Server shim source code](./containerd-shim-wws-v1). +## Quickstarts + +- [Start k3d and run a sample WASM application](./deployments/k3d/README.md#how-to-run-the-example). +- [Create a Spin application on k3d](./containerd-shim-spin-v1/quickstart.md) +- [Deploy a SpiderLightning application with k3d](./containerd-shim-slight-v1/quickstart.md) +- [Deploy a Wasm Workers Server application with k3d](./containerd-shim-slight-v1/quickstart.md) ### Building the shims -To build the shims in this project, run `make`. -### Running a shim locally on Linux -To run the spin shim using [a hello world Spin example](./images/spin), run `make run_spin`. This will use `ctr` to simulate the same call that would be made from containerd to run a local OCI container image. +To build the shims in this project, run `make build`. -The "hello world" image contains only 2 files, the [`spin.toml`](./images/spin/spin.toml) file and the `spin_rust_hello.wasm` file created by compiling the "hello world" spin example by running `cargo build --target wasm32-wasi --release` in [the example directory](./images/spin). **The image is only 1.9MB!** +### Running the integration tests -To run either shim locally using k3d and exercise it using sample services, see [the README in deployments/k3d](./deployments/k3d/README.md). +To run the integration tests, run `make integration-tests`. ### Cleaning up -To clean up, run `make clean`. + +To clean up, run `make tests/clean`. ## Example Kubernetes Cluster Deployments + In [the deployments directory](deployments) you will find examples of deploying the shims to Kubernetes clusters and using them in example Kubernetes workloads. ## Using a shim in Kubernetes + To use one of these containerd shims in Kubernetes, you must do the following: -1. Install the shim binary somewhere on the path of your Kubernetes worker nodes. For example, copy `containerd-shim-spin-v1` to `/bin`. + +1. Install the shim binary somewhere on the path of your Kubernetes worker nodes. For example, copy `containerd-shim-spin-v1` to `/bin`. 2. Add the following to the containerd config.toml that maps the runtime type to the shim binary from step 1. - ```toml - [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.spin] - runtime_type = "io.containerd.spin.v1" - ``` + +```toml +[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.spin] + runtime_type = "io.containerd.spin.v1" +``` + 3. Apply a runtime class that contains a handler that matches the "spin" config runtime name from step 2. - ```yaml - apiVersion: node.k8s.io/v1 - kind: RuntimeClass - metadata: - name: wasmtime-spin - handler: spin - ``` + +```yaml +apiVersion: node.k8s.io/v1 +kind: RuntimeClass +metadata: + name: wasmtime-spin +handler: spin +``` + 4. Deploy a Wasm workload to your cluster with the specified runtime class name matching the "wasmtime-spin" runtime class from step 3. - ```yaml - apiVersion: apps/v1 - kind: Deployment + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: wasm-spin +spec: + replicas: 1 + selector: + matchLabels: + app: wasm-spin + template: metadata: - name: wasm-spin + labels: + app: wasm-spin spec: - replicas: 1 - selector: - matchLabels: - app: wasm-spin - template: - metadata: - labels: - app: wasm-spin - spec: - runtimeClassName: wasmtime-spin - containers: - - name: spin-hello - image: ghcr.io/deislabs/containerd-wasm-shims/examples/spin-rust-hello:latest - command: ["/"] - ``` + runtimeClassName: wasmtime-spin + containers: + - name: spin-hello + image: ghcr.io/deislabs/containerd-wasm-shims/examples/spin-rust-hello:latest + command: ["/"] +``` ## Code of Conduct