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 k8s.cosmonic.io/v1alpha1 and runtime.wasmcloud.dev/v1alpha1 API packages:

• Artifact - artifacts.runtime.wasmcloud.dev/v1alpha1
• Host - hosts.runtime.wasmcloud.dev/v1alpha1
• HostGroup - hostgroups.k8s.cosmonic.io/v1alpha1
• Workload - workloads.runtime.wasmcloud.dev/v1alpha1
• WorkloadDeployment - workloaddeployments.runtime.wasmcloud.dev/v1alpha1
• WorkloadReplicaSet - workloadreplicasets.runtime.wasmcloud.dev/v1alpha1

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

Artifact

The Artifact resource represents a WebAssembly component that can be referenced by workloads. Artifacts define the image location and optional image pull secrets for accessing private registries.

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

HostGroup

The HostGroup resource represents a set of wasmCloud hosts that can be scaled together.

Example manifest:

apiVersion: k8s.cosmonic.io/v1alpha1
kind: HostGroup
metadata:
  name: default
spec:
  replicas: 1

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

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'