Skip to main content
Version: 1.x

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.

shell
go install sigs.k8s.io/kind@v0.23.0

You may need to add your Go binary folder to your PATH as well:

shell
export PATH=${PATH}:`go env GOPATH`/bin

Start a local Kubernetes cluster:

shell
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:

shell
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.

In order to deploy wasmCloud on kind, first install the wasmcloud-platform Helm chart. By default, the chart installs NATS, wadm, and the wasmCloud operator subchart.

shell
helm upgrade --install \
    wasmcloud-platform \
    --values https://raw.githubusercontent.com/wasmCloud/wasmcloud/main/charts/wasmcloud-platform/values.yaml \
    oci://ghcr.io/wasmcloud/charts/wasmcloud-platform \
    --dependency-update

Wait for all components to install and wadm-nats communications to establish:

shell
kubectl rollout status deploy,sts -l app.kubernetes.io/name=nats
shell
kubectl wait --for=condition=available --timeout=600s deploy -l app.kubernetes.io/name=wadm
shell
kubectl wait --for=condition=available --timeout=600s deploy -l app.kubernetes.io/name=wasmcloud-operator

Next create a wasmCloud host:

shell
helm upgrade --install \
    wasmcloud-platform \
    --values https://raw.githubusercontent.com/wasmCloud/wasmcloud/main/charts/wasmcloud-platform/values.yaml \
    oci://ghcr.io/wasmcloud/charts/wasmcloud-platform \
    --dependency-update \
    --set "hostConfig.enabled=true"

If the deployment is successful, you should receive the note:

shell
✨ Congratulations! Your wasmCloud platform has been deployed successfully.
   - 🛀 To use the wash cli with your new wasmCloud platform, run:
    kubectl port-forward service/nats 4222:4222 4223:4223

   - 🗺️  To launch the wasmCloud dashboard on http://localhost:3030, in a different terminal window, run:
     wash ui

If you'd like, you can check wasmCloud host status:

shell
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:

yaml
...
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:

shell
kubectl apply -f https://raw.githubusercontent.com/wasmCloud/wasmcloud-operator/main/examples/quickstart/hello-world-application.yaml

View the deployment status:

shell
kubectl get application
text
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:

shell
kubectl get services
text
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:

shell
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:

shell
kubectl port-forward pods/$WASMCLOUD_HOST_POD 8080

curl the application:

shell
curl http://localhost:8080

Debugging​

You can use kubectl to get logs from the wasmCloud host running on your kind cluster:

shell
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 daemonscaler in the application manifest. (You can see an example of this in the hello-world-application manifest.)

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.)

shell
kubectl port-forward svc/nats 4222:4222 4223:4223

Now you can connect to wasmCloud on Kubernetes with your local wash toolchain:

shell
wash app list

View the hello-world application running on the Kubernetes cluster, manageable via our local wash CLI:

text
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:

shell
kind delete cluster