Blog guide

March 19, 2024

Run SpinKube on Rancher Desktop

Matt Butcher

spinkube rancher suse containers

Rancher Desktop, an open source application for running Docker containers and Kubernetes on your local system, now has built-in support for Spin. And it’s a piece of cake to install SpinKube and be up and running in just a few minutes.

In this post we’ll install Rancher Desktop, and then add SpinKube. After that, we’ll build a simple JavaScript app and deploy it into our Rancher Desktop cluster.

Installing Rancher Desktop

To start, grab the latest version of Rancher Desktop. (Spin support was added in version 1.13.) The first time you run it, you will be prompted to choose a container runtime. Select containerd, which is the runtime that best supports WebAssembly in Rancher’s k3s lightweight variety of Kubernetes.

If you already have Rancher Desktop installed, you can check the Container Engine Preferences to ensure that containerd is your runtime (and change it, if necessary). This can be done by launching the desktop, clicking Preferences and going to Container Engine.

Also, please select rancher-desktop from the Kubernetes Contexts configuration.

Those are the only bits of configuration you need to do. Let’s get started!

Installing SpinKube on k3s

SpinKube adds a useful controller that makes it easy to create and launch Spin apps. We’ll get it all installed and configured before building our first Spin app in the next section.

These instructions are abbreviated from the SpinKube QuickStart guide.

Later versions of the Helm chart may automate more of these steps. So take a quick glance at the QuickStart before installing.

We’ll be installing the following:

• The CertManager for SSL
• The CRDs for SpinKube
• SpinKube itself via a Helm chart
• The KWasm runtime class manager

# Cert Manager
$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
# CRDs
$ kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.crds.yaml
$ kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.runtime-class.yaml
$ kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.shim-executor.yaml

Install Spin Operator with Helm

The Spin operator handles SpinApp applications:

$ helm install spin-operator \
  --namespace spin-operator \
  --create-namespace \
  --version 0.1.0 \
  --wait \
  oci://ghcr.io/spinkube/charts/spin-operator

Installing the KWasm Runtime Class Manager

Next we need to install the operator that manages the runtimes:

$ helm repo add kwasm http://kwasm.sh/kwasm-operator/

$ helm install \
  kwasm-operator kwasm/kwasm-operator \
  --namespace kwasm \
  --create-namespace \
  --set kwasmOperator.installerImage=ghcr.io/spinkube/containerd-shim-spin/node-installer:v0.13.1

$ kubectl annotate node --all kwasm.sh/kwasm-node=true

Now we’ve got SpinKube installed and configured. We can move on to creating an app.

Creating a Spin App

We’ll create a simple Spin JavaScript app:

$ spin new -t http-js hello-k3s --accept-defaults
$ cd hello-k3s
$ npm install

Now let’s make a trivial edit to src/index.js:

export async function handleRequest(request) {
    return {
        status: 200,
        headers: {"content-type": "text/plain"},
        body: "Hello from Rancher Desktop" // <-- This changed
    }
}

I changed the body message in the code above.

All that’s left to do is build the app:

$ spin build

Next up, we’ll take our Spin app and deploy it to the k3s that is running in Rancher Desktop.

Deploying a Spin App to Rancher Desktop with SpinKube

We have Rancher Desktop setup, and SpinKube installed. And we just finished building a new JS application. All that’s left to do is deploy it. The best reference for deploying is the Packaging and Distributing Spin Apps tutorial.

First, we will push the image to a registry. You can use any container registry you prefer (like DockerHub). But for this tutorial, we’ll use a simple one that does not require authentication:

$ spin registry push ttl.sh/hello-k3s:0.1.0

To read the configuration, we can use the spin kube scaffold command:

$ spin kube scaffold --from ttl.sh/hello-k3s:0.1.0
apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: hello-k3s
spec:
  image: "ttl.sh/hello-k3s:0.1.0"
  executor: containerd-shim-spin
  replicas: 2

Now, we can deploy the app into our cluster:

$ spin kube deploy --from ttl.sh/hello-k3s:0.1.0

If we click on the Rancher Desktop’s “Cluster Dashboard”, we can see hello-k3s:0.1.0 running inside the “Workloads” dropdown section:

To access our app outside of the cluster, we can forward the port so that we access the application from our host machine:

$ kubectl port-forward svc/hello-k3s 8083:80

With that, we’re ready to test out the app:

$ curl localhost:8083
Hello from Rancher Desktop

And there you have it! We’ve got the latest Rancher Desktop running the latest SpinKube, and we’ve created and loaded our first Spin app.

Rancher Desktop operates on Windows, macOS, and Linux. This dynamic duo of Rancher Desktop and SpinKube, both open-source projects hosted on GitHub, offers a robust platform for efficiently building and deploying WebAssembly applications within a Kubernetes ecosystem. Be one of the trailblazers in integrating Rancher Desktop and SpinKube to enhance your development and deployment workflows. For additional information, visit the SpinKube project website and explore Rancher Desktop by SUSE.