Deploy with kind
Overview
kind is a Kubernetes distribution designed to run local clusters for local development or CI, using nodes that run as containers.
This deployment guide will demonstrate how to deploy wasmCloud to a kind cluster and run wasmCloud applications built from WebAssembly components.
Install tools
In addition to kind and the container tooling a kind cluster requires to run, this guide uses Helm and the wasmCloud Shell (wash) CLI. (For an alternative, script-driven kind quickstart using Kustomize, see the community contributions repository.)
Install container tooling
kind requires container tooling and supports Docker, podman, and nerdctl. Install the container toolchain of your choice before installing kind.
Install kind
If you do not already have kind, you can install it with the Go toolchain.
go install sigs.k8s.io/kind@v0.23.0
You may need to add your Go binary folder to your PATH as well:
export PATH=${PATH}:`go env GOPATH`/bin
Start a local Kubernetes cluster:
cat <<EOF | kind create cluster --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
kubeadmConfigPatches:
- |
kind: InitConfiguration
nodeRegistration:
kubeletExtraArgs:
node-labels: "ingress-ready=true"
extraPortMappings:
- containerPort: 80
hostPort: 80
protocol: TCP
- containerPort: 443
hostPort: 443
protocol: TCP
EOF
Install Helm
Helm serves as a package manager for Kubernetes. Follow the instructions on the Helm install page or use the project's install script:
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
chmod 700 get_helm.sh
./get_helm.sh
Install wash
Once wasmCloud is deployed to your kind cluster, you can use the wasmCloud Shell (wash) CLI to manage wasmCloud applications. If you do not have wash installed locally, follow the instructions on the install page.
Deploying wasmCloud
Once a kind cluster is running locally, you can run wasmCloud on Kubernetes with the wasmCloud Kubernetes operator. An operator is an extension that uses custom Kubernetes resources to manage an application—you can learn more about the Kubernetes operator pattern in the Kubernetes documentation.
Before deploying the operator, it is necessary to deploy two prerequisites to the cluster:
- NATS (with Jetstream enabled)
- wasmCloud Application Deployment Manager (wadm)
The following steps will help you deploy the prerequisites to your Kubernetes cluster, then deploy the operator.
Deploy NATS
NATS is the open source connective technology that wasmCloud uses to create a unified topology across any number of environments. Add the NATS Helm repository:
helm repo add nats https://nats-io.github.io/k8s/helm/charts/
Install the upstream NATS Helm chart to start a cluster with the values.yaml file from the wasmCloud operator repository:
helm upgrade --install -f https://raw.githubusercontent.com/wasmCloud/wasmcloud-operator/main/examples/quickstart/nats-values.yaml nats nats/nats
Validate the installation with:
kubectl rollout status deploy,sts -l app.kubernetes.io/instance=nats
Deploy wadm
wasmCloud Application Deployment Manager (wadm) enables declarative application deployment and management for wasmCloud. You can deploy wadm to your Kubernetes cluster with a Helm chart:
helm install wadm -f https://raw.githubusercontent.com/wasmCloud/wasmcloud-operator/main/examples/quickstart/wadm-values.yaml oci://ghcr.io/wasmcloud/charts/wadm
Validate the installation with:
kubectl rollout status deploy -l app.kubernetes.io/instance=wadm
Deploy the wasmCloud operator
To deploy the operator:
kubectl apply -k https://github.com/wasmCloud/wasmcloud-operator/deploy/base
Validate that the pods are ready:
kubectl rollout status deploy -l app=wasmcloud-operator -n wasmcloud-operator
Validate that the apiservice is available:
kubectl wait --for condition=available apiservices.apiregistration.k8s.io v1beta1.core.oam.dev
Create wasmCloud host
Apply the wasmcloud-host manifest:
kubectl apply -f https://raw.githubusercontent.com/wasmCloud/wasmcloud-operator/main/examples/quickstart/wasmcloud-host.yaml
Check wasmCloud host status:
kubectl describe wasmcloudhostconfig wasmcloud-host
Run a WebAssembly component on Kubernetes
When you kubectl apply a wasmCloud application manifest, the cluster automatically provisions the component workload with wasmCloud.
This example uses the hello-world-application.yaml manifest included in the operator's quickstart. (The source code for the application is available in the wasmCloud repository.)
Below is an excerpt of the manifest:
...
spec:
components:
- name: http-component
type: component
properties:
image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
...
The component is packaged as an OCI artifact and specified in the image field. This isn't a container, but a component conforming to OCI standards, meaning that it can be used with existing registries for container images.
Run kubectl apply:
kubectl apply -f https://raw.githubusercontent.com/wasmCloud/wasmcloud-operator/main/examples/quickstart/hello-world-application.yaml
View the deployment status:
kubectl get application
APPLICATION DEPLOYED VERSION LATEST VERSION STATUS
hello-world v0.0.1 v0.0.1 Deployed
When you run a wasmCloud application that uses the httpserver provider with a daemonscaler, as this one does, the operator automatically creates a Kubernetes service for the application.
View services:
kubectl get services
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
hello-world ClusterIP 10.96.199.43 <none> 8080/TCP 11s
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 6m29s
nats ClusterIP 10.96.104.180 <none> 4222/TCP,7422/TCP,4223/TCP 5m36s
nats-headless ClusterIP None <none> 4222/TCP,7422/TCP,4223/TCP,6222/TCP,8222/TCP 5m36s
wasmcloud-host ClusterIP 10.96.67.225 <none> 4222/TCP 84s
Test the application
On a cluster without ingress (such as this one), you can still test the component from within the wasmCloud host container where the application is running.
Assign the wasmCloud host pod name to an environment variable:
WASMCLOUD_HOST_POD=$(kubectl get pods -o jsonpath="{.items[*].metadata.name}" -l app.kubernetes.io/instance=wasmcloud-host)
Port-forward the wasmCloud host's port 8080:
kubectl port-forward pods/$WASMCLOUD_HOST_POD 8080
curl the application:
curl http://localhost:8080
Debugging
You can use kubectl to get logs from the wasmCloud host running on your kind cluster:
kubectl logs -l app.kubernetes.io/instance=wasmcloud-host -c wasmcloud-host
Common mistakes
- If you're having trouble deploying an application, make sure your wadm application manifest references an OCI image and not a local file.
- If a service is not automatically generated for an application using the httpserver provider, check to ensure that the provider uses
daemonscalerin the application manifest. (You can see an example of this in thehello-world-applicationmanifest.)
Manage applications with wash
To connect wash to the cluster, port-forward into the NATS service running in your Kubernetes cluster. (Note: 4222 is the port for the NATS service, 4223 is the port for NATS websockets.)
kubectl port-forward svc/nats 4222:4222 4223:4223
Now you can connect to wasmCloud on Kubernetes with your local wash toolchain:
wash app list
View the hello-world application running on the Kubernetes cluster, manageable via our local wash CLI:
Name Latest Version Deployed Version Deploy Status Description
hello-world v0.0.1 v0.0.1 Deployed HTTP hello world demo in Rust, using the WebAssembly Component Model and WebAssembly Interfaces Types (WIT)
Clean up
To delete the kind cluster when you are finished:
kind delete cluster