Containerd Shim Spin

https://github.com/spinframework/containerd-shim-spin
Admin
A containerd shim implementation that enables running Spin WebAssembly workloads on Kubernetes via...
Tokens:6,777
Snippets:108
Trust Score:-
License:Apache-2.0
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Spin CLI

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/images/spin-dapr/README.md

Installs the Spin CLI tool. This command downloads the installer script and moves the spin binary to /usr/local/bin.

```sh
curl -fsSL https://developer.fermyon.com/downloads/install.sh | bash
sudo mv ./spin /usr/local/bin/
```

--------------------------------

### Provide Application Details

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Example of providing details when prompted by 'spin new'.

```output
$ spin new -t http-rust qs-wasm-spin
Description: An example app for the quickstart
HTTP path: /hi
```

--------------------------------

### Build, Install, and Run Containerd Shim Spin

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/README.md

Execute this command to build, install, and run the shim binary. Ensure dependencies are set up first.

```bash
make run
```

--------------------------------

### Install Docker 24.0.0-beta.2

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/DockerSetup.md

Installs the specified beta version of Docker using the official installation script. Ensure you have uninstalled previous versions first.

```shell
curl -fsSL https://get.docker.com -o get-docker.sh

sudo CHANNEL=test sh get-docker.sh
```

--------------------------------

### Build and Install Shim

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/conformance-tests/README.md

Build the release version of the shim and copy the binary to the system's executable path.

```sh
cargo build --release
sudo cp target/release/containerd-shim-spin-v2 /usr/bin/
```

--------------------------------

### Start Kind Cluster with Spin Shim

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Starts a Kind cluster pre-configured with the containerd-shim-spin. Ensure containerd is enabled in your Docker settings.

```bash
cat <<EOF | kind create cluster --name wasm-cluster --image ghcr.io/spinframework/containerd-shim-spin/kind:v0.24.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
```

--------------------------------

### Setup Linux Environment for Containerd Shim Spin

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/README.md

Run this command to set up the Linux environment before building and running the shim.

```bash
make setup
```

--------------------------------

### Spin Application Local URL

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Example output showing the local URL and available routes for a running Spin application.

```output
$ spin up
Serving http://127.0.0.1:3000
Available Routes:
  qs-wasm-spin: http://127.0.0.1:3000/hi
```

--------------------------------

### Build Development Installer Image

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/node-installer/README.md

Use this command to build the development version of the node installer image locally. This is useful for testing or custom modifications.

```bash
make build-dev-installer-image
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/DockerSetup.md

Confirms that the correct version of Docker has been installed by checking the version information.

```shell
docker version

> Docker version 24.0.0-beta.2
```

--------------------------------

### Install Dapr CLI

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/images/spin-dapr/README.md

Installs the Dapr command-line interface. Ensure you have curl installed.

```sh
curl -fsSL https://raw.githubusercontent.com/dapr/cli/master/install/install.sh | bash
```

--------------------------------

### Create Kind Cluster with Spin Shim

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/README.md

Builds a Kind cluster image with the Spin shim and configures containerd. Applies runtime classes and an example workload, then forwards the service port and tests with curl.

```shell
docker build -t kind-shim-test deployments/kind
cat <<EOF | kind create cluster --name wasm-cluster --image kind-shim-test --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
kubectl apply -f https://github.com/spinframework/containerd-shim-spin/raw/main/deployments/workloads/runtime.yaml
kubectl apply -f https://github.com/spinframework/containerd-shim-spin/raw/main/deployments/workloads/workload.yaml
echo "waiting 15 seconds for workload to be ready"
sleep 15
kubectl port-forward svc/wasm-spin 8081:80 &
curl -v http://127.0.0.1:8081/hello
```

--------------------------------

### Build Spin Application

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Builds the Spin application for the wasm32-wasip1 target. Ensure you have Rust and the Spin CLI installed.

```bash
cd qs-wasm-spin
rustup target add wasm32-wasip1
spin build
```

--------------------------------

### Run Spin Application Locally

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Starts the Spin application on your development machine, providing a local URL for access. Stop the application by returning to its terminal and pressing Ctrl+C.

```bash
spin up
```

--------------------------------

### Deploy Spin App with RuntimeClass

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/README.md

Example Kubernetes Deployment manifest for a Spin application. It specifies the `wasmtime-spin-v2` RuntimeClass, ensuring the application is executed with the containerd-shim-spin.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: wasm-spin
spec:
  replicas: 1
  selector:
    matchLabels:
      app: wasm-spin
  template:
    metadata:
      labels:
        app: wasm-spin
    spec:
      runtimeClassName: wasmtime-spin-v2
      containers:
        - name: spin-hello
          image: ghcr.io/spinframework/containerd-shim-spin/examples/spin-rust-hello:v0.20.0
          command: ["/"]

```

--------------------------------

### Uninstall Existing Docker Tools

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/DockerSetup.md

Before installing a specific Docker version, remove any existing Docker-related packages to avoid conflicts.

```shell
sudo apt-get purge docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin docker-ce-rootless-extras
```

--------------------------------

### Kubernetes RuntimeClass for Spin

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/README.md

Apply this Kubernetes `RuntimeClass` definition to your cluster. Ensure the `handler` field matches the runtime name configured in containerd. Consider using `nodeSelector` to target nodes with the shim installed.

```yaml
apiVersion: node.k8s.io/v1
handler: spin
kind: RuntimeClass
metadata:
  name: wasmtime-spin-v2

```

--------------------------------

### Run Conformance Tests (Option 1)

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/conformance-tests/README.md

Build the conformance tests binary and execute it with sudo, providing paths to the Spin and ctr binaries.

```sh
cargo build 
sudo ../target/debug/conformance-tests /path/to/spin /path/to/ctr
```

--------------------------------

### Deploy Sample Spin Application and Port-Forward

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Deploys a pre-built sample Spin application to the cluster and sets up port forwarding to access it locally on port 8081.

```bash
kubectl apply -f https://raw.githubusercontent.com/spinframework/containerd-shim-spin/main/deployments/workloads/workload.yaml
echo "waiting 5 seconds for workload to be ready"
sleep 5
kubectl port-forward svc/wasm-spin 8081:80
```

--------------------------------

### Create New Spin Application

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Initializes a new Spin application using the 'http-rust' template. You will be prompted to provide a description and HTTP path.

```bash
spin new -t http-rust qs-wasm-spin
```

--------------------------------

### Build from Source

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/README.md

Builds the project from source using the 'make up' command.

```shell
make up
```

--------------------------------

### Run Conformance Tests (Option 2)

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/conformance-tests/README.md

Run cargo as root, preserving the user's environment, and provide paths to the Spin and ctr binaries.

```sh
sudo -E $HOME/.cargo/bin/cargo run /path/to/spin /path/to/ctr
```

--------------------------------

### Deploy and Test Spin Application on Kubernetes

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Apply the Kubernetes configuration to deploy the application and then test its accessibility using curl. A 5-second delay is included to allow the workload to become ready.

```bash
kubectl apply -f qs.yaml
echo "waiting 5 seconds for workload to be ready"
sleep 5
curl -v http://0.0.0.0:8081/hi

```

--------------------------------

### Build and Push Container Image

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Build a container image for the Spin application using Docker and push it to a registry like TTL.sh.

```bash
docker buildx build --platform=wasip1/wasm -t ttl.sh/spin-quickstart/qs-wasm-spin .
docker push ttl.sh/spin-quickstart/qs-wasm-spin:latest

```

--------------------------------

### Configure Containerd Runtime

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/conformance-tests/README.md

Add the Spin shim as a runtime in the containerd configuration file.

```toml
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.spin]
    runtime_type = "/usr/bin/containerd-shim-spin-v2"
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.spin.options]
    SystemdCgroup = true
```

--------------------------------

### Configure and Create Kind Cluster

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/images/spin-dapr/README.md

Sets up a Kind Kubernetes cluster with specific containerd configurations for Spin runtime. This configuration is crucial for running Spin workloads within the cluster.

```sh
# start the Kind cluster
cat <<EOF | kind create cluster --name wasm-cluster --image ghcr.io/spinframework/containerd-shim-spin/kind:v0.24.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
```

--------------------------------

### Verify Sample Application Response

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Confirms that the sample Spin application is running and accessible by making a curl request to the forwarded port.

```output
$ curl -v http://0.0.0.0:8081/hello
*   Trying 0.0.0.0:8081...
* TCP_NODELAY set
* Connected to 0.0.0.0 (127.0.0.1) port 8081 (#0)
> GET /hello HTTP/1.1
> Host: 0.0.0.0:8081
> User-Agent: curl/7.68.0
> Accept: */*
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Content-Length: 22
< Date: Mon, 10 Oct 2022 20:39:43 GMT
< Content-Type: text/plain; charset=utf-8
< 
* Connection #0 to host 0.0.0.0 left intact
Hello world from Spin!
```

--------------------------------

### Configure containerd for Spin Runtime (v2+)

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/README.md

Add this configuration to your containerd `config.toml` if you are using containerd version 2 or later. It maps the 'spin' runtime type to the shim binary and enables SystemdCgroup.

```toml
[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

```

--------------------------------

### Build and Load Docker Image for Spin App

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/images/spin-dapr/README.md

Builds a Docker image for the Spin application and loads it into the Kind cluster. This makes the application's container image available to the cluster.

```sh
# create an image and load it into Kind
docker build images/spin-dapr -t spin-dapr:latest --load
kind load docker-image spin-dapr:latest --name wasm-cluster
```

--------------------------------

### Configure containerd for Spin Runtime (older)

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/README.md

Add this configuration to your containerd `config.toml` for versions prior to containerd 2. It maps the 'spin' runtime type to the shim binary and enables SystemdCgroup.

```toml
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.spin]
  runtime_type = "io.containerd.spin.v2"
[plugins."io.containerd.grpc.v1.cri".containerd.runtimes.spin.options]
  SystemdCgroup = true

```

--------------------------------

### Smoke test the release with a Kind cluster

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/release.md

Optional: Smoke test the new release by creating a Kind cluster with the shim and deploying a test workload. Replace version numbers as needed.

```console
cat <<EOF | kind create cluster --name wasm-cluster --image ghcr.io/spinframework/containerd-shim-spin/kind:v0.24.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
kubectl apply -f https://github.com/spinframework/containerd-shim-spin/releases/download/v0.24.0/runtime.yaml
kubectl apply -f https://github.com/spinframework/containerd-shim-spin/releases/download/v0.24.0/workload.yaml
```

--------------------------------

### Build Spin Application

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/images/spin-dapr/README.md

Builds the Spin application located in the 'images/spin-dapr' directory. This step compiles the application into a WebAssembly binary.

```sh
# build the application
cd images/spin-dapr
spin build
cd -
```

--------------------------------

### Apply RuntimeClass for Spin Applications

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Applies the necessary Kubernetes RuntimeClass configuration to enable Spin applications to use the Spin WASM shim.

```bash
kubectl apply -f https://raw.githubusercontent.com/spinframework/containerd-shim-spin/main/deployments/workloads/runtime.yaml
```

--------------------------------

### Create and push a Git tag for release

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/release.md

Create a GPG-signed and annotated Git tag for the release, then push it to the remote repository. This action triggers the release workflow.

```sh
# Create a GPG-signed and annotated tag
git tag -s -m "Containerd Shim Spin v0.15.0" v0.15.0

# Push the tag to the remote corresponding to spinframework/containerd-shim-spin (here 'origin')
git push origin v0.15.0
```

--------------------------------

### Dockerfile for Spin Application

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

This Dockerfile builds a Spin application into a Wasm binary and prepares it for containerization.

```dockerfile
FROM --platform=${BUILDPLATFORM} rust:1.91 AS build
WORKDIR /opt/build
COPY . .
RUN rustup target add wasm32-wasip1 && cargo build --target wasm32-wasip1 --release

FROM scratch
COPY --from=build /opt/build/target/wasm32-wasip1/release/qs_wasm_spin.wasm .
COPY --from=build /opt/build/spin.toml .

```

--------------------------------

### Build Wasm Image

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/DockerSetup.md

Builds a WebAssembly image using Docker's buildx plugin, specifying the wasi/wasm platform. The --load flag is intended to load the image locally.

```shell
docker buildx build --platform=wasi/wasm --load -t wasmtest_spin:latest ./images/spin
```

--------------------------------

### Enable Containerd Snapshotter in Docker

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/DockerSetup.md

Configures Docker to use containerd for image storage by modifying the daemon.json file. Create the file if it does not exist.

```json
{
  "features": {
    "containerd-snapshotter": true
  }
}
```

--------------------------------

### Publish OCI WASM Image

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Publish the Spin application as an OCI WASM image using the 'spin registry push' command. Ensure you are using Spin 2.0 or later.

```bash
spin registry push ttl.sh/spin-quickstart/qs-wasm-spin:latest

```

--------------------------------

### Test Containerd Shim Spin

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/README.md

After running the shim, use this command in a separate terminal to test its functionality by sending a request to the default endpoint.

```bash
curl 0.0.0.0:80/hello
```

--------------------------------

### Update spin.toml for Wasm Source

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Modify the spin.toml file to specify the Wasm binary as the component source.

```toml
source = "qs_wasm_spin.wasm"

```

--------------------------------

### Kubernetes Deployment and Service Configuration

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Defines a Kubernetes Deployment, Service, and Ingress to run and expose the Spin application. The Deployment uses a custom runtimeClassName 'wasmtime-spin'.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: wasm-spin
spec:
  replicas: 3
  selector:
    matchLabels:
      app: wasm-spin
  template:
    metadata:
      labels:
        app: wasm-spin
    spec:
      runtimeClassName: wasmtime-spin
      containers:
        - name: testwasm
          image: ttl.sh/spin-quickstart/qs-wasm-spin:latest
          command: ["/"]
---
apiVersion: v1
kind: Service
metadata:
  name: wasm-spin
spec:
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
  selector:
    app: wasm-spin
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: wasm-spin
  annotations:
    ingress.kubernetes.io/ssl-redirect: "false"
spec:
  ingressClassName: traefik
  rules:
    - http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: wasm-spin
                port:
                  number: 80

```

--------------------------------

### Apply Kubernetes Manifests

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/images/spin-dapr/README.md

Applies the necessary Kubernetes manifests to deploy the Spin Dapr application and its runtime components to the cluster. This includes the Spin runtime and the application workload.

```sh
# Apply the manifest
kubectl apply -f https://github.com/spinframework/containerd-shim-spin/raw/main/deployments/workloads/runtime.yaml
kubectl apply -f images/spin-dapr/deploy.yaml
```

--------------------------------

### Initialize Dapr in Kubernetes

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/images/spin-dapr/README.md

Initializes Dapr in the Kind cluster with Kubernetes integration enabled. This command ensures Dapr components are correctly set up for the cluster.

```sh
# Install Dapr
dapr init -k --wait
```

--------------------------------

### Restart Containerd Service

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/conformance-tests/README.md

Restart the containerd service to apply the configuration changes.

```sh
systemctl restart containerd
```

--------------------------------

### Load Wasm Image to Kind Cluster

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/DockerSetup.md

Loads a Docker image into a Kind cluster. This command is used after saving the image to a tar file, as direct loading might not work for Wasm images.

```shell
kind load docker-image wasmtest_spin:latest --name wasm-cluster
```

--------------------------------

### Save Wasm Image to Tar

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/DockerSetup.md

Saves the built Wasm image to a tar archive. This is a workaround because the --load flag does not function correctly for the wasi/wasm platform.

```shell
docker save wasmtest_spin:latest -o wasmtest_spin.tar
```

--------------------------------

### Delete Sample Spin Application

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Removes the deployed sample Spin application from the Kubernetes cluster.

```bash
kubectl delete -f https://raw.githubusercontent.com/spinframework/containerd-shim-spin/main/deployments/workloads/workload.yaml
```

--------------------------------

### Update minor version using version.sh

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/release.md

Use the version.sh script to update the minor version number in manifests and documentation. Specify version updates with -m, -n, or -p flags.

```sh
scripts/version.sh -n
```

--------------------------------

### Access Spin Application Route

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Accesses a specific route of the locally running Spin application using curl.

```bash
$ curl http://127.0.0.1:3000/hi
Hello, Fermyon
```

--------------------------------

### Clean up Kubernetes Resources

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Remove the deployed Spin application resources from Kubernetes by deleting the applied YAML file.

```bash
kubectl delete -f qs.yaml

```

--------------------------------

### Port Forward and Test Spin Dapr App

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/images/spin-dapr/README.md

Forwards traffic to the Spin Dapr service and retrieves the last Kubernetes event. This is used to test the application's functionality after deployment.

```sh
# When everythin is up, forward the port and get the last kubernetes event
kubectl port-forward svc/spin-dapr 8080:80 &
curl localhost:8080 | jq
```

--------------------------------

### Delete Kind Cluster

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/containerd-shim-spin/quickstart.md

Delete the local Kubernetes cluster created with kind.

```bash
kind delete cluster --name wasm-cluster

```

--------------------------------

### Tear Down Kind Cluster

Source: https://github.com/spinframework/containerd-shim-spin/blob/main/deployments/kind/README.md

Removes the Kind cluster named 'wasm-cluster'.

```shell
kind delete cluster --name wasm-cluster
```
Tokens:
Raw