Virtual Clusters

A virtual cluster is a fully functional Kubernetes cluster that runs inside the namespace of another Kubernetes cluster (host cluster). Virtual clusters are very useful if you are hitting the limits of namespaces and do not want to make special exceptions to the multi-tenancy configuration of the underlying cluster, e.g. a user needs their own CRD or user needs pods from 2 namespaces to communicate with each other but your standard NetworkPolicy does not allow this, then a virtual cluster may be perfect for this user.

Working with Virtual Clusters

Unlike "real" clusters, virtual clusters are much more lightweight and much faster to spin up and tear down again.

Create Virtual Clusters

UI

1. Go to the Virtual Clusters view using the menu on the left
2. Click on the button
3. Use the field Display Name to define the name of this virtual cluster and optionally specify other settings
4. Click on the button at the very bottom

5. Retrieve a kube-context for this virtual cluster using Loft CLI:

   loft use vcluster [vcluster-name]

CLI

To create a virtual cluster using Loft CLI, run:

loft create vcluster [vcluster-name]

Kube-Context

Running loft create vcluster will automatically add a kube-context to your kube-config file, so you can immediately run kubectl commands right after creating a virtual cluster.

kubectl

1. If you do not have a kube-context for the cluster where this space should be created in, you can set up a kube-context using:

   loft use cluster [cluster-name]

2. Create a file named vcluster.yaml with the following content:

   apiVersion: cluster.loft.sh/v1
   kind: VirtualCluster
   metadata:
     name: vcluster-name             # Set the name for your virtual cluster here
     namespace: vc-host-namespace    # Host namespace for the virtual cluster

3. Create the virtual cluster using kubectl:

   kubectl apply -f vcluster.yaml

4. Retrieve a kube-context for this virtual cluster using Loft CLI:

   loft use vcluster [vcluster-name]

Delete Virtual Clusters

UI

1. In the Virtual Clusters view, hover over the row of the virtual cluster that you want to delete.
2. While hovering over the row, you will see buttons appear on the right in the Actions column
3. Click on the button to Delete the virtual cluster

CLI

loft delete vcluster [vcluster-name]

Kube-Context

Deleting virtual clusters with Loft CLI has the advantage that Loft CLI will also delete the kube-context for this virtual cluster from your local kube-config file to keep everything cleaned up.

kubectl

1. If you do not have a kube-context for the cluster where this virtual cluster is located in, you can set up a kube-context using:

   loft use cluster [cluster-name]

2. Delete the virtual cluster using kubectl:

   kubectl delete vcluster [vcluster-name]
   
   # Alternatives:
   # 1) kubectl delete space [host-namespace]    # Delete the host namespace
   # 2) kubectl delete -f vcluster.yaml

List Virtual Clusters

UI

To see a list of virtual clusters, go to the Virtual Clusters view using the main menu on the left.

CLI

Run this command using Loft CLI to get a list of all virtual clusters you have access to across all clusters:

loft list vclusters

Kube-Context

If you want to retrieve a kube-context for any of your virtual clusters, run:

loft use vcluster [vcluster-name]

kubectl

1. If you do not have a kube-context for the space (host namespace) where you want to list virtual clusters in, you can set up a kube-context using:

   loft use space [space-name]

2. Run this kubectl command to get a list of virtual clusters in this namespace:

   kubectl get virtualclusters

Control Access To Virtual Cluster

UI

1. In the Virtual Clusters view, hover over virtual cluster that you want to give someone access to
2. While hovering over the row, you will see buttons appear on the right in the Actions column
3. Click on the button to Edit the virtual cluster
4. In the drawer that appears on the right, expand the Access To Virtual Cluster section
5. Use the Who should have access to this Virtual Cluster? field to select all Users/Teams who should get access to this virtual cluster

6. OPTIONAL: To change the access of any of the selected users or team to this virtual cluster, expand the Edit Roles For Users & Teams section and use the selectors to change the vcluster Admin role to another appropriate role for each user or team if needed

7. On the very bottom, click on the button to save the changes

CLI

To give someone access to a virtual cluster using Loft CLI, run:

loft share vcluster [optional:name]

Configuration

Virtual Cluster Template

JSONPath in VirtualCluster CRD:

 metadata.annotations["loft.sh/virtual-cluster-template"] (type: string)

Metadata

Name

JSONPath in VirtualCluster CRD:

 metadata.name (type: string)

Namespace

JSONPath in VirtualCluster CRD:

 metadata.namespace (type: string)

Labels

JSONPath in VirtualCluster CRD:

 metadata.labels (type: map[string]string)

Annotations

JSONPath in VirtualCluster CRD:

 metadata.annotations (type: map[string]string)

Advanced Options

Version

JSONPath in VirtualCluster CRD:

 spec.helmRelease.chart.version (type: string)

Helm Values

JSONPath in VirtualCluster CRD:

 spec.helmRelease.values (type: {})

Apps

Namespaces For Apps

Access To Virtual Cluster

JSONPath in VirtualCluster CRD:

 spec.access (type: Access[])

CRDs

VirtualCluster

apiVersion	string APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
kind	string Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
	object (io.k8s.apimachinery.pkg.apis.meta.v1.ObjectMeta) ObjectMeta is metadata that all persisted resources must have, which includes all objects users must create.
	object (com.github.loft-sh.agentapi.pkg.apis.loft.cluster.v1.VirtualClusterSpec)
	object (com.github.loft-sh.agentapi.pkg.apis.loft.cluster.v1.VirtualClusterStatus)

{

• "apiVersion": "string",
• "kind": "string",
• "metadata": {

  • "annotations": {

    • "property1": "string",
    • "property2": "string"

    },
  • "clusterName": "string",
  • "creationTimestamp": "2019-08-24T14:15:22Z",
  • "deletionGracePeriodSeconds": 0,
  • "deletionTimestamp": "2019-08-24T14:15:22Z",
  • "finalizers": [

    • "string"

    ],
  • "generateName": "string",
  • "generation": 0,
  • "labels": {

    • "property1": "string",
    • "property2": "string"

    },
  • "managedFields": [

    • {

      • "apiVersion": "string",
      • "fieldsType": "string",
      • "fieldsV1": { },
      • "manager": "string",
      • "operation": "string",
      • "time": "2019-08-24T14:15:22Z"

      }

    ],
  • "name": "string",
  • "namespace": "string",
  • "ownerReferences": [

    • {

      • "apiVersion": "string",
      • "blockOwnerDeletion": true,
      • "controller": true,
      • "kind": "string",
      • "name": "string",
      • "uid": "string"

      }

    ],
  • "resourceVersion": "string",
  • "selfLink": "string",
  • "uid": "string"

  },
• "spec": {

  • "helmRelease": {

    • "chart": {

      • "name": "string",
      • "repo": "string",
      • "version": "string"

      },
    • "values": "string"

    },
  • "kubeConfigRef": {

    • "key": "string",
    • "secretName": "string",
    • "secretNamespace": "string"

    },
  • "pod": {

    • "podSelector": {

      • "matchExpressions": [

        • {

          • "key": "string",
          • "operator": "string",
          • "values": [

            • "string"

            ]

          }

        ],
      • "matchLabels": {

        • "property1": "string",
        • "property2": "string"

        }

      },
    • "port": 0

    }

  },
• "status": {

  • "conditions": [

    • {

      • "lastTransitionTime": "2019-08-24T14:15:22Z",
      • "message": "string",
      • "reason": "string",
      • "severity": "string",
      • "status": "string",
      • "type": "string"

      }

    ],
  • "controlPlaneReady": true,
  • "helmRelease": {

    • "lastTransitionTime": "2019-08-24T14:15:22Z",
    • "message": "string",
    • "phase": "string",
    • "reason": "string",
    • "release": {

      • "chart": {

        • "name": "string",
        • "repo": "string",
        • "version": "string"

        },
      • "values": "string"

      }

    },
  • "message": "string",
  • "observedGeneration": 0,
  • "phase": "string",
  • "reason": "string",
  • "sleepModeConfig": {

    • "apiVersion": "string",
    • "kind": "string",
    • "metadata": {

      • "annotations": {

        • "property1": "string",
        • "property2": "string"

        },
      • "clusterName": "string",
      • "creationTimestamp": "2019-08-24T14:15:22Z",
      • "deletionGracePeriodSeconds": 0,
      • "deletionTimestamp": "2019-08-24T14:15:22Z",
      • "finalizers": [

        • "string"

        ],
      • "generateName": "string",
      • "generation": 0,
      • "labels": {

        • "property1": "string",
        • "property2": "string"

        },
      • "managedFields": [

        • {

          • "apiVersion": "string",
          • "fieldsType": "string",
          • "fieldsV1": { },
          • "manager": "string",
          • "operation": "string",
          • "time": "2019-08-24T14:15:22Z"

          }

        ],
      • "name": "string",
      • "namespace": "string",
      • "ownerReferences": [

        • {

          • "apiVersion": "string",
          • "blockOwnerDeletion": true,
          • "controller": true,
          • "kind": "string",
          • "name": "string",
          • "uid": "string"

          }

        ],
      • "resourceVersion": "string",
      • "selfLink": "string",
      • "uid": "string"

      },
    • "spec": {

      • "deleteAfter": 0,
      • "deleteAllPods": true,
      • "forceSleep": true,
      • "forceSleepDuration": 0,
      • "sleepAfter": 0,
      • "sleepSchedule": "string",
      • "timezone": "string",
      • "wakeupSchedule": "string"

      },
    • "status": {

      • "currentEpoch": {

        • "slept": 0,
        • "start": 0

        },
      • "lastActivity": 0,
      • "lastActivityInfo": {

        • "apiGroup": "string",
        • "name": "string",
        • "resource": "string",
        • "subject": "string",
        • "subresource": "string",
        • "verb": "string",
        • "virtualCluster": "string"

        },
      • "lastEpoch": {

        • "slept": 0,
        • "start": 0

        },
      • "scheduledSleep": 0,
      • "scheduledWakeup": 0,
      • "sleepType": "string",
      • "sleepingSince": 0,
      • "sleptLastSevenDays": 0,
      • "sleptLastThirtyDays": 0

      }

    }

  }

}