add documentation for running wasm workloads

Signed-off-by: David Justice <[email protected]>

.codespellignore

@@ -5,4 +5,5 @@ ot
 updat
 shouldnot
 decorder
-overriden
+overriden
+wit

docs/book/src/SUMMARY.md

@@ -31,6 +31,7 @@
     - [VM Identity](./topics/vm-identity.md)
     - [Windows](./topics/windows.md)
     - [Flatcar](./topics/flatcar.md)
+    - [WebAssembly / WASI Pods](./topics/wasi.md)
 - [Development](./developers/development.md)
     - [Kubernetes Developers](./developers/kubernetes-developers.md)
     - [Releasing](./developers/releasing.md)

docs/book/src/topics/wasi.md

@@ -0,0 +1,117 @@
+# WebAssembly / WASI Workloads
+
+## Overview
+
+CAPZ enables you to create WebAssembly (Wasm) / WASI pod workloads targeting either [Deislabs Slight](https://github.com/deislabs/spiderlightning) or [Fermyon Spin](https://github.com/fermyon/spin) frameworks for building and running fast, secure microservices with Wasm on Kubernetes (v1.23.16+, v1.24.10+, v1.25.6+, v1.26.1+, and newer Kubernetes versions).
+
+Both of the runtimes (slight and spin) for running Wasm workloads use [Wasmtime](https://wasmtime.dev) embedded in containerd shims via the [deislabs/containerd-wasm-shims](https://github.com/deislabs/containerd-wasm-shims) project which is built upon [containerd/runwasi](https://github.com/containerd/runwasi). These containerd shims enable Kubernetes to run Wasm workloads without needing to embed the Wasm runtime in each OCI image. 
+
+## Slight (SpiderLightning)
+"SpiderLightning defines a set of WebAssembly Interface Types (i.e., WIT) files that abstract distributed application capabilities, such as state management, pub/sub, event driven programming, and more."
+
+## Fermyon Spin
+"Spin is an open source framework for building and running fast, secure, and composable cloud microservices with WebAssembly. It aims to be the easiest way to get started with WebAssembly microservices, and takes advantage of the latest developments in the WebAssembly component model and Wasmtime runtime."
+
+### Applying the Wasm Runtime Classes
+By default, CAPZ virtual machines include containerd shims to run both `slight` and `spin` workloads. To inform Kubernetes about the ability to run these workloads on CAPZ nodes, you will need to apply a runtime class for each runtime.
+
+```yaml
+---
+apiVersion: node.k8s.io/v1
+kind: RuntimeClass
+metadata:
+  name: "wasmtime-slight-v1"
+handler: "slight"
+---
+apiVersion: node.k8s.io/v1
+kind: RuntimeClass
+metadata:
+  name: "wasmtime-spin-v1"
+handler: "spin"
+```
+
+The preceding runtime classes will register a runtime class for slight and spin, which will direct containerd to use the spin or slight shim when a pod workload is scheduled onto a cluster node.
+
+### Running an Example Spin Workload
+With the runtime classes registered, we can now schedule Wasm workloads on our nodes.
+
+```yaml
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: wasm-spin
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: wasm-spin
+  template:
+    metadata:
+      labels:
+        app: wasm-spin
+    spec:
+      runtimeClassName: wasmtime-spin-v1
+      containers:
+        - name: spin-hello
+          image: ghcr.io/deislabs/containerd-wasm-shims/examples/spin-rust-hello:latest
+          command: ["/"]
+          resources:
+            requests:
+              cpu: 10m
+              memory: 10Mi
+            limits:
+              cpu: 500m
+              memory: 128Mi
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: wasm-spin
+spec:
+  type: LoadBalancer
+  ports:
+    - protocol: TCP
+      port: 80
+      targetPort: 80
+  selector:
+    app: wasm-spin
+```
+
+The preceding deployment and service will create a load balanced "hello world" service with 3 Spin microservices. Note the `runtimeClassName` applied to the Deployment, `wasmtime-spin-v1`, which informs containerd on the cluster node to run the workload with the spin shim.
+
+### Constraining Scheduling of Wasm Workloads
+You may have a cluster where not all nodes are able to run Wasm workloads. In this case, you would want to constrain the nodes that are able to have Wasm workloads scheduled. 
+
+If you would like to constrain the nodes that will run the Wasm workloads, you can apply a node label selector to the runtime classes, and apply node labels to the cluster nodes you'd like to run the workloads.
+
+```yaml
+---
+apiVersion: node.k8s.io/v1
+kind: RuntimeClass
+metadata:
+  name: "wasmtime-slight-v1"
+handler: "slight"
+scheduling:
+  nodeSelector:
+    "cluster.x-k8s.io/wasmtime-slight-v1": "true"
+---
+apiVersion: node.k8s.io/v1
+kind: RuntimeClass
+metadata:
+  name: "wasmtime-spin-v1"
+handler: "spin"
+scheduling:
+  nodeSelector:
+    "cluster.x-k8s.io/wasmtime-spin-v1": "true"
+```
+
+In the preceding yaml, note the nodeSelector and the label. The Kubernetes scheduler will select nodes with the `cluster.x-k8s.io/wasmtime-slight-v1: "true"` or the `cluster.x-k8s.io/wasmtime-spin-v1: "true"` to determine where to schedule Wasm workloads.
+
+You will also need to pair the above runtime classes with labels applied to your cluster nodes. To label your nodes, use a command like the following:
+
+```bash
+kubectl label nodes <your-node-name> <label>
+```
+
+Once you have applied node labels, you can safely schedule Wasm workloads to a constrained set of nodes in your cluster.