Skip to content

Commit d842a6e

Browse files
nailo2cnailo2c
authored
docs: add K3s integration guide for Kubernetes deployment (#293)
* docs: add K3s integration guide for Kubernetes deployment Signed-off-by: nailo2c <nailo2c@gmail.com> * add K3s doc to i18n/zh Signed-off-by: nailo2c <nailo2c@gmail.com> --------- Signed-off-by: nailo2c <nailo2c@gmail.com>
1 parent 2950cb4 commit d842a6e

2 files changed

Lines changed: 416 additions & 0 deletions

File tree

  • docs/develop/deploy/kubernetes
  • i18n/zh/docusaurus-plugin-content-docs/current/develop/deploy/kubernetes

‎docs/develop/deploy/kubernetes/k3s.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
---
2+
sidebar_position: 12
3+
---
4+
5+
# K3s
6+
7+
[K3s](https://k3s.io/) is a lightweight, certified Kubernetes distribution designed for resource-constrained environments such as edge, IoT, and CI/CD. It bundles containerd as the default container runtime and can automatically detect WebAssembly runtimes like WasmEdge.
8+
9+
<!-- prettier-ignore -->
10+
:::note
11+
This guide is based on containerd + runwasi (containerd-shim-wasmedge).
12+
:::
13+
14+
## Prerequisites
15+
16+
- A Linux machine (x86_64 or aarch64) with systemd
17+
- Root or sudo access
18+
19+
## Install WasmEdge
20+
21+
Use the [simple install script](../../../start/install.md) to install WasmEdge on your node.
22+
23+
```bash
24+
curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash
25+
```
26+
27+
## Install the containerd-shim-wasmedge
28+
29+
K3s looks for the `containerd-shim-wasmedge-v1` binary in the system PATH. You can install it from a pre-built release binary or build it from source.
30+
31+
### Option A: Pre-built binary
32+
33+
Download the latest release from the [runwasi releases page](https://github.com/containerd/runwasi/releases) and install it.
34+
35+
```bash
36+
# Detect architecture and download the appropriate binary
37+
ARCH=$(uname -m) # x86_64 or aarch64
38+
wget https://github.com/containerd/runwasi/releases/download/containerd-shim-wasmedge%2Fv0.6.0/containerd-shim-wasmedge-${ARCH}-linux-musl.tar.gz
39+
tar xzf containerd-shim-wasmedge-${ARCH}-linux-musl.tar.gz
40+
sudo install -m 755 containerd-shim-wasmedge-v1 /usr/local/bin/
41+
```
42+
43+
### Option B: Build from source
44+
45+
Make sure you have [Rust](https://www.rust-lang.org/tools/install) installed, then build the shim from the [runwasi](https://github.com/containerd/runwasi) project.
46+
47+
```bash
48+
git clone https://github.com/containerd/runwasi.git
49+
cd runwasi
50+
./scripts/setup-linux.sh
51+
make build-wasmedge
52+
INSTALL="sudo install" LN="sudo ln -sf" make install-wasmedge
53+
```
54+
55+
## Install and start K3s
56+
57+
Install K3s after the shim binary is in place, so that K3s can detect the WasmEdge runtime at startup.
58+
59+
```bash
60+
curl -sfL https://get.k3s.io | sh -
61+
```
62+
63+
K3s will automatically detect `containerd-shim-wasmedge-v1` in the system PATH and create a corresponding Kubernetes `RuntimeClass` named `wasmedge`.
64+
65+
Verify that K3s is running and the RuntimeClass exists:
66+
67+
```bash
68+
sudo kubectl get nodes
69+
sudo kubectl get runtimeclass
70+
```
71+
72+
Expected output:
73+
74+
```bash
75+
$ sudo kubectl get nodes
76+
NAME STATUS ROLES AGE VERSION
77+
ubuntu Ready control-plane 45s v1.34.6+k3s1
78+
79+
$ sudo kubectl get runtimeclass
80+
NAME HANDLER AGE
81+
crun crun 45s
82+
lunatic lunatic 45s
83+
nvidia nvidia 45s
84+
nvidia-experimental nvidia-experimental 45s
85+
slight slight 45s
86+
spin spin 45s
87+
wasmedge wasmedge 45s
88+
wasmer wasmer 45s
89+
wasmtime wasmtime 45s
90+
wws wws 45s
91+
```
92+
93+
Make sure `wasmedge` is in the list.
94+
95+
<!-- prettier-ignore -->
96+
:::note
97+
If the `wasmedge` RuntimeClass does not appear, make sure the `containerd-shim-wasmedge-v1` binary is in a directory listed in the K3s service's PATH (e.g., `/usr/local/bin`), then restart K3s with `sudo systemctl restart k3s`.
98+
:::
99+
100+
## Run a simple WebAssembly app
101+
102+
[A separate article](https://github.com/second-state/wasmedge-containers-examples/blob/main/simple_wasi_app.md) explains how to compile, package, and publish a simple WebAssembly WASI program as a container image to Docker Hub. Run the WebAssembly-based image from Docker Hub in the K3s cluster as follows.
103+
104+
```bash
105+
sudo kubectl run --restart=Never wasi-demo \
106+
--image=wasmedge/example-wasi:latest \
107+
--overrides='{"kind":"Pod","apiVersion":"v1","spec":{"runtimeClassName":"wasmedge"}}' \
108+
-- /wasi_example_main.wasm 50000000
109+
```
110+
111+
Check the pod status and view the output:
112+
113+
```bash
114+
sudo kubectl get pod wasi-demo
115+
sudo kubectl logs wasi-demo
116+
```
117+
118+
The output from the containerized application is printed into the console.
119+
120+
```bash
121+
$ sudo kubectl get pod wasi-demo
122+
NAME READY STATUS RESTARTS AGE
123+
wasi-demo 0/1 Completed 0 7s
124+
125+
$ sudo kubectl logs wasi-demo
126+
Random number: -817406905
127+
Random bytes: [7, 7, 147, 202, 106, 102, 198, 6, 42, 39, 198, 92, 59, 247, 54, 99, 249, 117, 113, 143, 240, 85, 226, 102, 44, 165, 66, 251, 220, 107, 106, 70, 168, 144, 114, 113, 77, 132, 114, 33, 155, 254, 169, 196, 218, 119, 171, 145, 106, 36, 205, 130, 43, 208, 152, 127, 60, 57, 26, 160, 178, 75, 3, 215, 98, 32, 223, 67, 176, 35, 182, 141, 2, 190, 15, 72, 167, 44, 46, 148, 240, 1, 110, 148, 19, 134, 182, 21, 127, 141, 106, 65, 27, 84, 121, 217, 171, 36, 88, 47, 197, 96, 193, 102, 143, 105, 67, 77, 40, 187, 40, 151, 60, 140, 238, 143, 8, 89, 129, 117, 103, 157, 102, 34, 65, 5, 195, 246]
128+
Printed from wasi: This is from a main function
129+
This is from a main function
130+
The env vars are as follows.
131+
The args are as follows.
132+
/wasi_example_main.wasm
133+
50000000
134+
File content is This is in a file
135+
```
136+
137+
Clean up the pod after verifying:
138+
139+
```bash
140+
sudo kubectl delete pod wasi-demo
141+
```
142+
143+
## Run a WebAssembly-based HTTP service
144+
145+
[A separate article](https://github.com/second-state/wasmedge-containers-examples/blob/main/http_server_wasi_app.md) explains how to compile, package, and publish a simple WebAssembly HTTP service application as a container image to Docker Hub. Create a deployment using a YAML file:
146+
147+
```yaml
148+
apiVersion: apps/v1
149+
kind: Deployment
150+
metadata:
151+
name: http-server
152+
spec:
153+
replicas: 1
154+
selector:
155+
matchLabels:
156+
app: http-server
157+
template:
158+
metadata:
159+
labels:
160+
app: http-server
161+
spec:
162+
runtimeClassName: wasmedge
163+
containers:
164+
- name: http-server
165+
image: wasmedge/example-wasi-http:latest
166+
ports:
167+
- containerPort: 1234
168+
protocol: TCP
169+
---
170+
apiVersion: v1
171+
kind: Service
172+
metadata:
173+
name: http-server
174+
spec:
175+
type: NodePort
176+
selector:
177+
app: http-server
178+
ports:
179+
- port: 1234
180+
targetPort: 1234
181+
```
182+
183+
Save the above as `k3s-http-server.yaml` and apply it:
184+
185+
```bash
186+
sudo kubectl apply -f k3s-http-server.yaml
187+
```
188+
189+
Wait for the pod to be ready, then get the NodePort:
190+
191+
```bash
192+
sudo kubectl get svc http-server
193+
```
194+
195+
Access the HTTP service using the NodePort:
196+
197+
```bash
198+
curl -d "name=WasmEdge" -X POST http://localhost:<NodePort>
199+
echo: name=WasmEdge
200+
```
201+
202+
Clean up the deployment and service after verifying:
203+
204+
```bash
205+
sudo kubectl delete -f k3s-http-server.yaml
206+
```
207+
208+
That's it!

0 commit comments

Comments
 (0)