Skip to main content

Custom Resources

Core primitives in Cosmonic Control are represented by Kubernetes custom resources. Custom resources may be declaratively provisioned and managed using the API extensions defined in Custom Resource Definitions (CRDs).

Cosmonic Control uses CRDs for the following custom resources from the control.cosmonic.io/v1alpha2, control.cosmonic.io/v1alpha1 and runtime.wasmcloud.dev/v1alpha1 API packages:

For complete API specifications, see the API references for control.cosmonic.io and runtime.wasmcloud.dev/v1alpha1.

Artifact​

The Artifact resource represents a WebAssembly component image that can be referenced by workloads. Artifacts define the image location and optional image pull secrets for accessing private registries. The resource can be used to fetch an OCI image and store its contents in a NATS JetStream Object Store, reducing registry load by downloading artifacts once and distributing them internally. The Artifact resource tracks individual revisions, publishing the artifact's location under Status.ArtifactURL.

WorkloadDeployment can reference Artifacts as their component image. The controller will automatically roll the deployment when a new image is detected.

Example manifest:

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​

The Host resource represents a wasmCloud runtime environment called a host. Each host has a unique ID and can run workloads.

Example manifest:

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

HTTPTrigger​

The HTTPTrigger resource routes HTTP traffic from Cosmonic Control's ingress to Wasm workloads. Its spec is shaped like the Gateway API HTTPRoute: it lists the hostnames it serves and a set of rules, and each rule sends matching requests to one or more WorkloadDeployments in the same namespace, split by weight. The trigger does not create the workload; deploy the WorkloadDeployment alongside it.

As of Cosmonic Control v0.13.0, HTTPTrigger is served as control.cosmonic.io/v1alpha2. Earlier releases used v1alpha1, which embedded the workload in the trigger; see Upgrading from v0.12.2 to v0.13.0 to migrate.

See Ingress and Workloads for a full reference and examples.

Example manifest:

apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: WorkloadDeployment
metadata:
  name: hello-world
  namespace: default
spec:
  replicas: 1
  template:
    spec:
      hostInterfaces:
        - namespace: wasi
          package: http
          interfaces:
            - incoming-handler
          config:
            host: hello.localhost.cosmonic.sh
      components:
        - name: http
          image: ghcr.io/cosmonic-labs/control-demos/hello-world:0.1.2
---
apiVersion: control.cosmonic.io/v1alpha2
kind: HTTPTrigger
metadata:
  name: hello-world
  namespace: default
spec:
  hostnames:
    - hello.localhost.cosmonic.sh
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: hello-world

The WorkloadDeployment declares the inbound wasi:http interface itself: incoming-handler for a WASI P2 component, handler for a WASI P3 component. config.host names the hostname the workload serves; when it is set, Envoy rewrites the Host header to it and keeps the client's original host in X-Forwarded-Host.

The entry needs no version. A WorkloadDeployment with no inbound wasi:http entry still schedules and reports ready, but it answers every request with 404.

Splitting traffic between workloads​

A rule can list several backends with a weight each. Weights are relative, and 0 sends a backend nothing:

spec:
  hostnames:
    - hello.example.com
  rules:
    - backendRefs:
        - name: hello-v1
          weight: 90
        - name: hello-v2
          weight: 10

Backends in one rule that set different config.host values cannot share the rule; the trigger reports IncompatibleBackendHosts.

Pinning to a host environment​

Environment pinning lives on the WorkloadDeployment, as spec.template.spec.environment. It pins the workloads to hosts reporting that environment in their heartbeat. When unset, the workload is unpinned and the scheduler treats every host as fair game, including shared host groups that serve multiple tenants. Set it to keep workloads on a tenant-scoped host group, or to route them onto a dedicated shared host group such as infra:

apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: WorkloadDeployment
spec:
  template:
    spec:
      environment: team-a
      # ...

The environment value is matched against the environment HostGroup pods report; see Installing HostGroups for setting it on a HostGroup. An environment other than the workload's own namespace is honored only while the control chart's operator.allowSharedHosts is true (the default).

Autoscaling​

WorkloadDeployment exposes the Kubernetes /scale subresource, so a stock HorizontalPodAutoscaler or KEDA ScaledObject can target it directly. As of v0.13.0 HTTPTrigger has no replicas and no /scale subresource. See Autoscaling.

ProjectEnvironment​

Enterprise

ProjectEnvironment is an enterprise feature. It is available with an enterprise license and is not required for free-tier use.

The ProjectEnvironment resource defines team membership and roles for a Kubernetes namespace managed as a Cosmonic Control project. It is used in conjunction with the enterprise Project grouping type to provide namespace-scoped multi-tenancy with RBAC.

Example manifest:

apiVersion: control.cosmonic.io/v1alpha1
kind: ProjectEnvironment
metadata:
  name: my-project
  namespace: my-namespace
spec:
  groups:
    - name: platform-team
      role: admin
    - name: app-team
      role: developer

Workload​

The Workload resource 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.

Example manifest:

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: {}

The poolSize, maxConcurrency, and maxInvocations fields on a component set how many calls a warm instance serves at once and how many instances the host keeps. Because instance concurrency drives how many connections a workload needs, size those fields together with the host's per-workload connection quotas. The upstream wasmCloud Concurrency and connections guide walks through the interaction and a worked sizing example.

WorkloadDeployment​

The WorkloadDeployment resource manages 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:

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'

WorkloadReplicaSet​

The WorkloadReplicaSet resource ensures that a specified number of workload replicas are running at any given time. It is typically managed by a WorkloadDeployment but can be used directly for more granular control.

Example manifest:

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'
Last updated on by github-actions[bot]