Skip to main content
API Reference

vCluster

note

A vCluster control plane runs with fixed resources and does not scale with cluster size. Unlike standard NKE clusters, where control-plane nodes can be scaled to handle higher load, vClusters are not recommended for large clusters or workloads with a high number of Kubernetes objects (such as many Pods, CRDs, or operators) and heavy API server traffic.

A vCluster is a virtual Kubernetes cluster built on vCluster that runs on top of Nine Kubernetes Engine (NKE). It uses the same underlying compute, storage, and networking infrastructure as a standard NKE cluster, with dedicated worker nodes, but runs a virtualized control plane instead of dedicated high-availability control-plane nodes.

Because vClusters have no base cluster fee and provision in under two minutes, they provide a cost-effective alternative to standard NKE clusters for non-production workloads, with trade-offs in availability guarantees (SLA), automatic backups, and managed add-ons.

Use Cases​

  • CI/CD pipelines: Fast creation and deletion times combined with low cost make vClusters well suited for running end-to-end deployment tests in CI/CD pipelines.
  • Testing new Kubernetes API versions: Nine provides the latest Kubernetes releases in vCluster early, so you can test your applications against new API versions before upgrading production clusters.
  • Isolated development and staging environments: Run separate vClusters for development and staging to achieve stronger isolation than sharing multiple namespaces on a single NKE cluster, while granted full cluster-admin permissions.

Feature Comparison​

The following table compares standard NKE clusters and vClusters:

FeatureNKEvCluster
Service type LoadBalancer✓✓
Persistent storage (RWO/RWX)✓✓
Ingress✓✓
Autoscaling✓✓
Argo CD integration✓✓
Static Egress✓✓
Service Connections✓✓
NKE machine types✓✓
Dedicated worker nodes✓✓
Dedicated, scalable HA control plane✓✗
Managed cluster add-ons✓✗
Automatic backups✓✗
Uptime guarantees (SLA)✓✗
Base cluster fee✓✗
Fast creation time (< 2 minutes)✗✓
Full cluster-admin✗✓

Getting Started​

You can create a vCluster using Cockpit or nctl.

  1. Log in to Cockpit.
  2. Select Managed Kubernetes from the product overview.
  3. Click Add Cluster and select the vcluster option.

To configure kubectl access to your cluster, see Cluster Login. For details on available locations, machine types, load balancing, and persistent storage, see the Nine Kubernetes Engine (NKE) overview.

Argo CD​

When you deploy applications to a vCluster using Argo CD, annotating a namespace with nine.ch/argo-admin="true" (as described in Argo CD Namespace Creation) does not automatically grant permissions. Because vClusters are not fully managed clusters, you must manually grant permissions to the Argo CD ServiceAccount.

To grant Argo CD cluster-admin permissions on your vCluster, complete the following steps:

  1. Find the name of the Argo CD ServiceAccount in the default namespace:

    kubectl get serviceaccounts -n default

    Note the service account name starting with argocd- (for example, argocd-xyz).

  2. Create a ClusterRoleBinding manifest named argocd-clusterrolebinding.yaml and replace <ARGOCD_SERVICE_ACCOUNT> with the service account name from the previous step:

    argocd-clusterrolebinding.yaml
    apiVersion: rbac.authorization.k8s.io/v1
    kind: ClusterRoleBinding
    metadata:
      name: argocd
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: cluster-admin
    subjects:
      - kind: ServiceAccount
        name: <ARGOCD_SERVICE_ACCOUNT>
        namespace: default

  3. Apply the manifest to your vCluster:

    kubectl apply -f argocd-clusterrolebinding.yaml

Ingress​

vCluster reuses the Ingress controller of the underlying host cluster, so you do not need to deploy a separate Ingress controller inside your vCluster.

You can find the predefined IngressClass and Host in the cluster details in Cockpit or in the API status under status.atProvider.vcluster.defaultIngress. Using the host IngressClass also enables automatic Let's Encrypt TLS certificates. For configuration details, see Ingress Usage.

Installing a Custom Ingress Controller​

If you do not want to use the predefined host Ingress controller, you can deploy a custom Ingress controller inside your vCluster. Configure your custom controller with a distinct IngressClass name so that it does not conflict with the predefined IngressClass.

Metrics Server​

metrics-server is not installed by default in a vCluster. Consequently, commands such as kubectl top and CPU- or memory-based Horizontal Pod Autoscalers (HPA) do not work out of the box (see Autoscaling Your NKE Workload).

Because you have full cluster-admin permissions within your vCluster, you can install and configure metrics-server yourself by following the official Metrics Server installation guide.