Creating a vCluster using CLI

Login into Kosmos #

kosmos login https://console.kosmos.spcplatform.com/ --access-key <your-access-key>

Output: 14:13:32 done Successfully logged into Kosmos instance https://console.kosmos.spcplatform.com

Validate Kosmos CLI version #

Make sure you use Komos CLI version 4.3.16 (or later):

kosmos --version

Output: kosmosctl version 4.3.16

YAML file for vCluster #

Generic Yaml VirtualCluster Template

apiVersion: storage.kosmos.spcplatform.com/v1
kind: VirtualClusterTemplate
metadata:
  name: <template-name>
spec:
  displayName: <template-name>
  description: <description>
  template:
    accessPoint:
      ingress:
        enabled: <true|false>
    helmRelease:
      chart:
        version: <int>
      values: |
        sync:
          toHost:
            ingresses:
              enabled: <true|false>
          fromHost:
            nodes:
              enabled: <true|false>
            ingressClasses:
              enabled: <true|false>

Example:

Create a YAML file for vCluster create-vcluster.yaml. This is an example, please make necessary change in as per your devspace and users.

% cat create-vcluster.yaml
apiVersion: storage.kosmos.spcplatform.com/v1
kind: VirtualClusterInstance
metadata:
  name: my-vcluster-name
  namespace: my-devspace-name
spec:
  displayName: my-vcluster-name
  description: This vCluster is created using CLI.
  owner:
    user: khangnguyen
  templateRef:
    name: vcluster
    version: 0.21.2
  clusterRef:
    cluster: dx-aws-sandbox-stg-apne2-eks
  extraAccessRules:
    - clusterRole: cluster-admin
      users:
      - khangnguyen
      - khanguyenmsxv

Note: DevSpace namespaces start with the loft-p- prefix.

Create the vCluster #

Execute “kosmos” to create the vCluster:

kosmos create vcluster --file create-vcluster.yaml

Output:

14:14:05 info Creating virtual cluster my-vcluster-name in devspace my-devspace-name with template vcluster...
14:14:55 done Successfully created the virtual cluster my-vcluster-name in devspace my-devspace-name
14:14:55 done Successfully updated kube context to use virtual cluster my-vcluster-name in devspace my-devspace-name

List the vClusters #

kosmos list vclusters --devspace my-devspace-name

Retrieve vCluster information #

Retrieve information about the vCluster that you just created:

kosmos get vcluster --name my-vcluster-name --devspace my-devspace-name

kosmos get vcluster --name my-vcluster-name --devspace my-devspace-name -o yaml

Output:

metadata:
  creationTimestamp: "2025-02-06T22:14:05Z"
  finalizers:
  - virtualclusterinstance.storage.kosmos.spcplatform.com/finalizer
  generation: 1
  name: my-vcluster-name
  namespace: loft-p-my-devspace-name
  resourceVersion: "965214363"
  uid: 0f9b8472-b8ad-481f-9f01-b4f5c0f85e0d
spec:
  clusterRef:
    cluster: dx-sandbox-stg-eks
    namespace: loft-my-devspace-name-v-my-vcluster-name
    virtualCluster: my-vcluster-name
  description: This vCluster is created using CLI.
  displayName: my-vcluster-name
  extraAccessRules:
  - clusterRole: cluster-admin
    users:
    - khangnguyen
    - khanguyenmsxv
  owner:
    user: khangnguyen
  templateRef:
    name: vcluster
    version: 0.21.2
status:
  conditions:
  - lastTransitionTime: "2025-02-06T22:14:54Z"
    status: "True"
    type: Ready
  - lastTransitionTime: "2025-02-06T22:14:05Z"
    status: "True"
    type: Scheduled
  - lastTransitionTime: "2025-02-06T22:14:08Z"
    status: "True"
    type: SpaceReady
  - lastTransitionTime: "2025-02-06T22:14:08Z"
    status: "True"
    type: SpaceSynced
  - lastTransitionTime: "2025-02-06T22:14:05Z"
    status: "True"
    type: TemplateResolved
  - lastTransitionTime: "2025-02-06T22:14:05Z"
    status: "True"
    type: TemplateSynced
  - lastTransitionTime: "2025-02-06T22:14:54Z"
    status: "True"
    type: VirtualClusterAppsAndObjectsSynced
  - lastTransitionTime: "2025-02-06T22:14:16Z"
    status: "True"
    type: VirtualClusterDeployed
  - lastTransitionTime: "2025-02-06T22:14:53Z"
    status: "True"
    type: VirtualClusterOnline
  - lastTransitionTime: "2025-02-06T22:14:54Z"
    status: "True"
    type: VirtualClusterReady
  - lastTransitionTime: "2025-02-06T22:14:54Z"
    status: "True"
    type: VirtualClusterSynced
  phase: Ready
  sleepModeConfig:
    metadata:
      creationTimestamp: null
    spec: {}
    status: {}

Use vCluster #

After the vCluster is created, you can use “kubectl” to validate its functionality by switching your current kubectl context to point to the specified virtual cluster.

kosmos use vcluster my-vcluster-name

Output:

15:03:01 done Successfully updated kube context to use virtual cluster my-vcluster-name in devspace

Note: Any kubectl command you run will now operate inside the virtual cluster, not the host (physical).

kubectl get ns

Output:

NAME              STATUS   AGE
default           Active   78s
kube-node-lease   Active   78s
kube-public       Active   78s
kube-system       Active   78s

Delete the vCluster #

kosmos delete vcluster my-vcluster-name --devspace my-devspace-name

Output:

14:26:24 done Successfully deleted virtual cluster my-vcluster-name in devspace my-devspace-name
14:26:24 done Successfully deleted kube context for virtual cluster my-vcluster-name

Edit this page on GitHub