Skip to main content
Version: v2

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 run a cluster host (washlet) that surfaces the wash-runtime API over NATS.)
  • Runtime Gateway - HTTP reverse proxy that routes incoming requests to the appropriate wasmCloud host based on deployed workloads. Exposed as a Kubernetes Service.
  • NATS with JetStream - CNCF project that provides a connective layer for transport between operator and hosts, along with built-in object storage through JetStream. NATS carries all control-plane traffic to the host (the host never communicates directly with the Kubernetes API). The operator sends workload start/stop requests to individual hosts via NATS subjects, and hosts self-register by publishing heartbeat messages the operator subscribes to. The Helm chart bundles NATS automatically—you can also connect an existing NATS cluster by setting nats.enabled: false and pointing the operator at your endpoint.

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

For a detailed breakdown of each component's responsibilities and the request flow, see the Operator and Gateway Overview.

Get started with the wasmCloud operator​

Installation requires the following tools:

Select your Kubernetes environment:

If you already have a Kubernetes cluster, skip cluster creation. Verify your kubectl context is pointing to the right cluster:

shell
kubectl cluster-info

Install the wasmCloud operator​

Use Helm to install the wasmCloud operator from an OCI chart image:

shell
helm install wasmcloud --version v2.0.1 oci://ghcr.io/wasmcloud/charts/runtime-operator \
  -f https://raw.githubusercontent.com/wasmCloud/wasmCloud/refs/heads/main/charts/runtime-operator/values.local.yaml \
  --set gateway.service.type=LoadBalancer

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

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 wasmCloud/wasmCloud/charts/runtime-operator.

Verify the deployment:

shell
kubectl get pods -l app.kubernetes.io/instance=wasmcloud -n default

Once all pods are running, you're ready to deploy a Wasm workload.

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: default
      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 default 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/wasmCloud/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:

No action needed — your cluster remains running.

Next steps​