Skip to main content
The vCluster provider syncs virtual Kubernetes clusters created with vCluster into Ctrlplane’s inventory.

​
Prerequisites

  • ctrlc CLI installed
  • Access to the host Kubernetes cluster running vClusters
  • Ctrlplane API key

​
Basic Usage

# Sync all vClusters from the host cluster
ctrlc sync vcluster \
  --cluster-identifier host-cluster-id

# Continuous sync
ctrlc sync vcluster \
  --cluster-identifier host-cluster-id \
  --interval 5m

​
Options

FlagDescriptionRequired
--cluster-identifierIdentifier of the host cluster (or CLUSTER_IDENTIFIER env var)Yes
--providerResource provider nameNo
--intervalSync interval (e.g., 5m, 1h)No

​
Resource Metadata

Each vCluster is synced with metadata: 
identifier: host-cluster/vcluster/dev-team-cluster
name: dev-team-cluster
kind: vCluster/Cluster
metadata:
  host_cluster: host-cluster-id
  namespace: vcluster-dev-team
  release_name: dev-team-cluster
config:
  host_cluster: host-cluster-id
  namespace: vcluster-dev-team

​
Running in Kubernetes

Deploy on the host cluster: 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ctrlplane-vcluster-sync
  namespace: ctrlplane
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ctrlplane-vcluster-sync
  template:
    metadata:
      labels:
        app: ctrlplane-vcluster-sync
    spec:
      serviceAccountName: ctrlplane-sync
      containers:
        - name: sync
          image: ghcr.io/ctrlplanedev/cli:latest
          command:
            - ctrlc
            - sync
            - vcluster
            - --cluster-identifier
            - "$(CLUSTER_IDENTIFIER)"
            - --interval
            - "5m"
          env:
            - name: CTRLPLANE_API_KEY
              valueFrom:
                secretKeyRef:
                  name: ctrlplane-credentials
                  key: api-key
            - name: CTRLPLANE_WORKSPACE
              value: your-workspace-id
            - name: CLUSTER_IDENTIFIER
              value: host-cluster-id
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: ctrlplane-sync
  namespace: ctrlplane
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: ctrlplane-vcluster-sync
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: view
subjects:
  - kind: ServiceAccount
    name: ctrlplane-sync
    namespace: ctrlplane

​
Use Case: Development Environments

vClusters are ideal for dynamic development environments: 
# All vClusters as dev environments
type: Environment
name: Development vClusters
resourceSelector: |
  resource.kind == "vCluster/Cluster"

# Team-specific vClusters
type: Environment
name: Backend Team Dev
resourceSelector: |
  resource.kind == "vCluster/Cluster" &&
  resource.metadata["namespace"].startsWith("vcluster-backend-")

​
Best Practices

​
Use Namespace Conventions

Name vCluster namespaces consistently for easy targeting: 
# Pattern: vcluster-{team}-{purpose}
vcluster-backend-dev
vcluster-frontend-preview
vcluster-data-staging

​
Combine with Host Cluster Sync

Sync both the host cluster and vClusters: 
# Host cluster resources
ctrlc sync kubernetes \
  --cluster-identifier host-cluster \
  --interval 5m &

# vClusters
ctrlc sync vcluster \
  --cluster-identifier host-cluster \
  --interval 5m &

​
Next Steps

Kubernetes Provider

Sync Kubernetes resources

Dynamic Environments

Create environments for vClusters