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+

Installation

helm install cosmonic-control oci://ghcr.io/cosmonic/cosmonic-control\
  --version 0.2.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.1.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!

Install a HostGroup:

helm install hostgroup oci://ghcr.io/cosmonic/cosmonic-control-hostgroup --version 0.2.0 --namespace cosmonic-system --set http.enabled=true

Deploy the Welcome Tour component:

helm install welcome-tour oci://ghcr.io/cosmonic-labs/charts/welcome-tour -n welcome-app --create-namespace --version 0.1.0

Running the Welcome Tour on Kubernetes

In separate terminal tabs:

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

kubectl -n cosmonic-system port-forward svc/hostgroup-default 9091:9091

Open browser to http://localhost:9091 to see the tour!

See some of the resources running with:

kubectl get hosts

kubectl get components -A

kubectl get providers -A

Cleaning up

helm uninstall welcome-tour -n welcome-app

kubectl delete ns welcome-app

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"