Skip to main content
Version: 0.82

Deploying wasmCloud on Kubernetes

wasmCloud is compatible with, but not dependent on, Kubernetes. We think the future of WebAssembly is bright, and we also know there are plenty of systems already running in Kubernetes. For this reason, we provide the wasmCloud operator to help users run wasmCloud hosts on a Kubernetes cluster—and thereby run WebAssembly components on Kubernetes.

For high-level discussion of our approach to Kubernetes and compatibility with common cloud native tooling, see wasmCloud on Kubernetes.

On this page, you can find documentation for operators wishing to deploy wasmCloud with Kubernetes, including details on prerequisites such as NATS and how to deploy the operator.

Getting started with the wasmCloud operator

The wasmCloud operator can be found on GitHub at It uses custom resource definitions (CRDs) to define wasmCloud hosts as Kubernetes resources.

In order to follow the instructions on this page, you will need a Kubernetes cluster and appropriate access credentials as well as a Helm installation.

Deploying the operator

A wasmCloud cluster requires a few things to run:

  • A NATS cluster with Jetstream enabled
  • WADM connected to the NATS cluster in order to support applications

If you are running locally, the following steps will help you start a NATS cluster and wadm in your Kubernetes cluster, then deploy the operator.


Make sure you have a Kubernetes cluster running locally. Some good options include kind, minikube, or Docker Desktop.

Running NATS

Add the NATS Helm repo:

helm repo add nats

Install the upstream NATS Helm chart to start a cluster with the following values.yaml file:

    enabled: true
    replicas: 3
    enabled: true
    enabled: true
        size: 10Gi
      domain: default
helm upgrade --install -f values.yaml nats-cluster nats/nats

Running wadm

You can deploy wadm to your Kubernetes cluster with the wadm Helm chart. First, clone the wadm repo from GitHub:

git clone

In the cloned repo, find the chart at wadm/charts/wadm. In your values.yaml file, the server field for NATS should be set to:

server: 'nats-cluster.default.svc.cluster.local:4222'

Run helm install from wadm/charts/wadm in the cloned repo:

helm install wadm -f values.yaml ./

Setting up Secrets

The WasmCloudHostConfig CRD describes the desired state of a set of wasmCloud hosts connected to the same lattice:

kind: WasmCloudHostConfig
  name: my-wasmcloud-cluster
  # The number of wasmCloud host pods to run
  hostReplicas: 2
  # The cluster issuers to use for each host
    # This needs to be the public key of a cluster seed generated by
    # `wash keys gen cluster`
    - CDK...
  # The lattice to connect the hosts to
  lattice: 83a5b52e-17cf-4080-bac8-f844099f142e
  # Additional labels to apply to the host other than the defaults set in the operator
    some-label: value
  # Which wasmCloud version to use
  version: 0.82.0
  # The name of a secret in the same namespace that provides the required secrets.
  secretName: cluster-secrets
  # Enable the following to run the wasmCloud hosts as a DaemonSet
  #daemonset: true
  # The name of the image pull secret to use with wasmCloud hosts so that they
  # can authenticate to a private registry to pull components.
  # registryCredentialsSecret: my-registry-secret

The CRD requires a Kubernetes Secret with the following keys:

apiVersion: v1
kind: Secret
  name: my-wasmcloud-cluster
  # You can generate this with wash:
  # `wash keys gen cluster`
  # For more on wash see
  # Only required if using a NATS creds file
  # nats.creds: <base64 encoded creds file>

You can apply Secrets with kubectl:

kubectl apply -f your-secret-manifest.yaml
Secrets required

The operator will fail to provision the wasmCloud Deployment if any of these secrets are missing.

Image pull secrets (Optional)

You can also specify an image pull secret to use use with the wasmCloud hosts so that they can pull components from a private registry. This secret needs to be in the same namespace as the WasmCloudHostConfig CRD and must be a type secret. See the Kubernetes documentation for more information on how to provision that secret.

Once it is created, you can reference an image pull secret in the WasmCloudHostConfig CRD by setting the registryCredentialsSecret field to the name of the secret.

Start the operator

kubectl kustomize build deploy/local | kubectl apply -f -

Argo CD Health Check (Optional)

Argo CD provides a way to define a custom health check that it then runs against a given resource to determine whether or not the resource is in healthy state.

For this purpose, we specifically expose a status.phase field, which exposes the underlying status information from wadm.

With the following ConfigMap, a custom health check can be added to an existing Argo CD installation for tracking the health of wadm applications.

apiVersion: v1
kind: ConfigMap
  name: argocd-cm
  namespace: argocd
  labels: argocd-cm argocd
  resource.customizations: |
      health.lua: |
        hs = {}
        hs.status = "Progressing"
        hs.message = "Reconciling application state"
        if obj.status ~= nil and obj.status.phase ~= nil then
          if obj.status.phase == "Deployed" then
            hs.status = "Healthy"
            hs.message = "Application is ready"
          if obj.status.phase == "Reconciling" then
            hs.status = "Progressing"
            hs.message = "Application has been deployed"
          if obj.status.phase == "Failed" then
            hs.status = "Degraded"
            hs.message = "Application failed to deploy"
          if obj.status.phase == "Undeployed" then
            hs.status = "Suspended"
            hs.message = "Application is undeployed"
        return hs