Get Started

Cosmonic Control runs on any Kubernetes cluster. This guide walks through installing Cosmonic Control and deploying your first workload.

For production deployments, see the Operator Manual or a platform-specific deployment guide.

Get started for free

Cosmonic Control is free to get started. For enterprise use with unlimited HTTPTriggers per namespace, the Project grouping type, and the Artifact pre-fetch controller, contact us.

Prerequisites

• kubectl
• Helm v3.8.0+

1. Set up a cluster

Select your Kubernetes environment:

Existing cluster

If you already have a Kubernetes cluster, skip cluster creation. Verify your kubectl context is pointing to the right cluster:

kubectl cluster-info

k3d

k3d runs a lightweight k3s cluster inside Docker. It starts in seconds, uses minimal resources, and supports LoadBalancer services natively.

Requirements: Docker · k3d

k3d cluster create cosmonic \
  --port "80:80@loadbalancer" \
  --k3s-arg "--disable=traefik@server:0"

k3s

k3s is a single-binary Kubernetes distribution with no container runtime dependency. Linux only.

Install k3s:

curl -sfL https://get.k3s.io | sh -

Configure kubectl to use the k3s cluster:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER ~/.kube/config

kind

kind runs Kubernetes nodes as Docker containers.

Requirements: Docker · kind

Create a cluster with port 80 mapped for Envoy ingress:

cat <<EOF | kind create cluster --config=-
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30950
    hostPort: 80
    protocol: TCP
EOF

2. Install Cosmonic Control

Existing cluster

For cloud clusters (EKS, GKE, AKS, etc.), a cloud load balancer is provisioned automatically:

helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control \
  --version 0.3.0 \
  --namespace cosmonic-system \
  --create-namespace \
  --set envoy.service.type=LoadBalancer

For bare-metal or on-premises clusters without a load balancer controller, use NodePort and configure your own ingress to route traffic to port 30950.

k3d

helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control \
  --version 0.3.0 \
  --namespace cosmonic-system \
  --create-namespace \
  --set envoy.service.type=LoadBalancer

k3s

helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control \
  --version 0.3.0 \
  --namespace cosmonic-system \
  --create-namespace \
  --set envoy.service.type=LoadBalancer

kind

helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control \
  --version 0.3.0 \
  --namespace cosmonic-system \
  --create-namespace \
  --set envoy.service.type=NodePort \
  --set envoy.service.httpNodePort=30950

Wait for all components to be ready:

kubectl rollout status deploy -l app.kubernetes.io/instance=cosmonic-control -n cosmonic-system

Install a HostGroup:

helm install hostgroup oci://ghcr.io/cosmonic/cosmonic-control-hostgroup \
  --version 0.3.0 \
  --namespace cosmonic-system

kubectl rollout status deploy -l app.kubernetes.io/instance=hostgroup -n cosmonic-system

3. Deploy a workload

Deploy welcome-tour to verify everything is working end-to-end:

helm install welcome-tour --version 0.1.2 \
  oci://ghcr.io/cosmonic-labs/charts/http-trigger \
  -f https://raw.githubusercontent.com/cosmonic-labs/control-demos/refs/heads/main/welcome-tour/values.http-trigger.yaml

Wait for the workload's READY status to be TRUE:

kubectl get workloads

Open http://welcome-tour.localhost.cosmonic.sh in your browser.

note

localhost.cosmonic.sh is a public wildcard DNS entry that resolves to 127.0.0.1—no /etc/hosts edits required. For cloud or remote clusters, use your Envoy LoadBalancer service's external IP with the Host: welcome-tour.localhost.cosmonic.sh header instead.

Next steps

• Explore more examples — browse the Template Catalog for additional Wasm component demos
• Build your own component — see the wasmCloud Developer Guide to build and publish a Wasm component
• Deploy to production — see the Operator Manual for production-grade configuration, HostGroup scaling, and ingress setup

Cleaning up

Existing cluster

helm uninstall welcome-tour
helm uninstall hostgroup -n cosmonic-system
helm uninstall cosmonic-control -n cosmonic-system
kubectl delete ns cosmonic-system

k3d

The fastest way to clean up is to delete the entire cluster:

k3d cluster delete cosmonic

To remove only the Cosmonic Control workloads while keeping the cluster:

helm uninstall welcome-tour
helm uninstall hostgroup -n cosmonic-system
helm uninstall cosmonic-control -n cosmonic-system
kubectl delete ns cosmonic-system

k3s

Remove the Cosmonic Control workloads:

helm uninstall welcome-tour
helm uninstall hostgroup -n cosmonic-system
helm uninstall cosmonic-control -n cosmonic-system
kubectl delete ns cosmonic-system

To remove k3s entirely:

sudo /usr/local/bin/k3s-uninstall.sh

kind

The fastest way to clean up is to delete the entire cluster:

kind delete cluster

To remove only the Cosmonic Control workloads while keeping the cluster:

helm uninstall welcome-tour
helm uninstall hostgroup -n cosmonic-system
helm uninstall cosmonic-control -n cosmonic-system
kubectl delete ns cosmonic-system

Frequently asked questions

Can I install the chart with a Helm 3 version prior to v3.8.0?

In versions of Helm 3 prior to v3.8.0, OCI support was experimental. You can run export HELM_EXPERIMENTAL_OCI=1 to enable it, but some OCI functionality may behave differently. See the Helm documentation for details.

How do I mirror images to my own internal registry?

Use the global.image.registry and global.image.pullSecrets Helm values to point to your registry. See the Air-Gapped Installation guide for a full example using ORAS.