Skip to main content
Version: v2

Helm Values Reference

This page documents the configuration values you are most likely to override when installing the runtime-operator Helm chart. For the authoritative list of every value the chart supports, run:

shell
helm show values oci://ghcr.io/wasmcloud/charts/runtime-operator --version <version>

Top-level structure​

The chart's values.yaml is organized into five top-level sections:

SectionPurpose
globalSettings that apply across all components (image registry, TLS, image pull secrets)
natsThe bundled NATS server — set enabled: false to connect an external NATS cluster instead
operatorThe wasmCloud runtime-operator deployment
gatewayDeprecated in 2.0.3. Legacy runtime-gateway. Set enabled: false to skip installing it
runtimeHost group deployments (pods running the wash host binary)

global​

global.image.registry​

Override the container image registry for all components at once. Useful for air-gapped or mirrored deployments.

yaml
global:
  image:
    registry: myregistry.example.com

See Private Registries and Air-Gapped Deployments for the full mirroring workflow.

global.tls.enabled​

Introduced in 2.0.3. Set to false to disable TLS for NATS connections and skip certificate generation. Intended for clusters where a service mesh (e.g. Istio, Linkerd) provides mTLS between pods.

yaml
global:
  tls:
    enabled: false

When global.tls.enabled is false, the chart ignores global.certificates.generate — no self-signed certs are created and NATS runs plaintext.

global.certificates.generate​

Controls whether the chart generates self-signed TLS certificates for NATS and the control plane. Set to false when bringing your own certificate secrets. See the TLS: bring your own certificates recipe for the full BYOC flow.

global.nats.schedulerUrl and global.nats.dataUrl​

Introduced in 2.4.0. The chart now exposes two NATS URLs separately:

  • global.nats.schedulerUrl — the control-plane URL the operator (-nats-url) and the host runtime (--scheduler-nats-url) connect to for workload scheduling and host heartbeats.
  • global.nats.dataUrl — the data-plane URL the host runtime (--data-nats-url) uses for Wasm workload messaging, key-value, and blobstore backends.

Both default to nats://nats.<release-namespace>.svc.cluster.local:4222 when left empty (matching pre-2.4 behavior). Splitting them lets workloads target a separate NATS cluster from the scheduler — useful when application traffic and operator coordination live on different brokers.

yaml
global:
  nats:
    schedulerUrl: "nats://control-plane.example.internal:4222"
    dataUrl: "nats://data-plane.example.internal:4222"

Per-host-group overrides are also available via runtime.hostGroups[].schedulerNatsUrl and runtime.hostGroups[].dataNatsUrl.

operator, nats, runtime — pod labels and annotations​

Introduced in 2.0.3. Each deployment accepts podLabels and podAnnotations that are merged into the pod template. This is most commonly used for service mesh injection:

yaml
operator:
  podLabels:
    sidecar.istio.io/inject: "true"
  podAnnotations:
    proxy.istio.io/config: '{"holdApplicationUntilProxyStarts": true}'

nats:
  podLabels:
    sidecar.istio.io/inject: "true"

runtime:
  podLabels:
    sidecar.istio.io/inject: "true"

operator​

operator.watchNamespaces​

By default, the operator watches every namespace in the cluster. Set watchNamespaces to a list of namespace names to scope it down:

yaml
operator:
  watchNamespaces:
    - team-a
    - team-b

When watchNamespaces is populated, the chart drops the operator's cluster-wide ClusterRole and ClusterRoleBinding entirely and renders a set of Role + RoleBinding pairs in each watched namespace instead. Per watched namespace:

  • <release>-workload-crd covers the runtime.wasmcloud.dev workload resources — artifacts, workloads, workloadreplicasets, workloaddeployments, plus their /status and /finalizers subresources
  • <release>-workload-namespace covers per-workload core resources — configmaps, secrets, events, services (plus services/finalizers)
  • <release>-endpointslice covers endpointslices for Kubernetes-native traffic routing

Host CRD grants stay on the namespaced Role in the operator's own namespace (host pods aren't tenant-scoped), and <release>-leader-election continues to live there too. The net effect: an operator.watchNamespaces install holds no cluster-wide permissions for workload resources and can be deployed with namespace-admin RBAC alone for those namespaces.

info

This namespaced-by-default behavior for the runtime.wasmcloud.dev apiGroup landed in 2.3.0 (#5208). Earlier releases bound the workload CRD verbs cluster-wide even when watchNamespaces was set.

operator.hostNamespaces​

Introduced in 2.1. List of namespaces where host pods run. The operator's pod informer cache and per-namespace pod RBAC cover this set so the host-pod controller can manage finalizers on host pods. Leave empty when host pods only run in the operator's own namespace (the chart's default).

yaml
operator:
  hostNamespaces:
    - team-a
    - team-b

When you set runtime.hostGroups[].namespace to deploy host pods outside the operator's namespace, also include those namespaces here — otherwise the operator can't observe or finalize the host pods running there.

operator.allowSharedHosts​

Introduced in 2.1. Default: true. Controls whether WorkloadDeployments can schedule onto hosts whose Host.environment differs from the workload's own namespace, via spec.template.spec.environment.

yaml
operator:
  allowSharedHosts: false

The default (true) preserves the existing behavior where workloads with no environment set may schedule onto any matching host regardless of which tenant namespace the host runs in. This is permissive: in a multi-tenant cluster where each tenant has its own namespace and host pods, a workload in team-a can target hosts in team-b simply by setting spec.template.spec.environment: team-b.

Set to false when namespace boundaries are part of your tenant isolation model. With allowSharedHosts: false:

  • Scheduling is locked to the workload's own namespace.
  • Any cross-namespace environment value is rejected with a CrossEnvironmentSchedulingDenied Warning Event and a HostSelection=False condition on the Workload.

See Troubleshooting: Workload stays unscheduled with allowSharedHosts: false for the symptom and resolution patterns.

operator.env, operator.envFrom, and operator.extraArgs​

Introduced in 2.4.0. Three passthrough fields that let chart users wire operator-side configuration without forking the chart:

  • operator.env — additional environment variables for the operator container, appended after the chart-managed vars. Standard Kubernetes env shape (supports valueFrom with secretKeyRef / configMapKeyRef).
  • operator.envFrom — populate the operator container's environment from ConfigMaps or Secrets, using the standard Kubernetes envFrom shape.
  • operator.extraArgs — additional CLI args appended verbatim to the operator container, for operator flags the chart does not template (e.g. -leader-elect, -cpu-backpressure-threshold=75).
yaml
operator:
  env:
    - name: LOG_LEVEL
      value: debug
  envFrom:
    - secretRef:
        name: operator-extra-config
  extraArgs:
    - "-leader-elect"

operator.image.tag​

Defaults to the chart's appVersion. Override only when you need to pin to a specific operator build that differs from the chart release:

yaml
operator:
  image:
    tag: "2.4.0"

The same pattern applies to gateway.image.tag and runtime.image.tag.

gateway (deprecated)​

Deprecated

The runtime-gateway is deprecated as of 2.0.3. HTTP routing is now handled by the runtime-operator via EndpointSlices tied to user-defined Kubernetes Services. See Expose a Workload via Kubernetes Service for the replacement pattern.

To skip installing the gateway, set gateway.enabled: false.

yaml
gateway:
  enabled: false

runtime​

runtime.env, runtime.envFrom, and runtime.extraArgs​

Introduced in 2.4.0. Chart-wide host configuration applied to every host group's container. Per-host-group values (see runtime.hostGroups[].env etc.) are appended after these, letting one group extend the chart-wide defaults without redefining them.

  • runtime.env — additional environment variables applied to every host group container, appended after the chart-managed vars (WASMCLOUD_HOST_IP, WASMCLOUD_HOST_ENVIRONMENT) and before any per-host-group env.
  • runtime.envFrom — populate every host group container's environment from ConfigMaps or Secrets.
  • runtime.extraArgs — additional CLI args appended to every host group container, for host flags the chart does not template. Merged with per-host-group extraArgs.
yaml
runtime:
  env:
    - name: RUST_LOG
      value: info
  envFrom:
    - configMapRef:
        name: shared-host-config
  extraArgs:
    - "--max-concurrent-workloads=64"

runtime.hostGroups​

A host group is a Deployment of pods running the wash host. You can define multiple groups to isolate workloads or provide specialized capabilities (e.g. WebGPU-enabled hosts):

yaml
runtime:
  hostGroups:
    - name: default
      replicas: 3
      http:
        enabled: true
        port: 80
      resources:
        requests:
          memory: "64Mi"
          cpu: "250m"
        limits:
          memory: "512Mi"
          cpu: "500m"
    - name: gpu
      replicas: 1
      webgpu:
        enabled: true

WorkloadDeployment manifests target a group via spec.template.spec.hostSelector.hostgroup.

runtime.hostGroups[].namespace​

Introduced in 2.1. Namespace to deploy this host group's Deployment, Service, generated TLS Secret, and ServiceAccount into. Empty (default) deploys to the chart release's namespace.

yaml
runtime:
  hostGroups:
    - name: team-a
      namespace: team-a
      replicas: 2

When you override this, ensure the namespace exists and is included in operator.hostNamespaces so the operator has the pod RBAC and informer cache access it needs to manage host pod lifecycle there. Each host's Host.environment will reflect the namespace where its pod runs, which is what allowSharedHosts: false matches against for namespace-scoped scheduling.

runtime.hostGroups[].schedulerNatsUrl and runtime.hostGroups[].dataNatsUrl​

Introduced in 2.4.0. Per-host-group overrides for the NATS URLs the host runtime connects to. Both fall back to the chart-wide global.nats.schedulerUrl / global.nats.dataUrl when empty, which in turn fall back to the in-cluster NATS service.

yaml
runtime:
  hostGroups:
    - name: edge
      replicas: 2
      dataNatsUrl: "nats://edge-data.example.internal:4222"

Use this when a single chart release runs host groups against different data-plane brokers (for example, regional NATS clusters for an edge group while the default group stays on the in-cluster broker).

runtime.hostGroups[].env, envFrom, and extraArgs​

Introduced in 2.4.0. Per-host-group versions of the chart-wide runtime.env / envFrom / extraArgs fields. These are appended after the chart-wide values, so a group can extend the shared defaults without redeclaring them.

yaml
runtime:
  env:
    - name: RUST_LOG
      value: info
  hostGroups:
    - name: gpu
      replicas: 1
      env:
        - name: RUST_LOG
          value: debug   # overrides the chart-wide value for this group only
      extraArgs:
        - "--wasi-webgpu-debug"

runtime.hostGroups[].volumes, volumeMounts, and ports​

Introduced in 2.4.0. Optional passthrough fields rendered directly into the host group's pod and container spec, letting chart users mount ConfigMaps / Secrets / persistent volumes and expose extra container ports without forking the chart.

  • runtime.hostGroups[].volumes — appended to the pod's spec.volumes. Standard Kubernetes volume shape.
  • runtime.hostGroups[].volumeMounts — appended to the host container's volumeMounts. Pair each entry with a matching volumes entry above.
  • runtime.hostGroups[].ports — appended to the host container's ports. Typically used to expose a metrics scrape port for Prometheus.
yaml
runtime:
  hostGroups:
    - name: default
      replicas: 3
      volumes:
        - name: app-config
          configMap:
            name: my-host-config
      volumeMounts:
        - name: app-config
          mountPath: /etc/wasmcloud/config
          readOnly: true
      ports:
        - name: metrics
          containerPort: 9090
          protocol: TCP

All three fields render unconditionally, so they survive a global.tls.enabled: false install. Do not re-list the HTTP port in ports — the chart already renders it from .http.port, and a duplicate containerPort fails Deployment validation. See Filesystems and Volumes for the broader volume story.

runtime.hostGroups[].http.port​

Starting in 2.0.3, this value is honored by the host (it was previously hardcoded). This is the port the host's HTTP server listens on inside the pod, and the port the operator populates into each managed EndpointSlice. The upstream chart default is 9191; the values.local.yaml overlay overrides it to 80 for local development.

runtime.hostGroups[].webgpu.enabled​

Enables the WebGPU plugin on hosts in the group. Requires a host image built with the wasi-webgpu feature.

runtime.image.tag​

Starting in 2.0.3, this value defaults to the chart's appVersion (previously defaulted to a hardcoded tag). Leave unset to track the chart release.