Documentation

• 1: Overview
• 2: Quickstart
• 3: spin-operator
• 3.1: Prerequisites
• 3.2: Quickstart
• 3.3: Installation
• 3.3.1: Installing with Helm
• 3.4: Tutorials
• 3.4.1: Assigning variables to Spin Apps
• 3.4.2: Deploy Spin Operator on Azure Kubernetes Service
• 3.4.3: Integrating With Docker Desktop
• 3.4.4: Integrating With Rancher Desktop
• 3.4.5: Package and Deploy Spin Apps
• 3.4.6: Scaling Spin App With Horizontal Pod Autoscaling (HPA)
• 3.4.7: Scaling Spin App With Kubernetes Event-Driven Autoscaling (KEDA)
• 3.4.8: Share Spin Operator Image
• 3.4.9: Spin Operator Development
• 3.4.10: Running locally
• 3.4.11: Running on a Cluster
• 3.4.12: Uninstall
• 3.5: Support
• 3.5.1: Feedback
• 3.5.2: Troubleshooting
• 3.6: Reference
• 3.6.1: SpinApp
• 3.6.2: SpinAppExecutor
• 3.7: Contributing
• 4: containerd-shim-spin
• 4.1: Concepts
• 4.2: Contributing
• 5: runtime-class-manager
• 5.1: Concepts
• 5.2: Contributing
• 6: spin-plugin-kube
• 6.1: Installation
• 6.2: Tutorials
• 6.2.1: Autoscaler Support
• 6.3: CLI Reference
• 6.4: Concepts
• 6.5: Contributing
• 7: Compatibility
• 8: Integrations
• 9: Contributing to Docs
• 10: Glossary of Terms

1 - Overview

Project Overview

SpinKube is a new open source project that streamlines the experience of developing, deploying, and operating Wasm workloads on Kubernetes, using Spin in tandem with the runwasi and KWasm open source projects.

With SpinKube, you can leverage the advantages of using WebAssembly (Wasm) for your workloads:

• Artifacts are significantly smaller in size compared to container images.
• Artifacts can be quickly fetched over the network and started much faster (*Note: We are aware of several optimizations that still need to be implemented to enhance the startup time for workloads).
• Substantially fewer resources are required during idle times.

All of this while being able to integrate with Kubernetes primitives (DNS, probes, autoscaling, metrics, and a lot more cloud native and CNCF projects) thanks to Spin Operator.

Spin Operator watches Spin App Custom Resources and realizes the desired state in the Kubernetes cluster. The foundation of this project was built using the kubebuilder framework and contains a Spin App Custom Resource Definition (CRD) and controller.

To get started, check out our Spin Operator quickstart.

2 - Quickstart

3 - spin-operator

What Is Spin Operator?

Spin Operator is a Kubernetes operator which empowers platform engineers to deploy Spin applications as custom resources to their Kubernetes clusters. Spin Operator provides an elegant solution for platform engineers looking to improve efficiency without compromising on performance while maintaining workload portability.

Why Spin Operator?

By bringing the power of the Spin framework to Kubernetes clusters, Spin Operator provides application developers and platform engineers with the best of both worlds. For developers, this means easily building portable serverless functions that leverage the power and performance of Wasm via the Spin developer tool. For platform engineers, this means using idiomatic Kubernetes primitives (secrets, autoscaling, etc.) and tooling to manage these workloads at scale in a production environment, improving their overall operational efficiency.

How Does Spin Operator Work?

Built with the kubebuilder framework, Spin Operator is a Kubernetes operator. Kubernetes operators are used to extend Kubernetes automation to new objects, defined as custom resources, without modifying the Kubernetes API. The Spin Operator is composed of two main components:

• A controller that defines and manages Wasm workloads on k8s.
• The “SpinApps” Custom Resource Definition (CRD).

SpinApps CRDs can be composed manually or generated automatically from an existing Spin application using the spin kube scaffold command. The former approach lends itself well to CI/CD systems, whereas the latter is a better fit for local testing as part of a local developer workflow.

Once an application deployment begins, Spin Operator handles scheduling the workload on the appropriate nodes (thanks to the Runtime Class Manager, previously known as Kwasm) and managing the resource’s lifecycle. There is no need to fetch the containerd shim spin binary or mutate node labels. This is all managed via the Runtime Class Manager, which you will install as a dependency when setting up Spin Operator.

Next Steps

For application developers interested in writing their first Spin App, check out the spin kube plugin documentation. By the end of the quickstart, you’ll have an application ready to deploy to your Kubernetes cluster of choice.

For platform engineers interested in cluster operations and working with Spin Operator, visit our Spin Operator quickstart. We provide you with a simple quickstart SpinApp to use alongside spin operator.

3.1 - Prerequisites

The following prerequisites are required.

Go

If building the Spin Operator from source or contributing to the development of Spin Operator then you will require Go version v1.22.0+ to be installed on your machine. Otherwise, please ignore this section, and move to the next prerequisite.

TinyGo

Please also install the latest version of TinyGo

Managing Containers and Kubernetes Locally

If you’d like to run Spin Operator locally, you have the option of using Rancher Desktop or Docker Desktop, as the interface for managing containers and Kubernetes clusters directly from your workstation.

Rancher Desktop

If you choose Rancher Desktop it is recommended to install version 1.13.0 or higher. Additionally, you will need to configure it to support WebAssembly applications.

Docker Desktop

If you choose Docker Desktop it is recommended to install version 17.03 or higher. Additionally, you will need to configure it to support WebAssembly applications.

Kubectl

If you’d like to manage your Spin applications with kubectl, then Spin Operator requires that you have kubectl version v1.27.0+ installed.

K3d

If running/deploying your Spin application involves the use of k3d, then the Spin Operator requires that you have k3d installed and that you have access to a Kubernetes v1.27.0 cluster.

containerd

If running/deploying your Spin application involves the use of k3s or a baremetal host, then the Spin Operator requires that you have containerD installed.

Helm

If running/deploying your Spin application involves the use of Helm, then the Spin Operator requires that you have Helm installed on your system.

Spin

Please install the latest version (2.3.1 or newer) of Spin on your local machine for creating Spin Apps.

Bombardier

Installing Bombardier is not required to use Spin Operator. Bombardier is used in tutorials like Scaling Spin App With Horizontal Pod Autoscaling to generate load to test autoscaling.

Azure CLI

Installing Azure CLI is not required to use Spin Operator. Azure CLI is used to provision Azure Kubernetes Service (AKS) and necessary Azure resources as part of the Deploy Spin Operator on Azure Kubernetes Service tutorial.

3.2 - Quickstart

This Quickstart guide demonstrates how to set up a new Kubernetes cluster, install the Spin Operator and deploy your first Spin application.

Prerequisites

Ensure necessary prerequisites are installed.

For this Quickstart in particular, you will need:

• kubectl - the Kubernetes CLI
• Rancher Desktop or Docker Desktop for managing containers and Kubernetes on your desktop
• k3d - a lightweight Kubernetes distribution that runs on Docker
• Helm - the package manager for Kubernetes

Set up Your Kubernetes Cluster

1. Create a Kubernetes cluster with a k3d image that includes the containerd-shim-spin prerequisite already installed:

k3d cluster create wasm-cluster \
  --image ghcr.io/spinkube/containerd-shim-spin/k3d:v0.14.1 \
  --port "8081:80@loadbalancer" \
  --agents 2

Note: Spin Operator requires a few Kubernetes resources that are installed globally to the cluster. We create these directly through kubectl as a best practice, since their lifetimes are usually managed separately from a given Spin Operator installation.

2. Install cert-manager

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml

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 K3d example, they’re installed on every node.

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

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

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

Deploy the Spin Operator

Execute the following command to install the Spin Operator on the K3d 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 install spin-operator \
  --namespace spin-operator \
  --create-namespace \
  --version 0.1.0 \
  --wait \
  oci://ghcr.io/spinkube/charts/spin-operator

Lastly, create the shim executor:

kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/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/spinkube/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)

3.3 - Installation

In this section you’ll learn how to install Spin Operator and run the operator either on your local machine or on a Kubernetes cluster.

3.3.1 - Installing with Helm

Prerequisites

Please ensure that your system has all of the prerequisites installed before continuing.

For this guide in particular, you will need:

• kubectl - the Kubernetes CLI
• Helm - the package manager for Kubernetes

Install Spin Operator With Helm

The following instructions are for installing Spin Operator using a Helm chart (using helm install).

Prepare the Cluster

Before installing the chart, you’ll need to ensure the following:

The Custom Resource Definition (CRD) resources are installed. This includes the SpinApp CRD representing Spin applications to be scheduled on the cluster.

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

A RuntimeClass resource class that points to the spin handler called wasmtime-spin-v2 will be created. If you are deploying to a production cluster that only has a shim on a subset of nodes, you’ll need to modify the RuntimeClass with a nodeSelector:.

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

The containerd-spin-shim SpinAppExecutor custom resource is installed. This tells Spin Operator to use the containerd shim executor to run Spin apps:

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

Chart prerequisites

• cert-manager to automatically provision and manage TLS certificates (used by spin-operator’s admission webhook system). For detailed installation instructions see the cert-manager documentation.

# Install cert-manager CRDs
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.crds.yaml

# Add and update Jetstack repository
helm repo add jetstack https://charts.jetstack.io
helm repo update

# Install the cert-manager Helm chart
helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.14.3

• Kwasm Operator is required to install WebAssembly support on Kubernetes nodes. Note in the future this will be replaced by runtime class manager.

# Add Helm repository if not already done
helm repo add kwasm http://kwasm.sh/kwasm-operator/

# Install 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.14.1

# Provision Nodes
kubectl annotate node --all kwasm.sh/kwasm-node=true

Installing the Spin Operator Chart

The following installs the chart with the release name spin-operator:

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

Upgrading the Chart

Note that you may also need to upgrade the spin-operator CRDs in tandem with upgrading the Helm release:

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

To upgrade the spin-operator release, run the following:

# Upgrade Spin Operator using Helm
helm upgrade spin-operator \
  --namespace spin-operator \
  --version 0.1.0 \
  --wait \
  oci://ghcr.io/spinkube/charts/spin-operator

Uninstalling the Chart

To delete the spin-operator release, run:

# Uninstall Spin Operator using Helm
helm delete spin-operator --namespace spin-operator

This will remove all Kubernetes resources associated with the chart and deletes the Helm release.

To completely uninstall all resources related to spin-operator, you may want to delete the corresponding CRD resources and, optionally, the RuntimeClass:

kubectl delete -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.crds.yaml
kubectl delete -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.runtime-class.yaml
kubectl delete -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.shim-executor.yaml

3.4 - Tutorials

3.4.1 - Assigning variables to Spin Apps

By using variables, you can alter application behavior without recompiling your SpinApp. When running in Kubernetes, you can either provide constant values for variables, or reference them from Kubernetes primitives such as ConfigMaps and Secrets. This tutorial guides your through the process of assigning variables to your SpinApp.

Prerequisites

Ensure necessary prerequisites are installed.

For this tutorial in particular, you should either have the Spin Operator running locally or running on your Kubernetes cluster.

Build and Store SpinApp in an OCI Registry

We’re going to build the SpinApp and store it inside of a ttl.sh registry. Move into the apps/variable-explorer directory and build the SpinApp we’ve provided:

# Build and publish the sample app
cd apps/variable-explorer
spin build
spin registry push ttl.sh/variable-explorer:1h

Note that the tag at the end of ttl.sh/variable-explorer:1h indicates how long the image will last e.g. 1h (1 hour). The maximum is 24h and you will need to repush if ttl exceeds 24 hours.

For demonstration purposes, we use the variable explorer sample app. It reads three different variables (log_level, platform_name and db_password) and prints their values to the STDOUT stream as shown in the following snippet:

let log_level = variables::get("log_level")?;
let platform_name = variables::get("platform_name")?;
let db_password = variables::get("db_password")?;

println!("# Log Level: {}", log_level);
println!("# Platform name: {}", platform_name);
println!("# DB Password: {}", db_password);

Those variables are defined as part of the Spin manifest (spin.toml), and access to them is granted to the variable-explorer component:

[variables]
log_level = { default = "WARN" }
platform_name = { default = "Fermyon Cloud" }
db_password = { required = true }

[component.variable-explorer.variables]
log_level = "{{ log_level }}"
platform_name = "{{ platform_name }}"
db_password = "{{ db_password }}"

Configuration data in Kubernetes

In Kubernetes, you use ConfigMaps for storing non-sensitive, and Secrets for storing sensitive configuration data. The deployment manifest (config/samples/variable-explorer.yaml) contains specifications for both a ConfigMap and a Secret:

kind: ConfigMap
apiVersion: v1
metadata:
  name: spinapp-cfg
data:
  logLevel: INFO
---
kind: Secret
apiVersion: v1
metadata:
  name: spinapp-secret
data:
  password: c2VjcmV0X3NhdWNlCg==

Assigning variables to a SpinApp

When creating a SpinApp, you can choose from different approaches for specifying variables:

1. Providing constant values
2. Loading configuration values from ConfigMaps
3. Loading configuration values from Secrets

The SpinApp specification contains the variables array, that you use for specifying variables (See kubectl explain spinapp.spec.variables).

The deployment manifest (config/samples/variable-explorer.yaml) specifies a static value for platform_name. The value of log_level is read from the ConfigMap called spinapp-cfg, and the db_password is read from the Secert called spinapp-secret:

kind: SpinApp
apiVersion: core.spinoperator.dev/v1alpha1
metadata:
  name: variable-explorer
spec:
  replicas: 1
  image: ttl.sh/variable-explorer:1h
  executor: containerd-shim-spin
  variables:
    - name: platform_name
      value: Kubernetes
    - name: log_level
      valueFrom:
        configMapKeyRef:
          name: spinapp-cfg
          key: logLevel
          optional: true
    - name: db_password
      valueFrom:
        secretKeyRef:
          name: spinapp-secret
          key: password
          optional: false

As the deployment manifest outlines, you can use the optional property - as you would do when specifying environment variables for a regular Kubernetes Pod - to control if Kubernetes should prevent starting the SpinApp, if the referenced configuration source does not exist.

You can deploy all resources by executing the following command:

kubectl apply -f config/samples/variable-explorer.yaml

configmap/spinapp-cfg created
secret/spinapp-secret created
spinapp.core.spinoperator.dev/variable-explorer created

Inspecting runtime logs of your SpinApp

To verify that all variables are passed correctly to the SpinApp, you can configure port forwarding from your local machine to the corresponding Kubernetes Service:

kubectl port-forward services/variable-explorer 8080:80

Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80

When port forwarding is established, you can send an HTTP request to the variable-explorer from within an additional terminal session:

curl http://localhost:8080
Hello from Kubernetes

Finally, you can use kubectl logs to see all logs produced by the variable-explorer at runtime:

kubectl logs -l core.spinoperator.dev/app-name=variable-explorer

# Log Level: INFO
# Platform Name: Kubernetes
# DB Password: secret_sauce

3.4.2 - Deploy Spin Operator on Azure Kubernetes Service

In this tutorial, you install Spin Operator on an Azure Kubernetes Service (AKS) cluster and deploy a simple Spin application. You will learn how to:

• Deploy an AKS cluster
• Install Spin Operator Custom Resource Definition and Runtime Class
• Install and verify containerd shim via Kwasm
• Deploy a simple Spin App custom resource on your cluster

Prerequisites

Please see the following sections in the Prerequisites page and fulfill those prerequisite requirements before continuing:

• kubectl - the Kubernetes CLI
• Helm - the package manager for Kubernetes
• Azure CLI - cross-platform CLI for managing Azure resources

Provisioning the necessary Azure Infrastructure

Before you dive into deploying Spin Operator on Azure Kubernetes Service (AKS), the underlying cloud infrastructure must be provisioned. For the sake of this article, you will provision a simple AKS cluster. (Alternatively, you can setup the AKS cluster following this guide from Microsoft.)

# Login with Azure CLI
az login

# Select the desired Azure Subscription
az account set --subscription <YOUR_SUBSCRIPTION>

# Create an Azure Resource Group
az group create --name rg-spin-operator \
    --location germanywestcentral

# Create an AKS cluster
az aks create --name aks-spin-operator \
    --resource-group rg-spin-operator \
    --location germanywestcentral \
    --node-count 1 \
    --tier free \
    --generate-ssh-keys

Once the AKS cluster has been provisioned, use the aks get-credentials command to download credentials for kubectl:

# Download credentials for kubectl
az aks get-credentials --name aks-spin-operator \
    --resource-group rg-spin-operator

For verification, you can use kubectl to browse common resources inside of the AKS cluster:

# Browse namespaces in the AKS cluster
kubectl get namespaces

NAME              STATUS   AGE
default           Active   3m
kube-node-lease   Active   3m
kube-public       Active   3m
kube-system       Active   3m

Deploying the Spin Operator

First, the Custom Resource Definition (CRD) and the Runtime Class for wasmtime-spin-v2 must be installed.

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

# Install the Runtime Class
kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.runtime-class.yaml

The following installs cert-manager which is required to automatically provision and manage TLS certificates (used by the admission webhook system of Spin Operator)

# Install cert-manager CRDs
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.crds.yaml

# Add and update Jetstack repository
helm repo add jetstack https://charts.jetstack.io
helm repo update

# Install the cert-manager Helm chart
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.14.3

The Spin Operator chart also has a dependency on Kwasm, which you use to install containerd-wasm-shim on the Kubernetes node(s):

# Add Helm repository if not already done
helm repo add kwasm http://kwasm.sh/kwasm-operator/
helm repo update

# Install 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.14.1

# Provision Nodes
kubectl annotate node --all kwasm.sh/kwasm-node=true

To verify containerd-wasm-shim installation, you can inspect the logs from the Kwasm Operator:

# Inspect logs from the Kwasm Operator
kubectl logs -n kwasm -l app.kubernetes.io/name=kwasm-operator

{"level":"info","node":"aks-nodepool1-31687461-vmss000000","time":"2024-02-12T11:23:43Z","message":"Trying to Deploy on aks-nodepool1-31687461-vmss000000"}
{"level":"info","time":"2024-02-12T11:23:43Z","message":"Job aks-nodepool1-31687461-vmss000000-provision-kwasm is still Ongoing"}
{"level":"info","time":"2024-02-12T11:24:00Z","message":"Job aks-nodepool1-31687461-vmss000000-provision-kwasm is Completed. Happy WASMing"}

The following installs the chart with the release name spin-operator in the spin-operator namespace:

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

Lastly, create the shim executor::

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

Deploying a Spin App to AKS

To validate the Spin Operator deployment, you will deploy a simple Spin App to the AKS cluster. The following command will install a simple Spin App using the SpinApp CRD you provisioned in the previous section:

# Deploy a sample Spin app
kubectl apply -f https://raw.githubusercontent.com/spinkube/spin-operator/main/config/samples/simple.yaml

Verifying the Spin App

Configure port forwarding from port 8080 of your local machine to port 80 of the Kubernetes service which points to the Spin App you installed in the previous section:

kubectl port-forward services/simple-spinapp 8080:80
Forwarding from 127.0.0.1:8080 -> 80
Forwarding from [::1]:8080 -> 80

Send a HTTP request to http://127.0.0.1:8080/hello using curl:

# Send an HTTP GET request to the Spin App
curl -iX GET http://localhost:8080/hello
HTTP/1.1 200 OK
transfer-encoding: chunked
date: Mon, 12 Feb 2024 12:23:52 GMT

Hello world from Spin!%

Removing the Azure infrastructure

To delete the Azure infrastructure created as part of this article, use the following command:

# Remove all Azure resources
az group delete --name rg-spin-operator \
    --no-wait \
    --yes

3.4.3 - Integrating With Docker Desktop

Docker Desktop is an open-source application that provides all the essentials to work with containers and Kubernetes on your desktop.

Prerequisites

The prerequisites for this tutorial are the Docker Desktop and assets listed in the SpinKube quickstart. Let’s dive in.

Docker Desktop

First, install the latest version of Docker Desktop.

Docker Desktop Preferences

WebAssembly (Wasm) support is still an in-development (Beta) feature of Docker Desktop. Wasm support is disabled by default. To turn it on, open your Docker Desktop settings menu and click the gear icon in the top right corner of the navigation bar. Click Extensions from the menu on the left and ensure that boxes relating to Docker Marketplace and Docker Extensions system containers are checked (as shown in the image below). Checking these boxes enables the “Features in development” extension.

Please ensure that you press “Apply & restart” to save any changes.

Click on Features in development from the menu on the left, and enable the following two options:

• “Use containerd for pulling and storing images”: This turns on containerd support, which is necessary for Wasm.
• “Enable Wasm”: This installs the Wasm subsystem, which includes containerd shims and Spin (among other things).

Make sure you press “Apply & restart” to save the changes.

Docker Desktop is Wasm-ready!

Click on “Kubernetes” and check the “Enable Kubernetes” box, as shown below.

Make sure you press “Apply & restart” to save the changes.

Select docker-desktop from the Kubernetes Contexts configuration in your toolbar.

SpinKube

The following commands are from the SpinKube Quickstart guide. Please refer to the quickstart if you have any queries.

The following commands install all of the necessary items that can be found in the quickstart:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
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

helm install spin-operator \
  --namespace spin-operator \
  --create-namespace \
  --version 0.1.0 \
  --wait \
  oci://ghcr.io/spinkube/charts/spin-operator
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.14.1

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

Creating Our Spin Application

Next, we create a new Spin app using the Javascript template:

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

We then edit the Javascript source file (the src/index.js file) to match the following:

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

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

spin build

Deploying Our Spin App to Docker

We publish our application using the spin registry command:

docker push tpmccallum/hello-docker

The command above will return output similar to the following:

Using default tag: latest
The push refers to repository [docker.io/tpmccallum/hello-docker]
latest: digest: sha256:f24bf4fae2dc7dd80cad25b3d3a6bceb566b257c03b7ff5b9dd9fe36b05f06e0 size: 695

Once published, we can read the configuration of our published application using the spin kube scaffold command:

spin kube scaffold -f tpmccallum/hello-docker

The above command will return something similar to the following YAML:

apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: hello-docker
spec:
  image: "tpmccallum/hello-docker"
  executor: containerd-shim-spin
  replicas: 2

We can run this using the following command:

spin kube deploy --from docker.io/tpmccallum/hello-docker

If we look at the “Images” section of Docker Desktop we see tpmccallum/hello-docker:

We can test the Wasm-powered Spin app that is running via Docker using the following request:

curl localhost:3000

Which returns the following:

Hello from Docker Desktop

3.4.4 - Integrating With Rancher Desktop

Rancher Desktop is an open-source application that provides all the essentials to work with containers and Kubernetes on your desktop.

Prerequisites

The prerequisites for this tutorial are Rancher Desktop and assets listed in the SpinKube quickstart. Let’s dive in.

Rancher Desktop

First, install the latest version of Rancher Desktop.

Rancher Desktop Preferences

Check the “Container Engine” section of your “Preferences” to ensure that containerd is your runtime and that “Wasm” is enabled. As shown below.

Also, select rancher-desktop from the Kubernetes Contexts configuration in your toolbar.

SpinKube

The following commands are from the SpinKube Quickstart guide. Please refer to the quickstart if you have any queries.

The following commands install all of the necessary items that can be found in the quickstart:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
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

helm install spin-operator \
  --namespace spin-operator \
  --create-namespace \
  --version 0.1.0 \
  --wait \
  oci://ghcr.io/spinkube/charts/spin-operator
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.14.1

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

Creating Our Spin Application

Next, we create a new Spin app using the Javascript template:

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

We then edit the Javascript source file (the src/index.js file) to match the following:

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

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

spin build

Deploying Our Spin App to Rancher Desktop with SpinKube

We publish our application using the spin registry command:

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

Once published, we can read the configuration of our published application using the spin kube scaffold command:

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

The above command will return something similar to the following YAML:

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

To test locally, we can make a request as follows:

curl localhost:8083

The above curl command will return the following:

Hello from Rancher Desktop

3.4.5 - Package and Deploy Spin Apps

This article explains how Spin Apps are packaged and distributed via both public and private registries. You will learn how to:

• Package and distribute Spin Apps
• Deploy Spin Apps
• Scaffold Kubernetes Manifests for Spin Apps
• Use private registries that require authentication

Prerequisites

Ensure the necessary prerequisites are installed.

For this tutorial in particular, you need

• Spin Operator running locally or running on your Kubernetes cluster
• TinyGo - for building the Spin app
• kubectl - the Kubernetes CLI
• spin - the Spin CLI
• spin kube - the Kubernetes plugin for spin

Creating a new Spin App

You use the spin CLI, to create a new Spin App. The spin CLI provides different templates, which you can use to quickly create different kinds of Spin Apps. For demonstration purposes, you will use the http-go template to create a simple Spin App.

# Create a new Spin App using the http-go template
spin new --accept-defaults -t http-go hello-spin

# Navigate into the hello-spin directory
cd hello-spin

The spin CLI created all necessary files within hello-spin. Besides the Spin Manifest (spin.toml), you can find the actual implementation of the app in main.go:

package main

import (
	"fmt"
	"net/http"

	spinhttp "github.com/fermyon/spin/sdk/go/v2/http"
)

func init() {
	spinhttp.Handle(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "text/plain")
		fmt.Fprintln(w, "Hello Fermyon!")
	})
}

func main() {}

This implementation will respond to any incoming HTTP request, and return an HTTP response with a status code of 200 (Ok) and send Hello Fermyon as the response body.

You can test the app on your local machine by invoking the spin up command from within the hello-spin folder.

Packaging and Distributing Spin Apps

Spin Apps are packaged and distributed as OCI artifacts. By leveraging OCI artifacts, Spin Apps can be distributed using any registry that implements the Open Container Initiative Distribution Specification (a.k.a. “OCI Distribution Spec”).

The spin CLI simplifies packaging and distribution of Spin Apps and provides an atomic command for this (spin registry push). You can package and distribute the hello-spin app that you created as part of the previous section like this:

# Package and Distribute the hello-spin app
spin registry push --build ttl.sh/hello-spin:24h

It is a good practice to add the --build flag to spin registry push. It prevents you from accidentally pushing an outdated version of your Spin App to your registry of choice.

Deploying Spin Apps

To deploy Spin Apps to a Kubernetes cluster which has Spin Operator running, you use the kube plugin for spin. Use the spin kube deploy command as shown here to deploy the hello-spin app to your Kubernetes cluster:

# Deploy the hello-spin app to your Kubernetes Cluster
spin kube deploy --from ttl.sh/hello-spin:24h

spinapp.core.spinoperator.dev/hello-spin created

Scaffolding Spin Apps

In the previous section, you deployed the hello-spin app using the spin kube deploy command. Although this is handy, you may want to inspect, or alter the Kubernetes manifests before applying them. You use the spin kube scaffold command to generate Kubernetes manifests:

spin kube scaffold --from ttl.sh/hello-spin:24h
apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: hello-spin
spec:
  image: "ttl.sh/hello-spin:24h"
  replicas: 2

By default, the command will print all Kubernetes menifests to STDOUT. Alternatively, you can specify the out argument to store the manifests to a file:

# Scaffold manifests to spinapp.yaml
spin kube scaffold --from ttl.sh/hello-spin:24h \
    --out spinapp.yaml

# Print contents of spinapp.yaml
cat spinapp.yaml
apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: hello-spin
spec:
  image: "ttl.sh/hello-spin:24h"
  replicas: 2

Distributing and Deploying Spin Apps via private registries

It is quite common to distribute Spin Apps through private registries that require some sort of authentication. To publish a Spin App to a private registry, you have to authenticate using the spin registry login command.

For demonstration purposes, you will now distribute the Spin App via GitHub Container Registry (GHCR). You can follow this guide by GitHub to create a new personal access token (PAT), which is required for authentication.

# Store PAT and GitHub username as environment variables
export GH_PAT=YOUR_TOKEN
export GH_USER=YOUR_GITHUB_USERNAME

# Authenticate spin CLI with GHCR
echo $GH_PAT | spin registry login ghcr.io -u $GH_USER --password-stdin

Successfully logged in as YOUR_GITHUB_USERNAME to registry ghcr.io

Once authentication succeeded, you can use spin registry push to push your Spin App to GHCR:

# Push hello-spin to GHCR
spin registry push --build ghcr.io/$GH_USER/hello-spin:0.0.1

Pushing app to the Registry...
Pushed with digest sha256:1611d51b296574f74b99df1391e2dc65f210e9ea695fbbce34d770ecfcfba581

In Kubernetes you store authentication information as secret of type docker-registry. The following snippet shows how to create such a secret with kubectl leveraging the environment variables, you specified in the previous section:

# Create Secret in Kubernetes
kubectl create secret docker-registry ghcr \
    --docker-server ghcr.io \
    --docker-username $GH_USER \
    --docker-password $CR_PAT

secret/ghcr created

Scaffold the necessary SpinApp Custom Resource (CR) using spin kube scaffold:

# Scaffold the SpinApp manifest
spin kube scaffold --from ghcr.io/$GH_USER/hello-spin:0.0.1 \
    --out spinapp.yaml

Before deploying the manifest with kubectl, update spinapp.yaml and link the ghcr secret you previously created using the imagePullSecrets property. Your SpinApp manifest should look like this:

apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: hello-spin
spec:
  image: ghcr.io/$GH_USER/hello-spin:0.0.1
  imagePullSecrets:
    - name: ghcr
  replicas: 2
  executor: containerd-shim-spin

$GH_USER should match the actual username provided while running through the previous sections of this article

Finally, you can deploy the app using kubectl apply:

# Deploy the spinapp.yaml using kubectl
kubectl apply -f spinapp.yaml
spinapp.core.spinoperator.dev/hello-spin created

3.4.6 - Scaling Spin App With Horizontal Pod Autoscaling (HPA)

Horizontal scaling, in the Kubernetes sense, means deploying more pods to meet demand (different from vertical scaling whereby more memory and CPU resources are assigned to already running pods). In this tutorial, we configure HPA to dynamically scale the instance count of our SpinApps to meet the demand.

Prerequisites

Please see the following sections in the Prerequisites page and fulfil those prerequisite requirements before continuing:

• Docker - for running k3d
• kubectl - the Kubernetes CLI
• k3d - a lightweight Kubernetes distribution that runs on Docker
• Helm - the package manager for Kubernetes
• Bombardier - cross-platform HTTP benchmarking CLI

We use k3d to run a Kubernetes cluster locally as part of this tutorial, but you can follow these steps to configure HPA autoscaling on your desired Kubernetes environment.

Setting Up Kubernetes Cluster

Run the following command to create a Kubernetes cluster that has the containerd-shim-spin pre-requisites installed: If you have a Kubernetes cluster already, please feel free to use it:

k3d cluster create wasm-cluster-scale \
  --image ghcr.io/spinkube/containerd-shim-spin/k3d:v0.14.1 \
  -p "8081:80@loadbalancer" \
  --agents 2

Deploying Spin Operator and its dependencies

First, you have to install cert-manager to automatically provision and manage TLS certificates (used by Spin Operator’s admission webhook system). For detailed installation instructions see the cert-manager documentation.

# Install cert-manager CRDs
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.crds.yaml

# Add and update Jetstack repository
helm repo add jetstack https://charts.jetstack.io
helm repo update

# Install the cert-manager Helm chart
helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.14.3

Next, run the following commands to install the Spin Runtime Class and Spin Operator Custom Resource Definitions (CRDs):

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 K3d example, they’re installed on every node.

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

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

Lastly, install Spin Operator using helm and the shim executor with the following commands:

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

# Install the shim executor
kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.shim-executor.yaml

Great, now you have Spin Operator up and running on your cluster. This means you’re set to create and deploy SpinApps later on in the tutorial.

Set Up Ingress

Use the following command to set up ingress on your Kubernetes cluster. This ensures traffic can reach your SpinApp once we’ve created it in future steps:

# Setup ingress following this tutorial https://k3d.io/v5.4.6/usage/exposing_services/
cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx
  annotations:
    ingress.kubernetes.io/ssl-redirect: "false"
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: hpa-spinapp
            port:
              number: 80
EOF

Hit enter to create the ingress resource.

Deploy Spin App and HorizontalPodAutoscaler (HPA)

Next up we’re going to deploy the Spin App we will be scaling. You can find the source code of the Spin App in the apps/cpu-load-gen folder of the Spin Operator repository.

We can take a look at the SpinApp and HPA definitions in our deployment file below/. As you can see, we have set our resources -> limits to 500m of cpu and 500Mi of memory per Spin application and we will scale the instance count when we’ve reached a 50% utilization in cpu and memory. We’ve also defined support a maximum replica count of 10 and a minimum replica count of 1:

apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: hpa-spinapp
spec:
  image: ghcr.io/spinkube/spin-operator/cpu-load-gen:20240311-163328-g1121986
  enableAutoscaling: true
  resources:
    limits:
      cpu: 500m
      memory: 500Mi
    requests:
      cpu: 100m
      memory: 400Mi
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: spinapp-autoscaler
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: hpa-spinapp
  minReplicas: 1
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50

For more information about HPA, please visit the following links:

• Kubernetes Horizontal Pod Autoscaling
• Kubernetes HorizontalPodAutoscaler Walkthrough
• HPA Container Resource Metrics

Below is an example of the configuration to scale resources:

apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: hpa-spinapp
spec:
  image: ghcr.io/spinkube/spin-operator/cpu-load-gen:20240311-163328-g1121986
  executor: containerd-shim-spin
  enableAutoscaling: true
  resources:
    limits:
      cpu: 500m
      memory: 500Mi
    requests:
      cpu: 100m
      memory: 400Mi
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: spinapp-autoscaler
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: hpa-spinapp
  minReplicas: 1
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50

Let’s deploy the SpinApp and the HPA instance onto our cluster (using the above .yaml configuration). To apply the above configuration we use the following kubectl apply command:

# Install SpinApp and HPA
kubectl apply -f https://raw.githubusercontent.com/spinkube/spin-operator/main/config/samples/hpa.yaml

You can see your running Spin application by running the following command:

kubectl get spinapps
NAME          AGE
hpa-spinapp   92m

You can also see your HPA instance with the following command:

kubectl get hpa
NAME                 REFERENCE                TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
spinapp-autoscaler   Deployment/hpa-spinapp   6%/50%    1         10        1          97m

Please note: The Kubernetes Plugin for Spin is a tool designed for Kubernetes integration with the Spin command-line interface. The Kubernetes Plugin for Spin has a scaling tutorial that demonstrates how to use the spin kube command to tell Kubernetes when to scale your Spin application up or down based on demand).

Generate Load to Test Autoscale

Now let’s use Bombardier to generate traffic to test how well HPA scales our SpinApp. The following Bombardier command will attempt to establish 40 connections during a period of 3 minutes (or less). If a request is not responded to within 5 seconds that request will timeout:

# Generate a bunch of load
bombardier -c 40 -t 5s -d 3m http://localhost:8081

To watch the load, we can run the following command to get the status of our deployment:

kubectl describe deploy hpa-spinapp
...
---

Available      True    MinimumReplicasAvailable
Progressing    True    NewReplicaSetAvailable
OldReplicaSets:  <none>
NewReplicaSet:   hpa-spinapp-544c649cf4 (1/1 replicas created)
Events:
  Type    Reason             Age    From                   Message
  ----    ------             ----   ----                   -------
  Normal  ScalingReplicaSet  11m    deployment-controller  Scaled up replica set hpa-spinapp-544c649cf4 to 1
  Normal  ScalingReplicaSet  9m45s  deployment-controller  Scaled up replica set hpa-spinapp-544c649cf4  to 4
  Normal  ScalingReplicaSet  9m30s  deployment-controller  Scaled up replica set hpa-spinapp-544c649cf4  to 8
  Normal  ScalingReplicaSet  9m15s  deployment-controller  Scaled up replica set hpa-spinapp-544c649cf4  to 10

3.4.7 - Scaling Spin App With Kubernetes Event-Driven Autoscaling (KEDA)

KEDA extends Kubernetes to provide event-driven scaling capabilities, allowing it to react to events from Kubernetes internal and external sources using KEDA scalers. KEDA provides a wide variety of scalers to define scaling behavior base on sources like CPU, Memory, Azure Event Hubs, Kafka, RabbitMQ, and more. We use a ScaledObject to dynamically scale the instance count of our SpinApp to meet the demand.

Prerequisites

Please see the following sections in the Prerequisites page and fulfil those prerequisite requirements before continuing:

• kubectl - the Kubernetes CLI
• Helm - the package manager for Kubernetes
• Docker - for running k3d
• k3d - a lightweight Kubernetes distribution that runs on Docker
• Bombardier - cross-platform HTTP benchmarking CLI

We use k3d to run a Kubernetes cluster locally as part of this tutorial, but you can follow these steps to configure KEDA autoscaling on your desired Kubernetes environment.

Setting Up Kubernetes Cluster

Run the following command to create a Kubernetes cluster that has the containerd-shim-spin pre-requisites installed: If you have a Kubernetes cluster already, please feel free to use it:

k3d cluster create wasm-cluster-scale \
  --image ghcr.io/spinkube/containerd-shim-spin/k3d:v0.14.1 \
  -p "8081:80@loadbalancer" \
  --agents 2

Deploying Spin Operator and its dependencies

First, you have to install cert-manager to automatically provision and manage TLS certificates (used by Spin Operator’s admission webhook system). For detailed installation instructions see the cert-manager documentation.

# Install cert-manager CRDs
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.crds.yaml

# Add and update Jetstack repository
helm repo add jetstack https://charts.jetstack.io
helm repo update

# Install the cert-manager Helm chart
helm install \
  cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.14.3

Next, run the following commands to install the Spin Runtime Class and Spin Operator Custom Resource Definitions (CRDs):

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 K3d example, they’re installed on every node.

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

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

Lastly, install Spin Operator using helm and the shim executor with the following commands:

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

# Install the shim executor
kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.shim-executor.yaml

Great, now you have Spin Operator up and running on your cluster. This means you’re set to create and deploy SpinApps later on in the tutorial.

Set Up Ingress

Use the following command to set up ingress on your Kubernetes cluster. This ensures traffic can reach your Spin App once we’ve created it in future steps:

# Setup ingress following this tutorial https://k3d.io/v5.4.6/usage/exposing_services/
cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nginx
  annotations:
    ingress.kubernetes.io/ssl-redirect: "false"
spec:
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: keda-spinapp
            port:
              number: 80
EOF

Hit enter to create the ingress resource.

Setting Up KEDA

Use the following command to setup KEDA on your Kubernetes cluster using Helm. Different deployment methods are described at Deploying KEDA on keda.sh:

# Add the Helm repository
helm repo add kedacore https://kedacore.github.io/charts

# Update your Helm repositories
helm repo update

# Install the keda Helm chart into the keda namespace
helm install keda kedacore/keda --namespace keda --create-namespace

Deploy Spin App and the KEDA ScaledObject

Next up we’re going to deploy the Spin App we will be scaling. You can find the source code of the Spin App in the apps/cpu-load-gen folder of the Spin Operator repository.

We can take a look at the SpinApp and the KEDA ScaledObject definitions in our deployment files below. As you can see, we have explicitly specified resource limits to 500m of cpu (spec.resources.limits.cpu) and 500Mi of memory (spec.resources.limits.memory) per SpinApp:

# https://raw.githubusercontent.com/spinkube/spin-operator/main/config/samples/keda-app.yaml
apiVersion: core.spinoperator.dev/v1alpha1
kind: SpinApp
metadata:
  name: keda-spinapp
spec:
  image: ghcr.io/spinkube/spin-operator/cpu-load-gen:20240311-163328-g1121986
  executor: containerd-shim-spin
  enableAutoscaling: true
  resources:
    limits:
      cpu: 500m
      memory: 500Mi
    requests:
      cpu: 100m
      memory: 400Mi
---

We will scale the instance count when we’ve reached a 50% utilization in cpu (spec.triggers[cpu].metadata.value). We’ve also instructed KEDA to scale our SpinApp horizontally within the range of 1 (spec.minReplicaCount) and 20 (spec.maxReplicaCount).:

# https://raw.githubusercontent.com/spinkube/spin-operator/main/config/samples/keda-scaledobject.yaml
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: cpu-scaling
spec:
  scaleTargetRef:
    name: keda-spinapp
  minReplicaCount: 1
  maxReplicaCount: 20
  triggers:
    - type: cpu
      metricType: Utilization
      metadata:
        value: "50"

The Kubernetes documentation is the place to learn more about limits and requests. Consult the KEDA documentation to learn more about ScaledObject and KEDA’s built-in scalers.

Let’s deploy the SpinApp and the KEDA ScaledObject instance onto our cluster with the following command:

# Deploy the SpinApp
kubectl apply -f config/samples/keda-app.yaml
spinapp.core.spinoperator.dev/keda-spinapp created

# Deploy the ScaledObject
kubectl apply -f config/samples/keda-scaledobject.yaml
scaledobject.keda.sh/cpu-scaling created

You can see your running Spin application by running the following command:

kubectl get spinapps

NAME          READY REPLICAS   EXECUTOR
keda-spinapp  1                containerd-shim-spin

You can also see your KEDA ScaledObject instance with the following command:

kubectl get scaledobject

NAME          SCALETARGETKIND      SCALETARGETNAME   MIN   MAX   TRIGGERS   READY   ACTIVE   AGE
cpu-scaling   apps/v1.Deployment   keda-spinapp      1     20    cpu        True    True     7m

Generate Load to Test Autoscale

Now let’s use Bombardier to generate traffic to test how well KEDA scales our SpinApp. The following Bombardier command will attempt to establish 40 connections during a period of 3 minutes (or less). If a request is not responded to within 5 seconds that request will timeout:

# Generate a bunch of load
bombardier -c 40 -t 5s -d 3m http://localhost:8081

To watch the load, we can run the following command to get the status of our deployment:

kubectl describe deploy keda-spinapp
...
---

Available      True    MinimumReplicasAvailable
Progressing    True    NewReplicaSetAvailable
OldReplicaSets:  <none>
NewReplicaSet:   keda-spinapp-76db5d7f9f (1/1 replicas created)
Events:
  Type    Reason             Age   From                   Message
  ----    ------             ----  ----                   -------
  Normal  ScalingReplicaSet  84s   deployment-controller  Scaled up replica set hpa-spinapp-76db5d7f9f  to 2 from 1
  Normal  ScalingReplicaSet  69s   deployment-controller  Scaled up replica set hpa-spinapp-76db5d7f9f  to 4 from 2
  Normal  ScalingReplicaSet  54s   deployment-controller  Scaled up replica set hpa-spinapp-76db5d7f9f  to 8 from 4
  Normal  ScalingReplicaSet  39s   deployment-controller  Scaled up replica set hpa-spinapp-76db5d7f9f  to 16 from 8
  Normal  ScalingReplicaSet  24s   deployment-controller  Scaled up replica set hpa-spinapp-76db5d7f9f  to 20 from 16

3.4.8 - Share Spin Operator Image

You can build and push the Spin Operator image using the docker-build and docker-push targets specified in the Makefile.

• The docker-build task invokes local docker tooling and builds a Docker image matching your local system architecture.
• The docker-push task invokes local docker tooling and pushes the Docker image to a container registry.

You can chain both targets using make docker-build docker-push to perform build and push at once.

Ensure to provide the fully qualified image name as IMG argument to push your custom Spin Operator image to the desired container registry:

# Build & Push the Spin Operator Image
make docker-build docker-push IMG=<some-registry>/spin-operator:tag

This image ought to be published in the personal registry you specified. And it is required to have access to pull the image from the working environment. Make sure you have the proper permission to the registry if the above command doesn’t work.

Build and Push multi-arch Images

There are scenarios where you may want to build and push the Spin Operator image for multiple architectures. This is done by using the underlying Buildx capabilitites provided by Docker.

You use the docker-build-and-publish-all target specified in the Makefile to build and push the Spin Operator image for multiple architectures at once:

# Build & Push the Spin Operator Image for arm64 and amd64
make docker-build-and-publish-all

Optionally, you can specify desired architectures by providing the PLATFORMS argument as shown here:

# Build & Push the Spin Operator Image form desired architectures explicitly
make docker-build-and-publish-all PLATFORMS=linux/arm64,linux/amd64

3.4.9 - Spin Operator Development

To Deploy on the Cluster

Build and push your image to the location specified by IMG:

make docker-build docker-push IMG=<some-registry>/spin-operator:tag

NOTE: This image ought to be published in the personal registry you specified. And it is required to have access to pull the image from the working environment. Make sure you have the proper permission to the registry if the above commands don’t work.

Apply the Runtime Class to the cluster:

kubectl apply -f config/samples/spin-runtime-class.yaml

Install the CRDs into the cluster:

make install

Deploy cert-manager to the cluster:

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml

NOTE: Cert-manager is required to manage the TLS certificates for the admission webhooks.

Deploy the Manager to the cluster with the image specified by IMG:

make deploy IMG=<some-registry>/spin-operator:tag

NOTE: If you encounter RBAC errors, you may need to grant yourself cluster-admin privileges or be logged in as admin.

Create instances of your solution You can apply the samples (examples) from the config/sample:

kubectl apply -k config/samples/

NOTE: Ensure that the samples has default values to test it out.

To Uninstall

Delete the instances (CRs) from the cluster:

kubectl delete -k config/samples/

Delete the APIs(CRDs) from the cluster:

make uninstall

Delete the Runtime Class from the cluster:

kubectl delete -f config/samples/spin-runtime-class.yaml

UnDeploy the controller from the cluster:

make undeploy

UnDeploy cert-manager from the cluster:

kubectl delete -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml

Packaging and deployment via Helm

The Spin Operator chart is assembled via a combination of helmify using the kustomize manifests from the config directory as well as other non-kustomize items such as the NOTES.txt and Chart.yaml.

NOTE: Manual changes to helmify-generated resources, including the values.yml file and applicable resources in templates are not persisted across helmify invocations.

Generate the Helm chart:

make helm-generate

Install the Helm chart onto the cluster:

Note: CRDs and the wasm-spin-v2 RuntimeClass are currently not installed as part of the chart. You’ll need to ensure these are present via the method(s) mentioned above.

make helm-install

Follow the release notes printed after helm installs the chart for next steps.

Upgrade the Helm release on the cluster:

make helm-upgrade

Delete the Helm release from the cluster:

make helm-uninstall

3.4.10 - Running locally

Prerequisites

Please ensure that your system has all the prerequisites installed before continuing.

Fetch Spin Operator (Source Code)

Clone the Spin Operator repository:

git clone https://github.com/spinkube/spin-operator.git

Change into the Spin Operator directory:

cd spin-operator

Setting Up Kubernetes Cluster

Run the following command to create a Kubernetes k3d cluster that has the containerd-shim-spin pre-requisites installed:

k3d cluster create wasm-cluster --image ghcr.io/spinkube/containerd-shim-spin/k3d:v0.14.1 -p "8081:80@loadbalancer" --agents 2

Run the following command to install the Custom Resource Definitions (CRDs) into the cluster:

make install

Running spin-operator

Run the following command to run the Spin Operator locally:

make run

In a fresh terminal, run the following command to create a Runtime Class named wasmtime-spin-v2:

kubectl apply -f - <<EOF
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: wasmtime-spin-v2
handler: spin
EOF

A SpinAppExecutor is a custom resource that defines how an application should be executed. The SpinAppExecutor provides ways for the user to configure how the application should run, like which runtime class to use.

SpinAppExecutors can be defined at the namespace level, allowing multiple SpinAppExecutors to refer to different runtime classes in the same namespace. This means that a SpinAppExecutor must exist in every namespace where a SpinApp is to be executed.

Run the following command to create a SpinAppExecutor using the same runtime class as the one created above:

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

Running the Sample Application

Run the following command, in a different terminal window:

kubectl apply -f ./config/samples/simple.yaml

Run the following command to obtain the name of the pod you have running:

kubectl get pods

The above command will return information similar to the following:

NAME                              READY   STATUS    RESTARTS   AGE
simple-spinapp-5b8d8d69b4-snscs   1/1     Running   0          3m40s

Using the NAME from above, run the following kubectl command to listen on port 8083 locally and forward to port 80 in the pod:

kubectl port-forward simple-spinapp-5b8d8d69b4-snscs 8083:80

The above command will return the following forwarding mappings:

Forwarding from 127.0.0.1:8083 -> 80
Forwarding from [::1]:8083 -> 80

In a fresh terminal, run the following command:

curl localhost:8083/hello

The above command will return the following message:

Hello world from Spin!

3.4.11 - Running on a Cluster

Prerequisites

Please ensure that your system has all the prerequisites installed before continuing.

Running on Your Kubernetes Cluster

This is the standard development workflow for when you want to test running Spin Operator on a Kubernetes cluster. This is harder than running Spin Operator on your local machine, but deploying Spin Operator into your cluster lets you test things like webhooks.

Note that you need to install cert-manager for webhook support.

To install cert-manager with the default config

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml

Deploy the Manager to the cluster with the image specified by IMG:

make deploy IMG=<some-registry>/spin-operator:tag

NOTE: If you encounter RBAC errors, you may need to grant yourself cluster-admin privileges or be logged in as admin.

To create instances of your solution, apply the samples (examples) from the config/sample:

kubectl apply -k config/samples/

NOTE: Ensure that the samples has default values to test it out.

3.4.12 - Uninstall

These are commands to delete, uninstall and undeploy resources.

Delete (CRs)

The following command will delete the instances (CRs) from the cluster:

kubectl delete -k config/samples/

Delete APIs(CRDs)

The following command will uninstall CRDs from the Kubernetes cluster specified in ~/.kube/config:

make uninstall

Call with ignore-not-found=true to ignore resource not found errors during deletion.

UnDeploy

The following command will undeploy the controller from the Kubernetes cluster specified in ~/.kube/config:

make undeploy

Call with ignore-not-found=true to ignore resource not found errors during deletion.

3.5 - Support

3.5.1 - Feedback

The following is a list of suggestions that might assist you with providing feedback to the Spin Operator project.

Discord

For questions or support, please visit the Spin Operator Discord channel.

Feature requests and bug reports

If you would like to file a feature or a bug report request, please open a new issue.

Documentation

If you would like to provide feedback on the documentation please open a new issue.

3.5.2 - Troubleshooting

The following is a list of common error messages and potential troubleshooting suggestions that might assist you with your work.

No endpoints available for service “spin-operator-webhook-service”

When following the quickstart guide the following error can occur when running the kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.shim-executor.yaml command:

Error from server (InternalError): error when creating "https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.shim-executor.yaml": Internal error occurred: failed calling webhook "mspinappexecutor.kb.io": failed to call webhook: Post "https://spin-operator-webhook-service.spin-operator.svc:443/mutate-core-spinoperator-dev-v1alpha1-spinappexecutor?timeout=10s": no endpoints available for service "spin-operator-webhook-service"

To address the error above, first look to see if Spin Operator is running:

get pods -n spin-operator
NAME                                                READY   STATUS              RESTARTS   AGE
spin-operator-controller-manager-5bdcdf577f-htshb   0/2     ContainerCreating   0          26m

If the above result (ready 0/2) is returned, then use the name from the above result to kubectl describe pod of the spin-operator:

kubectl describe pod spin-operator-controller-manager-5bdcdf577f-htshb -n spin-operator

If the above command’s response includes the message SetUp failed for volume "cert" : secret "webhook-server-cert" not found, please check the certificate. The spin operator requires this certificate to serve webhooks, and the missing certificate could be one reason why the spin operator is failing to start.

The command to check the certificate and the desired output is as follows:

kubectl get certificate -n spin-operator
NAME                         READY   SECRET                AGE
spin-operator-serving-cert   True    webhook-server-cert   11m

Instead of the desired output shown above you may be getting the No resources found in spin-operator namespace. response from the command. For example:

kubectl get certificate -n spin-operator
No resources found in spin-operator namespace.

To resolve this issue, please try to install the Spin Operator again. Except this time, use the helm upgrade --install syntax instead of just helm install:

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

Once the Spin Operator is installed you can try and run the kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.1.0/spin-operator.shim-executor.yaml command again. The issue should be resolved now.

Error Validating Data: Connection Refused

When trying to run the kubectl apply -f <URL> command (for example installing the cert-manager etc.) you may encounter an error similar to the following:

$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml

error: error validating "https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml": error validating data: failed to download openapi: Get "https://127.0.0.1:6443/openapi/v2?timeout=32s": dial tcp 127.0.0.1:6443: connect: connection refused; if you choose to ignore these errors, turn validation off with --validate=false

This is because no cluster exists. You can create a cluster using the k3d command or install and configure a client like Rancher Desktop or Docker Desktop to manage Kubernetes clusters on your behalf.

Installation Failed

When trying to install a new version of a chart you may get the following error:

Error: INSTALLATION FAILED: cannot re-use a name that is still in use

For example, if you have installed v0.14.0 of kwasm-operator using the following helm install command:

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

Reissuing the above command with the new version v0.14.1 will result in the following error - Error: INSTALLATION FAILED: cannot re-use a name that is still in use. To use the same command when installing and upgrading a release, use upgrade --install (as referenced here in the official Helm documentation). For example:

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

Cluster Already Exists

When trying to create a cluster (e.g. a cluster named wasm-cluster) you may receive an error message similar to the following:

FATA[0000] Failed to create cluster 'wasm-cluster' because a cluster with that name already exists

Cluster Information

With k3d installed, you can use the following command to get a cluster list:

$ k3d cluster list
NAME           SERVERS   AGENTS   LOADBALANCER
wasm-cluster   1/1       2/2      true

With `kubectl installed, you can use the following command to dump cluster information (this is much more verbose):

kubectl cluster-info dump

Cluster Delete

With k3d installed, you can delete the cluster by name, as shown in the command below:

$ k3d cluster delete wasm-cluster
INFO[0000] Deleting cluster 'wasm-cluster'
INFO[0002] Deleting cluster network 'k3d-wasm-cluster'
INFO[0002] Deleting 1 attached volumes...
INFO[0002] Removing cluster details from default kubeconfig...
INFO[0002] Removing standalone kubeconfig file (if there is one)...
INFO[0002] Successfully deleted cluster wasm-cluster!

Too long: must have at most 262144 bytes

When running kubectl apply -f my-file.yaml, the following error can occur if the yaml file is too large:

Too long: must have at most 262144 bytes

Using the --server-side=true option resolves this issue:

kubectl apply --server-side=true -f my-file.yaml

Redis Operator

Noted an error when installing Redis Operator:

$ helm repo add redis-operator https://spotahome.github.io/redis-operator
"redis-operator" has been added to your repositories
$ helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "redis-operator" chart repository
Update Complete. ⎈Happy Helming!⎈
$ helm install redis-operator redis-operator/redis-operator
Error: INSTALLATION FAILED: failed to install CRD crds/databases.spotahome.com_redisfailovers.yaml: error parsing : error converting YAML to JSON: yaml: line 4: did not find expected node content

Used the following commands to enforce using a different version of Redis Operator (whilst waiting on this PR fix to be merged).

$ helm install redis-operator redis-operator/redis-operator --version 3.2.9
NAME: redis-operator
LAST DEPLOYED: Mon Jan 22 12:33:54 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

error: requires go version

When building apps like the cpu-load-gen Spin app, you may get the following error if your TinyGo is not up to date. The error requires go version 1.18 through 1.20 but this is not necessarily the case. It is recommended that you have the latest go installed e.g. 1.21 and downgrading is unnecessary. Instead please go ahead and install the latest version of TinyGo to resolve this error:

user@user:~/spin-operator/apps/cpu-load-gen$ spin build
Building component cpu-load-gen with `tinygo build -target=wasi -gc=leaking -no-debug -o main.wasm main.go`
error: requires go version 1.18 through 1.20, got go1.21

3.6 - Reference

3.6.1 - SpinApp

Resource Types:

• SpinApp

SpinApp

SpinApp is the Schema for the spinapps API

SpinApp.spec

back to parent

SpinAppSpec defines the desired state of SpinApp

SpinApp.spec.checks

back to parent

Checks defines health checks that should be used by Kubernetes to monitor the application.

SpinApp.spec.checks.liveness

back to parent

Liveness defines the liveness probe for the application.

SpinApp.spec.checks.liveness.httpGet

back to parent

HTTPGet describes a health check that should be performed using a GET request.

SpinApp.spec.checks.liveness.httpGet.httpHeaders[index]

back to parent

HTTPHealthProbeHeader is an abstraction around a http header key/value pair.

SpinApp.spec.checks.readiness

back to parent

Readiness defines the readiness probe for the application.

SpinApp.spec.checks.readiness.httpGet

back to parent

HTTPGet describes a health check that should be performed using a GET request.

SpinApp.spec.checks.readiness.httpGet.httpHeaders[index]

back to parent

HTTPHealthProbeHeader is an abstraction around a http header key/value pair.

SpinApp.spec.imagePullSecrets[index]

back to parent

LocalObjectReference contains enough information to let you locate the referenced object inside the same namespace.

SpinApp.spec.resources

back to parent

Resources defines the resource requirements for this app.

SpinApp.spec.runtimeConfig

back to parent

RuntimeConfig defines configuration to be applied at runtime for this app.

SpinApp.spec.runtimeConfig.keyValueStores[index]

back to parent

SpinApp.spec.runtimeConfig.keyValueStores[index].options[index]

back to parent

SpinApp.spec.runtimeConfig.keyValueStores[index].options[index].valueFrom

back to parent

ValueFrom is a reference to dynamically bind the variable to.

SpinApp.spec.runtimeConfig.keyValueStores[index].options[index].valueFrom.configMapKeyRef

back to parent

Selects a key of a ConfigMap.

SpinApp.spec.runtimeConfig.keyValueStores[index].options[index].valueFrom.secretKeyRef

back to parent

Selects a key of a secret in the apps namespace

SpinApp.spec.runtimeConfig.llmCompute

back to parent

SpinApp.spec.runtimeConfig.llmCompute.options[index]

back to parent

SpinApp.spec.runtimeConfig.llmCompute.options[index].valueFrom

back to parent

ValueFrom is a reference to dynamically bind the variable to.

SpinApp.spec.runtimeConfig.llmCompute.options[index].valueFrom.configMapKeyRef

back to parent

Selects a key of a ConfigMap.

SpinApp.spec.runtimeConfig.llmCompute.options[index].valueFrom.secretKeyRef

back to parent

Selects a key of a secret in the apps namespace

SpinApp.spec.runtimeConfig.sqliteDatabases[index]

back to parent

SpinApp.spec.runtimeConfig.sqliteDatabases[index].options[index]

back to parent

SpinApp.spec.runtimeConfig.sqliteDatabases[index].options[index].valueFrom

back to parent

ValueFrom is a reference to dynamically bind the variable to.

SpinApp.spec.runtimeConfig.sqliteDatabases[index].options[index].valueFrom.configMapKeyRef

back to parent

Selects a key of a ConfigMap.

SpinApp.spec.runtimeConfig.sqliteDatabases[index].options[index].valueFrom.secretKeyRef

back to parent

Selects a key of a secret in the apps namespace

SpinApp.spec.variables[index]

back to parent

SpinVar defines a binding between a spin variable and a static or dynamic value.

SpinApp.spec.variables[index].valueFrom

back to parent

ValueFrom is a reference to dynamically bind the variable to.

SpinApp.spec.variables[index].valueFrom.configMapKeyRef

back to parent

Selects a key of a ConfigMap.

SpinApp.spec.variables[index].valueFrom.fieldRef

back to parent

Selects a field of the pod: supports metadata.name, metadata.namespace, metadata.labels['<KEY>'], metadata.annotations['<KEY>'], spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs.

SpinApp.spec.variables[index].valueFrom.resourceFieldRef

back to parent

Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, limits.ephemeral-storage, requests.cpu, requests.memory and requests.ephemeral-storage) are currently supported.

SpinApp.spec.variables[index].valueFrom.secretKeyRef

back to parent

Selects a key of a secret in the pod’s namespace

SpinApp.spec.volumeMounts[index]

back to parent

VolumeMount describes a mounting of a Volume within a container.

SpinApp.spec.volumes[index]

back to parent

Volume represents a named volume in a pod that may be accessed by any container in the pod.

SpinApp.spec.volumes[index].awsElasticBlockStore

back to parent

awsElasticBlockStore represents an AWS Disk resource that is attached to a kubelet’s host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#awselasticblockstore

SpinApp.spec.volumes[index].azureDisk

back to parent

azureDisk represents an Azure Data Disk mount on the host and bind mount to the pod.

SpinApp.spec.volumes[index].azureFile

back to parent

azureFile represents an Azure File Service mount on the host and bind mount to the pod.

SpinApp.spec.volumes[index].cephfs

back to parent

cephFS represents a Ceph FS mount on the host that shares a pod’s lifetime

SpinApp.spec.volumes[index].cephfs.secretRef

back to parent

secretRef is Optional: SecretRef is reference to the authentication secret for User, default is empty. More info: https://examples.k8s.io/volumes/cephfs/README.md#how-to-use-it

SpinApp.spec.volumes[index].cinder

back to parent

cinder represents a cinder volume attached and mounted on kubelets host machine. More info: https://examples.k8s.io/mysql-cinder-pd/README.md

SpinApp.spec.volumes[index].cinder.secretRef

back to parent

secretRef is optional: points to a secret object containing parameters used to connect to OpenStack.

SpinApp.spec.volumes[index].configMap

back to parent

configMap represents a configMap that should populate this volume

SpinApp.spec.volumes[index].configMap.items[index]

back to parent

Maps a string key to a path within a volume.

SpinApp.spec.volumes[index].csi

back to parent

csi (Container Storage Interface) represents ephemeral storage that is handled by certain external CSI drivers (Beta feature).

SpinApp.spec.volumes[index].csi.nodePublishSecretRef

back to parent

nodePublishSecretRef is a reference to the secret object containing sensitive information to pass to the CSI driver to complete the CSI NodePublishVolume and NodeUnpublishVolume calls. This field is optional, and may be empty if no secret is required. If the secret object contains more than one secret, all secret references are passed.

SpinApp.spec.volumes[index].downwardAPI

back to parent

downwardAPI represents downward API about the pod that should populate this volume

SpinApp.spec.volumes[index].downwardAPI.items[index]

back to parent

DownwardAPIVolumeFile represents information to create the file containing the pod field

SpinApp.spec.volumes[index].downwardAPI.items[index].fieldRef

back to parent

Required: Selects a field of the pod: only annotations, labels, name and namespace are supported.

SpinApp.spec.volumes[index].downwardAPI.items[index].resourceFieldRef

back to parent

Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported.

SpinApp.spec.volumes[index].emptyDir

back to parent

emptyDir represents a temporary directory that shares a pod’s lifetime. More info: https://kubernetes.io/docs/concepts/storage/volumes#emptydir

SpinApp.spec.volumes[index].ephemeral

back to parent

ephemeral represents a volume that is handled by a cluster storage driver. The volume’s lifecycle is tied to the pod that defines it - it will be created before the pod starts, and deleted when the pod is removed.

Use this if: a) the volume is only needed while the pod runs, b) features of normal volumes like restoring from snapshot or capacity tracking are needed, c) the storage driver is specified through a storage class, and d) the storage driver supports dynamic volume provisioning through a PersistentVolumeClaim (see EphemeralVolumeSource for more information on the connection between this volume type and PersistentVolumeClaim).

Use PersistentVolumeClaim or one of the vendor-specific APIs for volumes that persist for longer than the lifecycle of an individual pod.

Use CSI for light-weight local ephemeral volumes if the CSI driver is meant to be used that way - see the documentation of the driver for more information.

A pod can use both types of ephemeral volumes and persistent volumes at the same time.

SpinApp.spec.volumes[index].ephemeral.volumeClaimTemplate

back to parent

Will be used to create a stand-alone PVC to provision the volume. The pod in which this EphemeralVolumeSource is embedded will be the owner of the PVC, i.e. the PVC will be deleted together with the pod. The name of the PVC will be <pod name>-<volume name> where <volume name> is the name from the PodSpec.Volumes array entry. Pod validation will reject the pod if the concatenated name is not valid for a PVC (for example, too long).

An existing PVC with that name that is not owned by the pod will not be used for the pod to avoid using an unrelated volume by mistake. Starting the pod is then blocked until the unrelated PVC is removed. If such a pre-created PVC is meant to be used by the pod, the PVC has to updated with an owner reference to the pod once the pod exists. Normally this should not be necessary, but it may be useful when manually reconstructing a broken cluster.

This field is read-only and no changes will be made by Kubernetes to the PVC after it has been created.

Required, must not be nil.

SpinApp.spec.volumes[index].ephemeral.volumeClaimTemplate.spec

back to parent

The specification for the PersistentVolumeClaim. The entire content is copied unchanged into the PVC that gets created from this template. The same fields as in a PersistentVolumeClaim are also valid here.

SpinApp.spec.volumes[index].ephemeral.volumeClaimTemplate.spec.dataSource

back to parent

dataSource field can be used to specify either:

• An existing VolumeSnapshot object (snapshot.storage.k8s.io/VolumeSnapshot)
• An existing PVC (PersistentVolumeClaim) If the provisioner or an external controller can support the specified data source, it will create a new volume based on the contents of the specified data source. When the AnyVolumeDataSource feature gate is enabled, dataSource contents will be copied to dataSourceRef, and dataSourceRef contents will be copied to dataSource when dataSourceRef.namespace is not specified. If the namespace is specified, then dataSourceRef will not be copied to dataSource.

SpinApp.spec.volumes[index].ephemeral.volumeClaimTemplate.spec.dataSourceRef

back to parent

dataSourceRef specifies the object from which to populate the volume with data, if a non-empty volume is desired. This may be any object from a non-empty API group (non core object) or a PersistentVolumeClaim object. When this field is specified, volume binding will only succeed if the type of the specified object matches some installed volume populator or dynamic provisioner. This field will replace the functionality of the dataSource field and as such if both fields are non-empty, they must have the same value. For backwards compatibility, when namespace isn’t specified in dataSourceRef, both fields (dataSource and dataSourceRef) will be set to the same value automatically if one of them is empty and the other is non-empty. When namespace is specified in dataSourceRef, dataSource isn’t set to the same value and must be empty. There are three important differences between dataSource and dataSourceRef:

• While dataSource only allows two specific types of objects, dataSourceRef allows any non-core object, as well as PersistentVolumeClaim objects.
• While dataSource ignores disallowed values (dropping them), dataSourceRef preserves all values, and generates an error if a disallowed value is specified.
• While dataSource only allows local objects, dataSourceRef allows objects in any namespaces. (Beta) Using this field requires the AnyVolumeDataSource feature gate to be enabled. (Alpha) Using the namespace field of dataSourceRef requires the CrossNamespaceVolumeDataSource feature gate to be enabled.

SpinApp.spec.volumes[index].ephemeral.volumeClaimTemplate.spec.resources

back to parent

resources represents the minimum resources the volume should have. If RecoverVolumeExpansionFailure feature is enabled users are allowed to specify resource requirements that are lower than previous value but must still be higher than capacity recorded in the status field of the claim. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#resources

SpinApp.spec.volumes[index].ephemeral.volumeClaimTemplate.spec.selector

back to parent

selector is a label query over volumes to consider for binding.

SpinApp.spec.volumes[index].ephemeral.volumeClaimTemplate.spec.selector.matchExpressions[index]

back to parent

A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.

SpinApp.spec.volumes[index].fc

back to parent

fc represents a Fibre Channel resource that is attached to a kubelet’s host machine and then exposed to the pod.

SpinApp.spec.volumes[index].flexVolume

back to parent

flexVolume represents a generic volume resource that is provisioned/attached using an exec based plugin.

SpinApp.spec.volumes[index].flexVolume.secretRef

back to parent

secretRef is Optional: secretRef is reference to the secret object containing sensitive information to pass to the plugin scripts. This may be empty if no secret object is specified. If the secret object contains more than one secret, all secrets are passed to the plugin scripts.

SpinApp.spec.volumes[index].flocker

back to parent

flocker represents a Flocker volume attached to a kubelet’s host machine. This depends on the Flocker control service being running

SpinApp.spec.volumes[index].gcePersistentDisk

back to parent

gcePersistentDisk represents a GCE Disk resource that is attached to a kubelet’s host machine and then exposed to the pod. More info: https://kubernetes.io/docs/concepts/storage/volumes#gcepersistentdisk

SpinApp.spec.volumes[index].gitRepo

back to parent

gitRepo represents a git repository at a particular revision. DEPRECATED: GitRepo is deprecated. To provision a container with a git repo, mount an EmptyDir into an InitContainer that clones the repo using git, then mount the EmptyDir into the Pod’s container.

SpinApp.spec.volumes[index].glusterfs

back to parent

glusterfs represents a Glusterfs mount on the host that shares a pod’s lifetime. More info: https://examples.k8s.io/volumes/glusterfs/README.md

SpinApp.spec.volumes[index].hostPath

back to parent

hostPath represents a pre-existing file or directory on the host machine that is directly exposed to the container. This is generally used for system agents or other privileged things that are allowed to see the host machine. Most containers will NOT need this. More info: https://kubernetes.io/docs/concepts/storage/volumes#hostpath

TODO(jonesdl) We need to restrict who can use host directory mounts and who can/can not mount host directories as read/write.

SpinApp.spec.volumes[index].iscsi

back to parent

iscsi represents an ISCSI Disk resource that is attached to a kubelet’s host machine and then exposed to the pod. More info: https://examples.k8s.io/volumes/iscsi/README.md

SpinApp.spec.volumes[index].iscsi.secretRef

back to parent

secretRef is the CHAP Secret for iSCSI target and initiator authentication

SpinApp.spec.volumes[index].nfs

back to parent

nfs represents an NFS mount on the host that shares a pod’s lifetime More info: https://kubernetes.io/docs/concepts/storage/volumes#nfs

SpinApp.spec.volumes[index].persistentVolumeClaim

back to parent

persistentVolumeClaimVolumeSource represents a reference to a PersistentVolumeClaim in the same namespace. More info: https://kubernetes.io/docs/concepts/storage/persistent-volumes#persistentvolumeclaims

SpinApp.spec.volumes[index].photonPersistentDisk

back to parent

photonPersistentDisk represents a PhotonController persistent disk attached and mounted on kubelets host machine

SpinApp.spec.volumes[index].portworxVolume

back to parent

portworxVolume represents a portworx volume attached and mounted on kubelets host machine

SpinApp.spec.volumes[index].projected

back to parent

projected items for all in one resources secrets, configmaps, and downward API

SpinApp.spec.volumes[index].projected.sources[index]

back to parent

Projection that may be projected along with other supported volume types

SpinApp.spec.volumes[index].projected.sources[index].clusterTrustBundle

back to parent

ClusterTrustBundle allows a pod to access the .spec.trustBundle field of ClusterTrustBundle objects in an auto-updating file.

Alpha, gated by the ClusterTrustBundleProjection feature gate.

ClusterTrustBundle objects can either be selected by name, or by the combination of signer name and a label selector.

Kubelet performs aggressive normalization of the PEM contents written into the pod filesystem. Esoteric PEM features such as inter-block comments and block headers are stripped. Certificates are deduplicated. The ordering of certificates within the file is arbitrary, and Kubelet may change the order over time.

SpinApp.spec.volumes[index].projected.sources[index].clusterTrustBundle.labelSelector

back to parent

Select all ClusterTrustBundles that match this label selector. Only has effect if signerName is set. Mutually-exclusive with name. If unset, interpreted as “match nothing”. If set but empty, interpreted as “match everything”.

SpinApp.spec.volumes[index].projected.sources[index].clusterTrustBundle.labelSelector.matchExpressions[index]

back to parent

A label selector requirement is a selector that contains values, a key, and an operator that relates the key and values.

SpinApp.spec.volumes[index].projected.sources[index].configMap

back to parent

configMap information about the configMap data to project

SpinApp.spec.volumes[index].projected.sources[index].configMap.items[index]

back to parent

Maps a string key to a path within a volume.

SpinApp.spec.volumes[index].projected.sources[index].downwardAPI

back to parent

downwardAPI information about the downwardAPI data to project

SpinApp.spec.volumes[index].projected.sources[index].downwardAPI.items[index]

back to parent

DownwardAPIVolumeFile represents information to create the file containing the pod field

SpinApp.spec.volumes[index].projected.sources[index].downwardAPI.items[index].fieldRef

back to parent

Required: Selects a field of the pod: only annotations, labels, name and namespace are supported.

SpinApp.spec.volumes[index].projected.sources[index].downwardAPI.items[index].resourceFieldRef

back to parent

Selects a resource of the container: only resources limits and requests (limits.cpu, limits.memory, requests.cpu and requests.memory) are currently supported.

SpinApp.spec.volumes[index].projected.sources[index].secret

back to parent

secret information about the secret data to project

SpinApp.spec.volumes[index].projected.sources[index].secret.items[index]

back to parent

Maps a string key to a path within a volume.

SpinApp.spec.volumes[index].projected.sources[index].serviceAccountToken

back to parent

serviceAccountToken is information about the serviceAccountToken data to project

SpinApp.spec.volumes[index].quobyte

back to parent

quobyte represents a Quobyte mount on the host that shares a pod’s lifetime

SpinApp.spec.volumes[index].rbd

back to parent

rbd represents a Rados Block Device mount on the host that shares a pod’s lifetime. More info: https://examples.k8s.io/volumes/rbd/README.md

SpinApp.spec.volumes[index].rbd.secretRef

back to parent

secretRef is name of the authentication secret for RBDUser. If provided overrides keyring. Default is nil. More info: https://examples.k8s.io/volumes/rbd/README.md#how-to-use-it

SpinApp.spec.volumes[index].scaleIO

back to parent

scaleIO represents a ScaleIO persistent volume attached and mounted on Kubernetes nodes.