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

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 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 is the primary way to deploy a Wasm component to Cosmonic Control. It combines an HTTP ingress rule (host, paths) with a workload specification into a single resource, so you don't need to manage Workload, WorkloadDeployment, and ingress objects separately.

See Ingress and Workloads for a full reference and examples.

Example manifest:

apiVersion: control.cosmonic.io/v1alpha1
kind: HTTPTrigger
metadata:
  name: hello-world
  namespace: default
spec:
  replicas: 1
  ingress:
    host: hello.localhost.cosmonic.sh
    paths:
      - path: /
        pathType: Prefix
  template:
    spec:
      components:
        - name: http
          image: ghcr.io/cosmonic-labs/control-demos/hello-world:0.1.2

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

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'