Skip to main content

Deploy on VMware vSphere Kubernetes Service (VKS)

Overview​

This deployment guide demonstrates how to install Cosmonic Control on a VMware vSphere Kubernetes Service (VKS) cluster, enabling the cluster to run both traditional pod deployments and WebAssembly (Wasm) workloads.

The deployment process includes the following steps:

  1. Deploy Helm charts for Cosmonic Control and a hostgroup
  2. Configure Contour ingress to route subdomains to the Cosmonic Control Envoy service for xDS-based Wasm workload routing
  3. Set up Contour ingress to the Cosmonic Perses UI for OpenTelemetry (OTEL) querying and monitoring

For an overview of the Cosmonic Control architecture, refer to the Architecture documentation.

Requirements​

To follow this guide, you will need a VKS cluster (minimum VKS 3.5+ required) and a Cosmonic Control license, as well as typical VMware Cloud Foundation (VCF) and Kubernetes tooling:

Before installing Cosmonic Control, ensure that Contour is configured as an ingress controller and cert-manager is installed (recommended for TLS support).

Set up VKS Cluster​

The vcf CLI makes it easy to extend your cluster by using the vcf addons command. Additional information is available in the vcf CLI documentation.

Add VKS standard add-ons​

vcf addon repository add vks-repo --url projects.packages.broadcom.com/vsphere/supervisor/packages/2025.10.22/vks-standard-packages:3.5.0-20251022 -n packages

Install cert-manager​

vcf addon install cert-manager -p cert-manager.kubernetes.vmware.com --version 1.18.2+vmware.2-vks.2 -n packages

Install Contour​

Follow the VMware VCF documentation for detailed Contour installation instructions.

Retrieve and customize the default values file:

vcf addon available get contour.kubernetes.vmware.com/1.33.0+vmware.1-vks.1 --default-values-file-output contour-data-values.yaml -n packages

A sample configuration is available in the vcf-cosmonic-control GitHub repository.

Install Contour with the customized values:

vcf addon install contour -p contour.kubernetes.vmware.com --version 1.33.0+vmware.1-vks.1 --values-file contour-data-values.yaml -n packages

Install Cosmonic Control​

Refer to the Cosmonic Control documentation for detailed installation guidelines.

Option 1: Helm Installation​

Basic Installation (without Console UI)​

Install Cosmonic Control with a NodePort service for the Envoy proxy:

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-key>"

Installation with Console UI​

To enable the Cosmonic Control Console UI, configure the console_ui.enabled and hostName parameters. A sample values file is available in the vcf-cosmonic-control GitHub repository.

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-key>" \
  --set hostName="console.localhost.cosmonic.sh" \
  --set console_ui.enabled=true

Install Cosmonic Control Hostgroup​

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

Configure Contour Ingress​

The vcf-contour folder in the vcf-cosmonic-control GitHub repository contains ingress configurations for integrating Cosmonic Control with VCF's Contour ingress controller.

  • vcf-contour/vcf-nihao-example-deployment.yaml: This example demonstrates basic Contour ingress functionality. Refer to the VMware Contour ingress documentation for implementation details.
  • vcf-contour/cosmonic-ingress.yaml: Configures ingress for the Cosmonic Console and Perses UI in the cosmonic-system namespace. The default hostnames are console.vcf.cosmonic.world and perses.vcf.cosmonic.world. For testing, you may use localhost.cosmonic.sh which resolves to 127.0.0.1.
  • vcf-contour/vcf-wasm-ingress.yaml: Routes all *.vcf-wasm.cosmonic.world traffic to the Cosmonic Envoy ingress service. For production environments, consider specifying individual hosts instead of wildcards to reduce invalid hostname requests.
  • vcf-contour/wasm-ingress-examples.yaml: Contains examples for specific domain routing as well as path-based routing to a Wasm workload. This can be used for when an application is containerized, but has components that are Sandboxed/Wasm workloads as well.

Option 2: ArgoCD Installation​

For a GitOps-based deployment approach using ArgoCD, see the sample-argo-gh-folder-structure directory in the vcf-cosmonic-control GitHub repository for an example repo structure that demonstrates how to deploy both Cosmonic Control and sample Wasm workloads.

Deploy WebAssembly Workloads​

WebAssembly workloads are deployed by creating an HTTPTrigger resource. Examples are available in the sample-argo-gh-folder-structure/apps folder of the vcf-cosmonic-control GitHub repository.

For additional examples and deployment patterns, refer to the Cosmonic Labs control-demos repository.

Example: Using Helm to Deploy​

The welcome-tour demo demonstrates deploying Wasm workloads using Helm. Refer to the welcome-tour repository for implementation details.

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