Quickstart

This Quickstart guide demonstrates how to set up a development Kubernetes cluster, install SpinKube and deploy your first Spin application. This example creates a kind cluster with the Spin containerd shim pre-installed on all nodes. In production, you should use the runtime class manager to install and manage the lifecycle of the containerd shim. Jump to the Helm installation for more production cluster installation instructions.

Prerequisites

For this Quickstart guide, you will need:

• kubectl - the Kubernetes CLI
• A container runtime, such as Docker Desktop, Rancher Desktop or OrbStack
• kind - a tool for running local development Kubernetes clusters using Docker container “nodes”.
• Helm - the package manager for Kubernetes

Set up Your Kubernetes Cluster

1. Create a Kubernetes cluster with a kind image that includes the containerd-shim-spin prerequisite already installed. During creation of the kind cluster, we add containerd configuration to instruct containerd to use the Spin containerd shim for workloads scheduled with the spin runtime class.:

cat <<EOF | kind create cluster --name wasm-cluster --image ghcr.io/spinframework/containerd-shim-spin/kind:v0.25.0 --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
containerdConfigPatches:
- |-
  [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.spin]
    runtime_type = "io.containerd.spin.v2"
  [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.spin.options]
    SystemdCgroup = true
EOF

2. Install cert-manager

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.20.0/cert-manager.yaml
kubectl wait --for=condition=available --timeout=300s deployment/cert-manager-webhook -n cert-manager

3. Apply the Runtime Class used for scheduling Spin apps onto nodes running the shim:

Note: In a production cluster you likely want to customize the Runtime Class with a nodeSelector that matches nodes that have the shim installed. However, in the kind example, the shim is pre-configured on every node.

kubectl apply -f https://github.com/spinframework/spin-operator/releases/download/v0.6.1/spin-operator.runtime-class.yaml

1. Apply the Custom Resource Definitions used by the Spin Operator:

kubectl apply -f https://github.com/spinframework/spin-operator/releases/download/v0.6.1/spin-operator.crds.yaml

Deploy the Spin Operator

Execute the following command to install the Spin Operator on the cluster using Helm. This will create all of the Kubernetes resources required by Spin Operator under the Kubernetes namespace spin-operator. It may take a moment for the installation to complete as dependencies are installed and pods are spinning up.

# Install Spin Operator with Helm
helm upgrade --install spin-operator \
  --namespace spin-operator \
  --create-namespace \
  --version 0.6.1 \
  --wait \
  oci://ghcr.io/spinframework/charts/spin-operator

Lastly, create the shim executor:

kubectl apply -f https://github.com/spinframework/spin-operator/releases/download/v0.6.1/spin-operator.shim-executor.yaml

Run the Sample Application

You are now ready to deploy Spin applications onto the cluster!

1. Create your first application in the same spin-operator namespace that the operator is running:

kubectl apply -f https://raw.githubusercontent.com/spinframework/spin-operator/main/config/samples/simple.yaml

2. Forward a local port to the application pod so that it can be reached:

kubectl port-forward svc/simple-spinapp 8083:80

3. In a different terminal window, make a request to the application:

curl localhost:8083/hello

You should see:

Hello world from Spin!

Next Steps

Congrats on deploying your first SpinApp! Recommended next steps:

• Scale your Spin Apps with Horizontal Pod Autoscaler (HPA)
• Scale your Spin Apps with Kubernetes Event Driven Autoscaler (KEDA)