Install Cosmonic Control

Cosmonic Control is an enterprise control plane for managing WebAssembly (Wasm) workloads in cloud native environments.

License key required

You'll need a Cosmonic license key to follow these instructions. Sign up for Cosmonic Control's free trial to get a key.

Requirements

Kubernetes
Helm v3.8.0+

Local Kubernetes

For the best local Kubernetes development experience, we recommend installing kind and starting a cluster with the following kind-config.yaml configuration, enabling simple local ingress with Envoy:

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
# One control plane node and three "workers."
nodes:
- role: control-plane
  extraPortMappings:
  - containerPort: 30950
    hostPort: 80
    protocol: TCP

The following command downloads the kind-config.yaml from the control-demos repository, starts a cluster, and deletes the config upon completion:

curl -fLO https://raw.githubusercontent.com/cosmonic-labs/control-demos/refs/heads/main/kind-config.yaml && kind create cluster --config=kind-config.yaml && rm kind-config.yaml

Installation

For a local development installation with ingress using Envoy:

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\
  --set cosmonicLicenseKey="<insert license here>"

To install without configuring ingress:

helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control\
  --version 0.3.0\
  --namespace cosmonic-system\
  --create-namespace\
  --set cosmonicLicenseKey="<insert license here>"

Registry and image pull secret overrides

The Cosmonic Control Helm chart mirrors images for open source components to our registry (ghcr.io/cosmonic). If you need to mirror to your own internal registry (e.g., Artifactory), you can use the global.image.registry and global.image.pullSecrets override fields to set your registry and image pull secret respectively.

Helm will confirm a successful installation:

Pulled: registry-1.docker.io/cosmonic/cosmonic-control:0.3.0
Digest: sha256:<hash>
NAME: cosmonic-control
LAST DEPLOYED: <date>
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Congratulations! You have successfully installed Cosmonic Control!

You may validate that all pods are ready by running:

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

Validate that the HostGroup is ready by running:

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

Deploy the Welcome Tour component:

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

Running the Welcome Tour on Kubernetes

If you're using the local dvelopment setup, open your browser to http://welcome-tour.localhost.cosmonic.sh to see the tour!

Open the Console

Port-forward the Console:

kubectl -n cosmonic-system port-forward svc/console 8080:8080

Open the Console at localhost:8080.

Cleaning up

helm uninstall welcome-tour

helm uninstall hostgroup -n cosmonic-system

helm uninstall cosmonic-control -n cosmonic-system

kubectl delete ns cosmonic-system

Declarative values configuration

The Cosmonic Control Helm chart uses the values.yaml file below.

# Additional configuration options for Cosmonic Control
global:
  image:
    # -- Globally override container image registry, e.g. "ghcr.io"
    registry: ''
    # -- Globally override container imagePullSecrets
    pullSecrets: []

nameOverride: ''
fullnameOverride: ''

cosmonicLicenseKey: 'test-license'

# -- This section builds out the service account.
# See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/security/service-accounts/).
serviceAccount:
  # -- Specifies whether a service account should be created
  create: true
  # -- Automatically mount a ServiceAccount's API credentials?
  automountServiceAccountToken: true
  # -- Annotations to add to the service account
  annotations: {}

rbac:
  create: true

You can declaratively customize values and override the chart defaults as needed by running (from your working directory):

helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control --version 0.2.0 -f values.yaml

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 Helm v3.8.0, OCI support was an experimental feature. You can run export HELM_EXPERIMENTAL_OCI=1 to enable support, but some OCI functionality may perform differently. See the Helm documentation for more information.

How do I mirror images to my own internal registry?

You can use the global.image.registry and global.image.pullSecrets override fields to set your registry and image pull secret respectively.

An example script to mirror images using ORAS follows. First, create a mirror.yaml file with the source and destination images, and a mirror.sh script to run the mirroring:

cat <<EOF >mirror.yaml
images:
  # Cosmonic Control Images
  # replace myartifactory with your registry
  - source: ghcr.io/cosmonic/control-console:v0.2.0
    destination: myartifactory/cosmonic/control-console:v0.2.0
  - source: ghcr.io/cosmonic/control-host:v0.2.0
    destination: myartifactory/cosmonic/control-host:v0.2.0
  - source: ghcr.io/cosmonic/platform-operator:v0.2.0
    destination: myartifactory/cosmonic/platform-operator:v0.2.0
  - source: ghcr.io/cosmonic/runtime-operator:v0.2.0
    destination: myartifactory/cosmonic/runtime-operator:v0.2.0
  - source: ghcr.io/cosmonic/nexus:v0.2.0
    destination: myartifactory/cosmonic/nexus:v0.2.0

  # third party images
  - source: docker.io/prom/prometheus:v3.3.1
    destination: myartifactory/cosmonic/control/prometheus:v3.3.1
  - source: docker.io/grafana/loki:3.5
    destination: myartifactory/cosmonic/control/loki:3.5
  - source: docker.io/otel/opentelemetry-collector-contrib:0.120.0
    destination: myartifactory/cosmonic/control/otel-collector-contrib:0.120.0
  - source: docker.io/grafana/grafana-oss:12.0.2
    destination: myartifactory/cosmonic/control/grafana-oss:12.0.2
EOF

cat <<EOF >./mirror.sh
#!/bin/bash
CONFIG_FILE="mirror.yaml"

if command -v oras >/dev/null 2>&1; then
  echo "oras is installed: $(oras version)"
else
  echo "oras not found. Please install: https://oras.land"
fi

echo "Mirroring images from $CONFIG_FILE..."
yq -o=json e '.images[]' "$CONFIG_FILE" | jq -c '.' | while read -r line; do
    src=$(echo "$line" | jq -r '.source')
    dst=$(echo "$line" | jq -r '.destination')
    if [[ -n "$src" && -n "$dst" && "$dst" != "null" ]]; then
      echo "oras copy $src $dst"
      oras copy "$src" "$dst"
    fi
done
EOF

Run the mirror script:

chmod +x ./mirror.sh
./mirror.sh

Now install the chart with the registry (add a pull secret override if needed):

helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control\
  --version 0.2.0\
  --namespace cosmonic-system\
  --create-namespace\
  --set cosmonicLicenseKey="<insert license here>"\
  --set global.image.registry="myartifactory"

Requirements​

Local Kubernetes​

Installation​

Running the Welcome Tour on Kubernetes​

Open the Console​

Cleaning up​

Declarative values configuration​

Frequently asked questions​