Skip to main content
Version: v2

Custom Resource Definitions (CRDs)

When deployed to Kubernetes, the core primitives of wasmCloud are represented by custom resources definitions (CRDs).

wasmCloud uses CRDs from the runtime.wasmcloud.dev/v1alpha1 API package:

This document explains each of these custom resources at a high level. For a complete API specification, see the API reference.

note

WorkloadDeployment is the resource used to deploy Wasm workloads—if you're looking to quickly deploy a component, start there.

Artifact​

An Artifact represents a Wasm component that can be referenced by Workloads. Artifacts define the image location and optional image pull secrets for accessing private registries. This can be used to fetch an OCI image and store its contents in a NATS JetStream Object Store.

The Artifact resource tracks individual revisions, publishing the artifact's location under Status.ArtifactURL. A WorkloadDeployment can reference an Artifact as its component image. A new deployment will be automatically rolled out when a new image is detected.

Use Artifact when you want the operator to watch for new image versions and trigger rolling updates automatically, or to centralize image pull secrets so individual WorkloadDeployment manifests don't need to repeat them.

Example manifest:

yaml
apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: Artifact
metadata:
  name: http-hello-world
  namespace: default
spec:
  image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
  imagePullSecret:
    name: ghcr-secret

Host​

A Host resource defines a wasmCloud runtime environment, or host, which has a unique ID and can run Wasm workloads.

Example manifest:

yaml
apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: Host
metadata:
  name: host-sample
  namespace: default
  labels:
    hostgroup: default
spec:
  hostId: NABCDEFGHIJKLMNOPQRSTUVWXYZ234567
  hostname: host-sample.default
  httpPort: 4000

Workload​

A Workload represents an application composed of one or more WebAssembly components and optional services. Workloads define the components, their configurations, volume mounts, and host interfaces they consume.

Workloads are analogous to Kubernetes Pods in that they typically are not managed individually, but are instead owned by a WorkloadDeployment, much as a Pod is owned by a Deployment.

Example manifest:

yaml
apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: Workload
metadata:
  name: hello-world
  namespace: default
spec:
  hostSelector:
    hostgroup: default
  components:
    - name: http-component
      image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
      poolSize: 10
      maxInvocations: 1000
      localResources:
        environment:
          config:
            LOG_LEVEL: info
        allowedHosts:
          - https://api.example.com
  hostInterfaces:
    - namespace: wasi
      package: http
      interfaces:
        - incoming-handler
      config:
        address: '0.0.0.0:8080'
  volumes:
    - name: cache
      ephemeral: {}

WorkloadDeployment​

A WorkloadDeployment defines the deployment and scaling of Workloads across hosts. It creates and manages WorkloadReplicaSets to ensure the desired number of workload replicas are running.

Example manifest:

yaml
apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: WorkloadDeployment
metadata:
  name: hello-world
  namespace: default
spec:
  replicas: 3
  deployPolicy: RollingUpdate
  artifacts:
    - name: http-component
      artifactFrom:
        name: http-hello-world
  template:
    metadata:
      labels:
        app: hello-world
    spec:
      hostSelector:
        hostgroup: default
      components:
        - name: http-component
          image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
          poolSize: 10
      hostInterfaces:
        - namespace: wasi
          package: http
          interfaces:
            - incoming-handler
          config:
            address: '0.0.0.0:8080'

Host Interfaces​

Use the hostInterfaces field to define host interfaces used by the workload. Each entry requires namespace, package, and interfaces, and may optionally include config and name.

The optional name field enables multi-backend binding: when a component needs multiple implementations of the same interface type (e.g., two wasi:keyvalue backends), each entry can be given a unique name. The name maps directly to the identifier argument in resource-opening functions such as store::open("cache").

yaml
hostInterfaces:
  # Named: NATS-backed keyvalue for caching
  - name: cache
    namespace: wasi
    package: keyvalue
    interfaces: [store, atomics, batch]
    config:
      backend: nats
      bucket: cache-kv
  # Named: Redis-backed keyvalue for sessions
  - name: sessions
    namespace: wasi
    package: keyvalue
    interfaces: [store]
    config:
      backend: redis
      url: redis://redis:6379
  # Unnamed: single HTTP interface (name not required)
  - namespace: wasi
    package: http
    interfaces: [incoming-handler]
    config:
      address: '0.0.0.0:8080'

Naming rules:

  • name is optional. Omitting it preserves existing single-backend behavior.
  • When two or more entries share the same namespace+package, all of them must have a non-empty name.
  • Names must be unique within a workload's hostInterfaces for the same namespace+package.
  • Names must match [a-z0-9][a-z0-9-]* (DNS label style).

Runtime Configuration​

Runtime configuration values (such as environment variables) may be supplied via the optional localResources subfield of the component field.

yaml
localResources:
  environment:
    config:
      some_key: some_value

Environmental values may also come from ConfigMaps or Secrets. The following approaches are also valid:

yaml
localResources:
  environment:
    configFrom:
      - name: my-configmap
    secretFrom:
      - name: my-secret
    config:
      literal_key: literal_value

Component resource controls​

The poolSize, maxInvocations, and allowedHosts fields on a component control how it runs inside the host. They are set under spec.template.spec.components[*] in a WorkloadDeployment (or directly in a Workload).

  • poolSize: Sets the maximum number of concurrent instances of this component that the host will pre-allocate in its execution pool. Higher values increase throughput under load; lower values reduce memory consumption. If omitted, the host uses its default pool size.
  • maxInvocations: Limits the number of in-flight invocations allowed for this component at any one time. Requests that exceed this limit are queued or rejected, providing back-pressure to protect host resources.
  • allowedHosts: A list of hostnames or URLs this component is permitted to make outbound HTTP calls to. Calls to addresses not on this list are blocked, enforcing a least-privilege network policy for the component.

WorkloadReplicaSet​

A WorkloadReplicaSet ensures that a given number of Workload replicas are running at once. It is typically managed by a WorkloadDeployment but can be used directly for more granular control.

Example manifest:

yaml
apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: WorkloadReplicaSet
metadata:
  name: hello-world-v1
  namespace: default
spec:
  replicas: 5
  template:
    metadata:
      labels:
        app: hello-world
        version: v1
    spec:
      hostSelector:
        hostgroup: default
      components:
        - name: http-component
          image: ghcr.io/wasmcloud/components/http-hello-world-rust:0.1.0
          poolSize: 10
      hostInterfaces:
        - namespace: wasi
          package: http
          interfaces:
            - incoming-handler
          config:
            address: '0.0.0.0:8080'