Skip to main content
Version: v2.0.0-rc.1

Kubernetes Operator

The wasmCloud operator makes it easy to run wasmCloud and WebAssembly workloads on Kubernetes.​

We use the operator pattern to run wasmCloud on Kubernetes, leveraging the orchestrator to schedule wasmCloud infrastructure and workloads.

By aligning to Kubernetes, teams can adopt WebAssembly (Wasm) progressively—and integrate wasmCloud with existing tooling for ingress, registries, CI/CD, and other areas of the cloud-native ecosystem.

The wasmCloud platform on Kubernetes​

Along with the wasmCloud operator, the wasmCloud platform on Kubernetes consists of these core parts:

  • Custom resource definitions (CRDs) for wasmCloud infrastructure and Wasm workloads.
  • wasmCloud host(s) - Sandboxed runtime environments for WebAssembly components. (By default, these are wash binaries using the wash host command to surface the wash-runtime API.)
  • NATS with Jetstream - CNCF project that provides a connective layer for transport between operator and hosts, along with built-in object storage through Jetstream.

The entire platform can be deployed with Helm using the wasmCloud operator Helm chart. (NATS and hosts can also be installed separately, if you wish.)

note

During the pre-release period for wasmCloud v2, use the charts/runtime-operator chart for testing v2 deployments. On the official v2.0.0 release, the charts/wasmcloud-operator chart image will advance from wasmCloud v1 to wasmCloud v2, and the pre-release runtime-operator chart will be retired.

Get started with the wasmCloud operator​

Installation requires the following tools:

You'll also need a Kubernetes environment. We recommend kind for the best local Kubernetes experience.

Local Kubernetes environment​

You can use the one-liner below to...

  • Download a kind configuration from the wasmcloud/runtime-operator repository
  • Start a cluster
  • Delete the configuration file upon completion
shell
curl -fLO https://raw.githubusercontent.com/wasmCloud/runtime-operator/refs/heads/main/kind-config.yaml && kind create cluster --config=kind-config.yaml && rm kind-config.yaml

If you'd rather start your cluster manually, copy the configuration below into a file called kind-config.yaml:

yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
  - role: control-plane
    extraPortMappings:
      - containerPort: 30950
        hostPort: 80
        protocol: TCP
shell
kind create cluster --config=kind-config.yaml

Install the wasmCloud operator​

Use Helm to install the wasmCloud operator from an OCI chart image, using the values for local installation from the wasmcloud/runtime-operator repository:

shell
helm install wasmcloud --version 0.1.0 oci://ghcr.io/wasmcloud/charts/runtime-operator -f https://raw.githubusercontent.com/wasmCloud/runtime-operator/refs/heads/main/charts/runtime-operator/values.local.yaml

Along with the wasmCloud operator, wasmCloud CRDs, and NATS, the Helm chart will deploy three wasmCloud hosts using the wasmcloud/wash container image:

  • default: A simple default host
  • public-ingress: A host with ingress via NodePort from outside your local Kubernetes environment (when using the kind configuration above)
  • private-ingress: A host with cluster-internal ingress via ClusterIP

You can build your own hosts that provide extended capabilities via host plugins.

note

You can find the full set of configurable values for the chart in the wasmcloud/runtime-operator repository.

Deploy a Wasm component​

Use a WorkloadDeployment manifest to deploy a Wasm component workload to your cluster:

yaml
apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: WorkloadDeployment
metadata:
  name: hello-world
spec:
  replicas: 1
  template:
    spec:
      hostSelector:
        hostgroup: public-ingress
      components:
        - name: hello-world
          image: ghcr.io/wasmcloud/components/hello-world:0.1.0
      hostInterfaces:
        - namespace: wasi
          package: http
          interfaces:
            - incoming-handler
          config:
            host: localhost

This manifest deploys a simple "Hello world!" component that uses the wasi:http interface to the public-ingress hostgroup, making it available to call via HTTP from outside the cluster.

You can deploy from the wasmCloud-hosted manifest with this kubectl command:

shell
kubectl apply -f https://raw.githubusercontent.com/wasmCloud/wash/refs/heads/main/examples/http-hello-world/manifests/workloaddeployment.yaml
note

Learn more about WorkloadDeployments and other wasmCloud resources in the Custom Resource Definitions (CRDs) section.

Now you can use curl to invoke the component with an HTTP request:

shell
curl localhost -i
text
Hello from wasmCloud!

Clean up​

Delete the workload deployment:

shell
kubectl delete workloaddeployment hello-world

Uninstall wasmCloud:

shell
helm uninstall wasmcloud

Delete the local Kubernetes environment:

shell
kind delete cluster

Next steps​