Skip to main content

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.

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.