Skip to content

Commit 4975d24

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #3161 from devigned/wasm-docs
add documentation for running wasm workloads
2 parents b188333 + 3637970 commit 4975d24

File tree

3 files changed

+154
-1
lines changed

3 files changed

+154
-1
lines changed

‎.codespellignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,5 @@ ot
55
updat
66
shouldnot
77
decorder
8-
overriden
8+
overriden
9+
wit

‎docs/book/src/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
- [VM Identity](./topics/vm-identity.md)
3232
- [Windows](./topics/windows.md)
3333
- [Flatcar](./topics/flatcar.md)
34+
- [WebAssembly / WASI Pods](./topics/wasi.md)
3435
- [Development](./developers/development.md)
3536
- [Kubernetes Developers](./developers/kubernetes-developers.md)
3637
- [Releasing](./developers/releasing.md)

‎docs/book/src/topics/wasi.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# WebAssembly / WASI Workloads
2+
3+
## Overview
4+
5+
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 on Kubernetes (v1.23.16+, v1.24.10+, v1.25.6+, v1.26.1+, and newer Kubernetes versions).
6+
7+
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.
8+
9+
## Slight (SpiderLightning)
10+
Slight (or Spiderlightning) is an open source wasmtime-based runtime that provides cloud capabilities to Wasm microservices. These capabilities include key/value, pub/sub, and much more.
11+
12+
## Fermyon Spin
13+
"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."
14+
15+
### Applying the Wasm Runtime Classes
16+
By default, CAPZ reference virtual machine images 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 (`slight` and `spin`) to your workload cluster.
17+
18+
```yaml
19+
---
20+
apiVersion: node.k8s.io/v1
21+
kind: RuntimeClass
22+
metadata:
23+
name: "wasmtime-slight-v1"
24+
handler: "slight"
25+
---
26+
apiVersion: node.k8s.io/v1
27+
kind: RuntimeClass
28+
metadata:
29+
name: "wasmtime-spin-v1"
30+
handler: "spin"
31+
```
32+
33+
The preceding YAML document 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.
34+
35+
### Running an Example Spin Workload
36+
With the runtime classes registered, we can now schedule Wasm workloads on our nodes by applying the following YAML document to your workload cluster.
37+
38+
```yaml
39+
---
40+
apiVersion: apps/v1
41+
kind: Deployment
42+
metadata:
43+
name: wasm-spin
44+
spec:
45+
replicas: 3
46+
selector:
47+
matchLabels:
48+
app: wasm-spin
49+
template:
50+
metadata:
51+
labels:
52+
app: wasm-spin
53+
spec:
54+
runtimeClassName: wasmtime-spin-v1
55+
containers:
56+
- name: spin-hello
57+
image: ghcr.io/deislabs/containerd-wasm-shims/examples/spin-rust-hello:latest
58+
command: ["/"]
59+
resources:
60+
requests:
61+
cpu: 10m
62+
memory: 10Mi
63+
limits:
64+
cpu: 500m
65+
memory: 128Mi
66+
---
67+
apiVersion: v1
68+
kind: Service
69+
metadata:
70+
name: wasm-spin
71+
spec:
72+
type: LoadBalancer
73+
ports:
74+
- protocol: TCP
75+
port: 80
76+
targetPort: 80
77+
selector:
78+
app: wasm-spin
79+
```
80+
81+
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.
82+
83+
### A Running Spin Microservice
84+
With the service and the deployment applied, you should now have a Spin microservice running in your workload cluster. If you run the following command against the workload cluster, you can find the IP for the `wasm-spin` service.
85+
86+
```shell
87+
kubectl get services -w
88+
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
89+
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 14m
90+
wasm-spin LoadBalancer 10.105.51.137 20.121.244.48 80:30197/TCP 3m8s
91+
```
92+
93+
In the preceding output, we can see the `wasm-spin` service with an external IP of `20.121.244.48`. Your external IP will be a different IP address, but that is expected.
94+
95+
Next, let's curl the service and get a response from our Wasm microservice. You will need to replace the placeholder IP address with the external IP address from the preceding output.
96+
97+
```shell
98+
curl http://20.121.244.48/hello
99+
Hello world from Spin!
100+
```
101+
102+
In the preceding output, we see the HTTP response from our Spin microservice, "Hello world from Spin!".
103+
104+
### Building a Spin or Slight Application
105+
At this point, you might be asking "How do I build my own Wasm microservice?" Here are a couple pointers to help you get started.
106+
107+
#### Example `slight` Application
108+
The [`slight` example in deislabs/containerd-wasm-shims repo](https://github.com/deislabs/containerd-wasm-shims/tree/ad323c4e773633630706cf1d354293dec90e61e6/images/slight) demonstrates a project layout for creating a container image consisting of a `slight` `app.wasm` and a `slightfile.toml`, both of which are needed to run the microservice.
109+
110+
To learn more about building `slight` applications, see [Deislabs Slight](https://github.com/deislabs/spiderlightning).
111+
112+
#### Example `spin` Application
113+
The [`spin` example in deislabs/containerd-wasm-shims repo](https://github.com/deislabs/containerd-wasm-shims/tree/ad323c4e773633630706cf1d354293dec90e61e6/images/spin) demonstrates a project layout for creating a container image consisting of two `spin` apps, `spin_rust_hello.wasm` and `spin_go_hello.wasm`, and a `spin.toml` file.
114+
115+
To learn more about building `spin` applications, see [Fermyon Spin](https://github.com/fermyon/spin).
116+
117+
### Constraining Scheduling of Wasm Workloads
118+
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.
119+
120+
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.
121+
122+
```yaml
123+
---
124+
apiVersion: node.k8s.io/v1
125+
kind: RuntimeClass
126+
metadata:
127+
name: "wasmtime-slight-v1"
128+
handler: "slight"
129+
scheduling:
130+
nodeSelector:
131+
"cluster.x-k8s.io/wasmtime-slight-v1": "true"
132+
---
133+
apiVersion: node.k8s.io/v1
134+
kind: RuntimeClass
135+
metadata:
136+
name: "wasmtime-spin-v1"
137+
handler: "spin"
138+
scheduling:
139+
nodeSelector:
140+
"cluster.x-k8s.io/wasmtime-spin-v1": "true"
141+
```
142+
143+
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.
144+
145+
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:
146+
147+
```bash
148+
kubectl label nodes <your-node-name> <label>
149+
```
150+
151+
Once you have applied node labels, you can safely schedule Wasm workloads to a constrained set of nodes in your cluster.

0 commit comments

Comments
 (0)