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.
vcluster.loft.sh/protected​
Type: Label
Example: vcluster.loft.sh/protected: "apiservice"
Used on: Service and Endpoint resources backing APIServices
Identifies APIService backend resources that should be protected from deletion by ValidatingAdmissionPolicy. The label value names the feature owning the resource for scoped policy bindings.
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.