Containerd Shim Spin

This project aims to provide the containerd shim implementation for Spin, which enables running Spin workloads on Kubernetes via runwasi. This means that by installing this shim onto Kubernetes nodes, we can add a runtime class to Kubernetes and schedule Spin workloads on those nodes. Your Spin apps can act just like container workloads!

runwasi is a project that aims to run WASI workloads managed by containerd.

Table of Contents

• Shim and Spin Version Map
• Documentation
• Building and running the shim on host
• Installing the shim on Kubernetes Nodes
• Locating build artifacts
• Feedback
• Contributing

Shim and Spin Version Map

Below is a table for referencing the version of the Spin runtime used in each containerd-shim-spin release.

shim version	v0.12.0	v0.13.0	v0.14.0	v0.14.1	v0.15.0	v0.15.1	v0.16.0
spin	v2.2.0	v2.3.1	v2.4.2	v2.4.3	v2.6.0	v2.6.0	v2.6.0

Documentation

To learn more about the Containerd Shim Spin, please visit the official Containerd Shim Spin documentation.

Building and running the containerd-shim-spin on host

Make sure you have installed dependencies:

make setup # setup linux environment

Build, install, and run the shim binary:

make run # run the shim binary

You may open another terminal and run the following command to test the shim:

curl 0.0.0.0:80/hello

Installing the containerd-shim-spin on Kubernetes Nodes

In order to run Spin applications on your cluster, you must complete the following three steps:

1. Install the shim on each Node that should support Spin apps
2. Update the containerd configuration to recognize the shim
3. Apply the Kubernetes RuntimeClass for the shim

Repeating steps 1 and 2 for each node on a cluster can be a time-consuming and manual process. For this reason, SpinKube provides a runtime-class-manager (previously the kwasm operator) that enables you to skip over step 1 and 2. See the SpinKube installation guide for more information on installing with Helm.

To carry out the installation step-by-step, do the following:

1. Install the shim on each Node that should support Spin apps

   Install a release of the shim on the PATH of your Kubernetes worker nodes. For example, copy containerd-shim-spin-v2 to /bin. Shims are additive, so once the containerd-shim-spin is installed on a Node, it can support Spin WebAssembly apps alongside Linux containers.

2. Add the following to the containerd config.toml that maps the runtime type to the shim binary from step 1.

   [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.spin]
   runtime_type = "io.containerd.spin.v2"

   The Node Installer script that is used by the runtime-class-manager does this for you and is a good reference to understand the common paths to the containerd configuration file for popular Kubernetes distributions.

3. Apply a runtime class that contains a handler that matches the "spin" config runtime name from step 2.

   This ensures that the image is executed with the correct runtime, namely the containerd-shim-spin.

   Note: You likely want to customize the Runtime Class with a nodeSelector to ensure Pods are only scheduled to Nodes where the shim has been installed.

   apiVersion: node.k8s.io/v1
   kind: RuntimeClass
   metadata:
   name: wasmtime-spin-v2
   handler: spin
   

4. Deploy a Spin app to your cluster with the specified RuntimeClass name matching the "wasmtime-spin-v2" runtime class from step 3. The Spin Operator does this for you, translating SpinApp custom resources into Kubernetes deployments.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
   name: wasm-spin
   spec:
   replicas: 1
   selector:
       matchLabels:
       app: wasm-spin
   template:
       metadata:
       labels:
           app: wasm-spin
       spec:
       runtimeClassName: wasmtime-spin-v2
       containers:
           - name: spin-hello
           image: ghcr.io/spinkube/containerd-shim-spin/examples/spin-rust-hello:v0.13.0
           command: ["/"]

Locating build artifacts

Versioned releases

A GitHub release is created for each versioned release with build artifacts attached, including shim binaries for all supported architectures. See the Releases page for the full listing.

In addition, container images for k3d, node-installer and example apps are published using the release version for their tags, eg ghcr.io/spinkube/containerd-shim-spin:v0.15.1. A listing of all images and their tags can be seen from the packages page.

Canary builds

On every push to the main branch, the release workflow will run and attach shim binary artifacts once finished.

Container images for k3d, node-installer and example apps are also published, using a unique tag of the form $(date +%Y%m%d-%H%M%S)-g$(git rev-parse --short HEAD). A listing of all images and their tags can be seen from the packages page.

Branch builds

For every push to a feature branch with a corresponding PR, the ci workflow will run and attach shim binary artifacts once finished.

If the feature branch is created from the origin repo, the node-installer image will be published with a tag following the same convention as main builds. You can locate the tag corresponding to your branch via the commit string portion.

Note: A node-installer image won't be pushed for feature branches on forks, as they don't have access to the credentials needed to publish to the ghcr.io container registry.

Feedback

For questions or support, please visit our Slack channel: #spinkube.

Contributing

If you would like to contribute, please visit this contributing page.