Skip to main content
Version: v0.27 Stable

Deploy with isolated vCluster control plane

Limited vCluster Tenancy Configuration Support

This feature is only available when using the following worker node types:

  • Host Nodes
    • Enterprise-Only Feature

    This feature is an Enterprise feature. See our pricing plans or contact our sales team for more information.

    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 the 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

    All of the deployment options below have the following assumptions:

    • A vcluster.yaml is provided. Refer to the vcluster.yaml reference docs to explore all configuration options. This file is optional and can be removed from the examples.
    • The vCluster is called my-vcluster.
    • The vCluster is be deployed into the team-x namespace.

    The vCluster CLI provides the most straightforward way to deploy and manage virtual clusters.

    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:

      Modify the following with your specific values to generate a copyable command:
      vcluster create my-vcluster --namespace team-x --values vcluster.yaml
      note

      After installation, vCluster automatically switches your Kubernetes context to the new virtual cluster. You can now run kubectl commands against the 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.

    All of the deployment options below have the following assumptions:

    • A vcluster.yaml is provided. Refer to the vcluster.yaml reference docs to explore all configuration options. This file is optional and can be removed from the examples.
    • The vCluster is called my-vcluster.
    • The vCluster is be deployed into the team-x namespace.

    The vCluster CLI provides the most straightforward way to deploy and manage virtual clusters.

    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:

      Modify the following with your specific values to generate a copyable command:
      vcluster create my-vcluster --namespace team-x --values vcluster.yaml
      note

      After installation, vCluster automatically switches your Kubernetes context to the new virtual cluster. You can now run kubectl commands against the virtual cluster.

    Test 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.