Running WebAssembly Workloads on Kubernetes: The Complete Guide to SpinKube, containerd Wasm Shim, and runwasi

// Simple Wasm module example written in Rust
// Requires [lib] crate-type = ["cdylib"] in Cargo.toml

#[no_mangle]
pub extern "C" fn add(a: i32, b: i32) -> i32 {
    a + b
}

#[no_mangle]
pub extern "C" fn fibonacci(n: i32) -> i64 {
    if n <= 1 {
        return n as i64;
    }
    let mut a: i64 = 0;
    let mut b: i64 = 1;
    for _ in 2..=n {
        let temp = b;
        b = a + b;
        a = temp;
    }
    b
}

# Build for the Wasm target
rustup target add wasm32-wasi
cargo build --target wasm32-wasi --release

# Check the build artifact size (typically a few KB to a few MB)
ls -lh target/wasm32-wasi/release/*.wasm

# Run directly with Wasmtime
wasmtime target/wasm32-wasi/release/my_module.wasm

# Example of granting filesystem access in WASI
# The --dir flag allows access only to a specific directory
wasmtime --dir=/tmp/data::./data my_app.wasm

# When network access is required
wasmtime --tcplisten=0.0.0.0:8080 my_server.wasm

// WIT interface definition example
package example:http-handler@1.0.0;

interface types {
    record http-request {
        method: string,
        uri: string,
        headers: list<tuple<string, string>>,
        body: option<list<u8>>,
    }

    record http-response {
        status: u16,
        headers: list<tuple<string, string>>,
        body: option<list<u8>>,
    }
}

world http-handler {
    import wasi:logging/logging;
    export handle-request: func(req: types.http-request) -> types.http-response;
}

kubelet → CRI → containerd → OCI Runtime (runc) → Linux Container

kubelet → CRI → containerd → containerd-shim-spin-v2 → Wasmtime/Spin → Wasm Module
                           → containerd-shim-slight-v2 → Wasmtime/SpiderLightning → Wasm Module
                           → containerd-shim-wasmedge-v1 → WasmEdge → Wasm Module

// Core trait structure of runwasi (simplified)
pub trait Engine {
    fn name() -> &'static str;
    fn run_wasi(&self, ctx: &WasiCtx, module: &[u8]) -> Result<i32>;
}

// Wasmtime engine implementation
pub struct WasmtimeEngine;
impl Engine for WasmtimeEngine {
    fn name() -> &'static str { "wasmtime" }
    fn run_wasi(&self, ctx: &WasiCtx, module: &[u8]) -> Result<i32> {
        // Execute Wasm module using Wasmtime
        let engine = wasmtime::Engine::default();
        let module = wasmtime::Module::new(&engine, module)?;
        // ...
    }
}

# RuntimeClass definition
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: wasmtime-spin-v2
handler: spin
scheduling:
  nodeSelector:
    kubernetes.io/arch: wasm32-wasi
---
# Wasm workload Pod
apiVersion: v1
kind: Pod
metadata:
  name: wasm-hello
spec:
  runtimeClassName: wasmtime-spin-v2
  containers:
    - name: hello-wasm
      image: ghcr.io/example/hello-wasm:v1
      command: ['/hello.wasm']
  nodeSelector:
    kubernetes.io/arch: wasm32-wasi

┌─────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                 │
│                                                       │
│  ┌──────────────┐       ┌────────────────────────┐  │
│  │ Spin Operator│       │    API Server           │  │
│  │              │◄──────│                         │  │
│  │ - SpinApp    │       │ SpinApp CRD registered  │  │
│  │   Controller │       └────────────────────────┘  │
│  │ - Executor   │                                    │
│  │   Selection  │                                    │
│  └──────┬───────┘                                    │
│         │ Creates/Manages                            │
│         ▼                                            │
│  ┌──────────────┐       ┌────────────────────────┐  │
│  │  Deployment  │       │   Node (Wasm-capable)   │  │
│  │  or          │──────►│                         │  │
│  │  SpinAppExec │       │  containerd             │  │
│  └──────────────┘       │    └─ shim-spin-v2      │  │
│                         │        └─ Spin Runtime  │  │
│                         │            └─ .wasm     │  │
│                         └────────────────────────┘  │
└─────────────────────────────────────────────────────┘

apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: hello-spin
  namespace: default
spec:
  image: ghcr.io/example/hello-spin:v1
  replicas: 3
  executor: containerd-shim-spin
  enableAutoscaling: true
  resources:
    limits:
      cpu: 100m
      memory: 128Mi
  variables:
    - name: DATABASE_URL
      valueFrom:
        secretKeyRef:
          name: db-credentials
          key: url
  runtime-config:
    key_value_stores:
      default:
        type: redis
        url: redis://redis-cluster:6379
    sqlite_databases:
      default:
        type: libsql
        url: https://my-turso-db.turso.io

# Create a k3d cluster (using an image that includes the Wasm shim)
k3d cluster create wasm-cluster \
  --image ghcr.io/spinkube/containerd-shim-spin/k3d:v0.17.0 \
  --port "8081:80@loadbalancer" \
  --agents 2

# Verify cluster status
kubectl get nodes
kubectl get runtimeclass

# Labeling Wasm-capable nodes with Node Feature Discovery
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: wasm-shim-installer
  namespace: kube-system
spec:
  selector:
    matchLabels:
      app: wasm-shim-installer
  template:
    metadata:
      labels:
        app: wasm-shim-installer
    spec:
      hostPID: true
      containers:
        - name: installer
          image: ghcr.io/spinkube/containerd-shim-spin/node-installer:v0.17.0
          securityContext:
            privileged: true
          volumeMounts:
            - name: containerd-config
              mountPath: /etc/containerd
            - name: shim-binary
              mountPath: /opt/kwasm/bin
      volumes:
        - name: containerd-config
          hostPath:
            path: /etc/containerd
        - name: shim-binary
          hostPath:
            path: /opt/kwasm/bin

# Install cert-manager (required for the Spin Operator's webhook)
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.0/cert-manager.yaml

# Install SpinKube CRDs
kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.4.0/spin-operator.crds.yaml

# Configure RuntimeClass
kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.4.0/spin-operator.runtime-class.yaml

# Install Spin Operator via Helm
helm install spin-operator \
  --namespace spin-operator \
  --create-namespace \
  --version 0.4.0 \
  oci://ghcr.io/spinkube/charts/spin-operator

# Create a SpinAppExecutor
kubectl apply -f - <<EOF
apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinAppExecutor
metadata:
  name: containerd-shim-spin
spec:
  createDeployment: true
  deploymentConfig:
    runtimeClassName: wasmtime-spin-v2
EOF

# Create a new project with the Spin CLI
spin new -t http-rust hello-k8s --accept-defaults
cd hello-k8s

// src/lib.rs - Spin HTTP handler
use spin_sdk::http::{IntoResponse, Request, Response};
use spin_sdk::http_component;

#[http_component]
fn handle_request(req: Request) -> anyhow::Result<impl IntoResponse> {
    let path = req.path();
    let method = req.method().to_string();

    println!("Received {method} request for {path}");

    let body = serde_json::json!({
        "message": "Hello from WebAssembly on Kubernetes!",
        "path": path,
        "method": method,
        "runtime": "SpinKube",
        "timestamp": chrono::Utc::now().to_rfc3339()
    });

    Ok(Response::builder()
        .status(200)
        .header("content-type", "application/json")
        .body(body.to_string())
        .build())
}

# Build and push to an OCI registry
spin build
spin registry push ghcr.io/myorg/hello-k8s:v1

# Deploy as a SpinApp
kubectl apply -f - <<EOF
apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: hello-k8s
spec:
  image: ghcr.io/myorg/hello-k8s:v1
  replicas: 3
  executor: containerd-shim-spin
EOF

# Check deployment status
kubectl get spinapp hello-k8s
kubectl get pods -l core.spinoperator.dev/app-name=hello-k8s

# Memory usage comparison with 100 concurrent instances (wrk benchmark)
# Docker Container: ~6.4GB (64MB per instance avg)
# Spin Wasm:        ~320MB (3.2MB per instance avg)
# Memory efficiency: Wasm uses approximately 20x less memory

# Benchmark command
wrk -t12 -c400 -d30s http://localhost:8080/api/json

# Docker Container (Go HTTP Server)
# Requests/sec: 45,230
# Avg Latency: 8.8ms
# Transfer/sec: 12.3MB

# Spin Wasm (Rust HTTP Handler)
# Requests/sec: 38,750
# Avg Latency: 10.3ms
# Transfer/sec: 10.5MB

# Wasm Pods currently have restrictions with HostPort and NodePort bindings
# Service mesh sidecar patterns (Istio, Linkerd) do not work
# → This can be worked around using Spin's built-in HTTP triggers

# Recommended configuration
apiVersion: v1
kind: Service
metadata:
  name: wasm-service
spec:
  type: ClusterIP # NodePort/LoadBalancer are possible but verify limitations
  selector:
    core.spinoperator.dev/app-name: hello-k8s
  ports:
    - port: 80
      targetPort: 80

# Basic commands for debugging Wasm workloads
kubectl logs -l core.spinoperator.dev/app-name=hello-k8s -f
kubectl describe spinapp hello-k8s
kubectl get events --field-selector involvedObject.name=hello-k8s

# Node pool separation strategy
# Pool 1: Standard container workloads
# Pool 2: Wasm-dedicated nodes with Wasm shim installed

# Add a taint to Wasm nodes
kubectl taint nodes wasm-node-1 workload-type=wasm:NoSchedule

# Add a toleration to the SpinApp
apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: edge-handler
spec:
  image: ghcr.io/myorg/edge-handler:v1
  replicas: 5
  executor: containerd-shim-spin
  deploymentAnnotations:
    app.kubernetes.io/part-of: edge-system
  podSpec:
    tolerations:
      - key: workload-type
        operator: Equal
        value: wasm
        effect: NoSchedule
    nodeSelector:
      kubernetes.io/arch: wasm32-wasi