---
title: "Get Started | Cosmonic"
description: "Install Cosmonic Control on any Kubernetes cluster in minutes."
canonical: "https://cosmonic.com/docs/install-cosmonic-control/"
---

# 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](https://cosmonic.com/docs/operations/deploying-to-cosmonic-control/) or a [platform-specific deployment guide](https://cosmonic.com/docs/deployment-guides/cosmonic-control-on-vmware-vsphere-kubernetes-service/).

> **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](mailto:support@cosmonic.com).

## Prerequisites

- [`kubectl`](https://kubernetes.io/releases/download/)
- [Helm](https://helm.sh/docs) 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:

```shell
kubectl cluster-info
```

**k3d**

[k3d](https://k3d.io/) runs a lightweight [k3s](https://k3s.io/) cluster inside Docker. It starts in seconds and uses minimal resources.

**Requirements:** [Docker](https://docs.docker.com/get-started/get-docker/) · [k3d](https://k3d.io/#installation)

Map host ports 80 and 443 to the Cosmonic Control Traefik NodePorts (30080 and 30443), and disable k3s's built-in Traefik so it does not conflict with the chart's:

```shell
k3d cluster create cosmonic \
  --port "80:30080@loadbalancer" \
  --port "443:30443@loadbalancer" \
  --k3s-arg "--disable=traefik@server:0"
```

**k3s**

[k3s](https://k3s.io/) is a single-binary Kubernetes distribution with no container runtime dependency. **Linux only.**

Install k3s with its built-in Traefik disabled (the Cosmonic Control chart deploys its own):

```shell
curl -sfL https://get.k3s.io | sh -s - --disable=traefik
```

Configure `kubectl` to use the k3s cluster:

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

**kind**

[kind](https://kind.sigs.k8s.io/) runs Kubernetes nodes as Docker containers.

**Requirements:** [Docker](https://docs.docker.com/get-started/get-docker/) · [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)

Create a cluster that maps host ports 80 and 443 to the Cosmonic Control Traefik NodePorts (30080 and 30443):

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

## 2. Install Cosmonic Control

The chart deploys Traefik as the edge proxy by default. Install with no overrides:

```shell
helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control \
  --version 0.15.0 \
  --namespace cosmonic-system \
  --create-namespace
```

> **Pre-configure ingress hosts**
>
> To auto-create a Traefik `Ingress` for one or more workload hosts at install time, pass `ingress.hosts` to the chart. This skips the manual `kubectl apply` of an `Ingress` in step 3:
>
> ```shell
> helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control \
>   --version 0.15.0 \
>   --namespace cosmonic-system --create-namespace \
>   --set 'ingress.hosts[0].host=welcome-tour.localhost.cosmonic.sh'
> ```
>
> See [Ingress and Workloads](https://cosmonic.com/docs/operations/ingress-and-workloads/#traefik-default) for the full pattern.

**Existing cluster**

Traefik is exposed on `NodePort` 30080 (http) and 30443 (https) inside the cluster. To reach it externally on a cloud cluster, either:

- Patch the Traefik Service to `LoadBalancer` so the cloud provisions an LB:

  ```shell
  kubectl patch svc traefik -n cosmonic-system -p '{"spec":{"type":"LoadBalancer"}}'
  ```
- Or front the Traefik NodePorts with an existing cloud or in-cluster load balancer.

For other ingress topologies (Istio, or exposing Envoy directly without the edge proxy), see [Ingress and Workloads](https://cosmonic.com/docs/operations/ingress-and-workloads/).

**k3d**

The host ports configured during cluster creation already forward to Traefik's NodePorts. No extra steps are needed.

**k3s**

Traefik's NodePorts (30080/30443) are reachable directly on the node. To reach Traefik on host port 80 instead, patch the Service to `LoadBalancer` and let k3s's built-in `klipper-lb` claim the host port:

```shell
kubectl patch svc traefik -n cosmonic-system -p '{"spec":{"type":"LoadBalancer"}}'
```

**kind**

The `extraPortMappings` configured during cluster creation already forward host 80 and 443 to Traefik's NodePorts. No extra steps are needed.

Wait for all components to be ready:

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

Install a HostGroup:

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

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

### GPU workloads

For workloads that import `wasi:webgpu/webgpu@0.0.1`, pass `--set gpu=true` so the host advertises the WebGPU interface. Without it, the workload sticks at `WORKLOAD_STATE_ERROR` because `hostInterfaces` acts as a scheduling filter — declaring an interface the host does not advertise prevents placement, not just linking.

```shell
helm install hostgroup oci://ghcr.io/cosmonic/cosmonic-control-hostgroup \
  --version 0.15.0 \
  --namespace cosmonic-system \
  --set gpu=true
```

The host pod must run on a node with a usable GPU exposed to it (Metal, Vulkan, or DX12 via `wgpu`); on managed clusters this typically means a GPU node pool plus the appropriate device-plugin daemonset.

### Override the host image for testing pre-release builds

The hostgroup chart pulls `ghcr.io/cosmonic/control-host:<appVersion>` by default. To run a pre-release build (for example, `canary` published from `cosmonic/control` `main`), override `image.tag`:

```shell
helm upgrade --install hostgroup oci://ghcr.io/cosmonic/cosmonic-control-hostgroup \
  --version 0.15.0 \
  --namespace cosmonic-system \
  --reuse-values \
  --set image.tag=canary
```

### Turn up operator logs when triaging

The Cosmonic Control operator defaults to `info`-level logs. Set `operator.logLevel=debug` to restore the verbose reconciliation traces (the hard-coded default before v0.6.1):

```shell
helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control \
  --version 0.15.0 \
  --namespace cosmonic-system --create-namespace \
  --set operator.logLevel=debug
```

Valid values: `debug`, `info`, `warn`, `error`. Useful for live troubleshooting; the verbosity isn't typically helpful in steady state.

### Trusting a private CA

The `caBundle` values mount a PEM bundle into a pod's system trust store, so a process that reads the system trust store can validate TLS against an internal or private CA. Declare the bundle once at the chart level and opt individual components in.

```shell
helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control \
  --version 0.15.0 \
  --namespace cosmonic-system --create-namespace \
  --set-file caBundle.contents=/path/to/bundle.pem \
  --set operator.caBundleEnabled=true
```

The hostgroup chart has a single-component equivalent under `caBundle.enabled`. `caBundle.contents` (inline PEM), `caBundle.existingConfigMap`, and `caBundle.existingSecret` are mutually exclusive; pick whichever fits your trust-store source (e.g. a `trust-manager` Bundle target). Only opted-in pods restart on rotation.

**Pulling images from a registry behind a private CA is covered as of v0.9.3.** The host's OCI client validates registry TLS against its own built-in roots rather than the mounted system trust store, so enabling `caBundle` also renders the host's `--oci-ca-path`. That is what makes a registry fronted by a private CA (for example an in-cluster Harbor) trusted for image pulls, for workload components and host component plugins alike. On v0.9.2 and earlier this case was not covered; there, pull from a registry with a publicly trusted certificate, or [mirror images](https://cosmonic.com/docs/operations/air-gapped-installation/) to one.

## 3. Deploy a workload

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

```shell
helm install welcome-tour --version 0.2.0 \
  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`:

```shell
kubectl get workloads
```

Create a Traefik `Ingress` so external traffic for the workload's host reaches Envoy:

```shell
cat <<EOF | kubectl apply -f -
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: welcome-tour
  namespace: cosmonic-system
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: web,websecure
spec:
  ingressClassName: traefik
  rules:
    - host: welcome-tour.localhost.cosmonic.sh
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: ingress
                port:
                  number: 80
EOF
```

Open [http://welcome-tour.localhost.cosmonic.sh](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`, so no `/etc/hosts` edits are required. For cloud or remote clusters, use the Traefik `LoadBalancer` service's external IP with the `Host: welcome-tour.localhost.cosmonic.sh` header. For k3s without a `LoadBalancer` patch, append `:30080` to the URL.

## Next steps

- **Explore more examples** — browse the [Template Catalog](https://cosmonic.com/docs/template-catalog/) for additional Wasm component demos
- **Build your own component** — see the [wasmCloud Developer Guide](https://wasmcloud.com/docs/wash/developer-guide/) to build and publish a Wasm component
- **Deploy to production** — see the [Operator Manual](https://cosmonic.com/docs/operations/deploying-to-cosmonic-control/) for production-grade configuration, HostGroup scaling, and ingress setup

## Cleaning up

**Existing cluster**

```shell
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:

```shell
k3d cluster delete cosmonic
```

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

```shell
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:

```shell
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:

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

**kind**

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

```shell
kind delete cluster
```

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

```shell
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](https://helm.sh/docs/topics/registries/) 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](https://cosmonic.com/docs/operations/air-gapped-installation/) guide for a full example using [ORAS](https://oras.land/).

Last updated on **Nov 10, 2026** by **Liam Randall**
