Annotations and labels reference
This page documents the well-known annotations and labels in the vcluster.loft.sh namespace used by vCluster for resource synchronization between virtual and host clusters.
Sync identification labels​
These labels identify synced resources and their relationship to the vCluster.
vcluster.loft.sh/name​
Type: Label
Example: vcluster.loft.sh/name: "my-vcluster"
Used on: All synced resources
Identifies the name of the vCluster that owns or synced this resource.
vcluster.loft.sh/namespace​
Type: Label
Example: vcluster.loft.sh/namespace: "vcluster-my-vcluster"
Used on: All synced resources
Identifies the namespace where the vCluster is deployed in the host cluster.
vcluster.loft.sh/managed-by​
Type: Label
Example: vcluster.loft.sh/managed-by: "vcluster"
Used on: Synced resources
Indicates that this resource is managed by vCluster and should not be modified directly.
Sync control annotations​
These annotations control how vCluster syncs resources between the virtual and host clusters.
vcluster.loft.sh/force-sync​
Type: Annotation
Example: vcluster.loft.sh/force-sync: "true"
Used on: Any resource
Forces vCluster to sync this resource from the host cluster to the virtual cluster, even if it would normally be excluded by sync configuration.
vcluster.loft.sh/skip-translate​
Type: Annotation
Example: vcluster.loft.sh/skip-translate: "true"
Used on: Any resource
Prevents vCluster from translating (name-mangling) this resource when syncing. The resource retains its original name in the host cluster.
vcluster.loft.sh/skip-backsync​
Type: Annotation
Example: vcluster.loft.sh/skip-backsync: "true"
Used on: Synced resources
Prevents changes to this resource in the host cluster from being synced back to the virtual cluster.
vcluster.loft.sh/import​
Type: Annotation
Example: vcluster.loft.sh/import: "true"
Used on: Resources in host cluster
Marks a resource in the host cluster for import into the vCluster. The resource is synced into the virtual cluster.
Internal annotations​
These annotations are used internally by vCluster for sync tracking. They should not be modified manually.
vcluster.loft.sh/object-name​
Type: Annotation (internal)
Used on: Synced resources
Stores the original name of the resource in the virtual cluster.
vcluster.loft.sh/object-namespace​
Type: Annotation (internal)
Used on: Synced resources
Stores the original namespace of the resource in the virtual cluster.
vcluster.loft.sh/object-uid​
Type: Annotation (internal)
Used on: Synced resources
Stores the UID of the resource in the virtual cluster.
vcluster.loft.sh/object-kind​
Type: Annotation (internal)
Used on: Synced resources
Stores the Kind of the resource in the virtual cluster.
vcluster.loft.sh/object-host-name​
Type: Annotation (internal)
Used on: Synced resources
Stores the translated name of the resource in the host cluster.
vcluster.loft.sh/object-host-namespace​
Type: Annotation (internal)
Used on: Synced resources
Stores the namespace of the resource in the host cluster.
vcluster.loft.sh/object-imported​
Type: Annotation (internal)
Used on: Imported resources
Marks a resource as imported from the host cluster.
vcluster.loft.sh/service-cidr​
Type: Annotation (internal)
Used on: vCluster configuration
Stores the service CIDR used by the vCluster.
vcluster.loft.sh/created​
Type: Annotation (internal)
Used on: Helm releases
Indicates that this release was created by the vCluster CLI.
vcluster.loft.sh/distro​
Type: Label (internal)
Used on: vCluster pods
Identifies the Kubernetes distribution running inside the vCluster (k3s, k8s, k0s, eks).
vcluster.loft.sh/belongs-to​
Type: Label
Example: vcluster.loft.sh/belongs-to: "my-vcluster"
Used on: Service resources
Identifies which vCluster the node service belongs to when there are multiple vClusters in one namespace.
vcluster.loft.sh/node​
Type: Label
Example: vcluster.loft.sh/node: "node-1"
Used on: Service resources
Specifies which node this service represents in the vCluster.
vcluster.loft.sh/restore-request​
Type: Label
Example: vcluster.loft.sh/restore-request: "true"
Used on: ConfigMap resources
Labels ConfigMaps as restore requests for vCluster snapshot restoration.
vcluster.loft.sh/snapshot-request​
Type: Label
Example: vcluster.loft.sh/snapshot-request: "true"
Used on: ConfigMap resources
Labels ConfigMaps as snapshot requests for vCluster state capture.
Platform integration​
These annotations are used when vCluster is managed by vCluster Platform.
loft.sh/custom-links​
Type: Annotation
Example: loft.sh/custom-links: "https://docs.example.com\nhttps://dashboard.example.com"
Used on: Cluster resources
Enumerates associated links to external websites. Multiple URLs can be specified using newline separators.
loft.sh/direct-cluster-endpoint​
Type: Annotation
Example: loft.sh/direct-cluster-endpoint: "https://cluster.example.com:6443"
Used on: Cluster resources
Tells the Loft CLI to use this endpoint instead of the default Loft server address to connect to this cluster.
loft.sh/direct-cluster-endpoint-insecure​
Type: Annotation
Example: loft.sh/direct-cluster-endpoint-insecure: "true"
Used on: Cluster resources
Specifies whether to use an insecure connection when connecting to the cluster endpoint.