Skip to main content
Version: main 🚧

Deploy with Isolated vCluster Control Plane


Pro Feature

This feature is available in the vCluster Pro tier. Contact us for more details and to start a trial.

vCluster creates isolated Kubernetes environments by deploying a virtual cluster that contains its own dedicated virtual control plane. This control plane orchestrates operations within the virtual cluster and facilitates interaction with the underlying host cluster. The virtual control plane is deployed as a single pod managed as a StatefulSet (default) or Deployment. By default, any workloads from a virtual cluster are deployed in the same namespace of a host cluster.

If you don't want to have your workloads running in the same namespace of the same host cluster, you can enable our isolated control plane feature, which allows you to run a vCluster control plane pod in one host cluster while a separate, headless vCluster runs workloads in another cluster. A headless vcluster is a vCluster without a control plane pod.

Separation of management and workload execution is often critical for security, management, or operational reasons.

Name of the Virtual Clusters

The release names in both clusters must be the same to ensure that the vCluster can properly sync across them. In this example, they are both called my-vcluster.

Part 1: Set up the Headless vCluster​

Create a Headless vCluster​

On the host cluster that will run the workloads, create a Headless vCluster with the following vcluster.yaml.

experimental:
  isolatedControlPlane:
    headless: true

  1. Install the vCluster CLI.

     brew install loft-sh/tap/vcluster-experimental

    If you installed the CLI using brew install vcluster, you should brew uninstall vcluster and then install the experimental version. The binaries in the tap are signed using the Sigstore framework for enhanced security.

    Confirm that you've installed the correct version of the vCluster CLI.

    vcluster --version

  2. Deploy vCluster.

    vcluster create my-vcluster --namespace team-x --values vcluster.yaml

    When the installation finishes, you are automatically connected to the virtual cluster. You Kubernetes context is updated to point to your new virtual cluster. You can run local kubectl commands for the new virtual cluster.

Obtain the kubeconfig of the Headless vCluster​

On the host cluster, you must obtain the kubeconfig of the Headless vCluster. This will be used to allow the control plane vCluster to communicate with it.

export WORKLOAD_KUBECONFIG=$(kubectl config view --raw -o json | TOKEN=$(kubectl create token vc-my-vcluster \
  -n team-x \
  --duration=48h \
) jq '."current-context" as $current | (.contexts[] | select(.name == $current)) as $context | {
  "current-context": ."current-context",
  "kind": ."kind",
  "apiVersion": ."apiVersion",
  "contexts": [$context],
  "clusters": [.clusters[] | select(.name == $context.context.cluster) | del(.cluster."certificate-authority-data") | .cluster."insecure-skip-tls-verify" = true],
  "users": [.users[] | select(.name == $context.context.user) | del(.user."client-certificate-data") | del(.user."client-key-data") | .user.token = $ENV.TOKEN]
}' | yq -P)
Kube Context

Confirm that your kube context is set to the host cluster and not the newly created Headless vCluster. If you used the vCluster CLI, use vcluster disconnect to be set back to your previous kube context.

Part 2: Set Up the Control Plane vCluster​

Switch to the kube context of the other Host​

Now, switch to the kube context of the host where the control plane will be deployed:

kubectl config use-context CONTEXT_NAME

Create the Namespace for the Control Plane​

Create a namespace in your cluster that will host the control plane vCluster:

kubectl create namespace vc-control-plane

Configure Kubeconfig Secret​

Using the kubeconfig obtained from the headless vCluster setup, create a Kubernetes secret in the control plane namespace.

kubectl create secret generic vc-remote-workloads-kubeconfig \
  --namespace vc-control-plane \
  --from-literal=kubeconfig=$WORKLOAD_KUBECONFIG

Optional: Configure Platform Kubeconfig Secret​

If you won't activate your vCluster through other means, you can manually activate it to ensure it is fully operational. This step is essential if you're setting up the vCluster for the first time or have yet to be automatically activated during deployment (by e.g. the CLI or platform section). Perform this step in the Kubernetes context of your control plane cluster:

kubectl create secret generic vcluster-platform-api-key \
  --namespace vc-control-plane \
  --from-literal=accessKey=$ACCESS_KEY \
  --from-literal=host=$PLATFORM_HOST
info

You can also specify the project via project key, if the platform is insecure via insecure and the virtual cluster name in the platform via name.

This command activates the my-vcluster vCluster in the vc-control-plane namespace.

Create the Control Plane vCluster​

Set up the control plane vCluster using the following vcluster.yaml.

experimental:
  isolatedControlPlane:
    enabled: true
    namespace: "team-x"
    service: "my-vcluster"
    kubeConfig: "/worker-cluster/kubeconfig.yaml"

controlPlane:
  statefulSet:
    persistence:
      addVolumes:
        - name: workload-kubeconfig
          secret:
            secretName: vc-remote-workloads-kubeconfig
            items:
              - key: kubeconfig
                path: kubeconfig.yaml
      addVolumeMounts:
        - mountPath: /worker-cluster
          name: workload-kubeconfig
          readOnly: true
  service:
    spec:
      type: LoadBalancer

networking:
  advanced:
    proxyKubelets:
      byHostname: false
      byIP: false

Setting up the control plane without Load Balancer support

By default vCluster starts a LoadBalancer type Service to serve API. In some environments like local development clusters or bare metal clusters you might want to use NodePort type instead. In order to do this, include this configuration in your vcluster.yaml file.

controlPlane:
  service:
    spec:
      type: NodePort
    httpsNodePort: 30999

On the host cluster that will run the control, create a control plane vCluster.

  1. Install the vCluster CLI.

     brew install loft-sh/tap/vcluster-experimental

    If you installed the CLI using brew install vcluster, you should brew uninstall vcluster and then install the experimental version. The binaries in the tap are signed using the Sigstore framework for enhanced security.

    Confirm that you've installed the correct version of the vCluster CLI.

    vcluster --version

  2. Deploy vCluster.

    vcluster create my-vcluster --namespace team-x --values vcluster.yaml

    When the installation finishes, you are automatically connected to the virtual cluster. You Kubernetes context is updated to point to your new virtual cluster. You can run local kubectl commands for the new virtual cluster.

Testing out the Isolated Control Plane​

In the kube context of the control plane vCluster, try deploying an application and see that the pods only run in the host cluster of the headless vCluster and not in the control plane vCluster.