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 tenant and control plane 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 control plane 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 tenant and control plane 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 control plane cluster to the tenant 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 control plane 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 control plane cluster from being synced back to the tenant cluster.

vcluster.loft.sh/import​

Type: Annotation

Example: vcluster.loft.sh/import: "true"

Used on: Resources in control plane cluster

Marks a resource in the control plane cluster for import into the vCluster. The resource is synced into the tenant cluster.

vcluster.loft.sh/preserve-host-rule​

Type: Annotation

Example: vcluster.loft.sh/preserve-host-rule: "mirror-rule"

Used on: HTTPRoute resources

Names a host HTTPRoute rule that vCluster should preserve when syncing the HTTPRoute between tenant and control plane clusters.

vcluster.loft.sh/preserve-request-mirror-filters​

Type: Annotation

Example: vcluster.loft.sh/preserve-request-mirror-filters: "true"

Used on: HTTPRoute resources

Keeps host-added HTTPRoute RequestMirror filters when syncing the HTTPRoute from the control plane cluster to the tenant 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 tenant cluster.

vcluster.loft.sh/object-namespace​

Type: Annotation (internal)

Used on: Synced resources

Stores the original namespace of the resource in the tenant cluster.

vcluster.loft.sh/object-uid​

Type: Annotation (internal)

Used on: Synced resources

Stores the UID of the resource in the tenant cluster.

vcluster.loft.sh/object-kind​

Type: Annotation (internal)

Used on: Synced resources

Stores the Kind of the resource in the tenant cluster.

vcluster.loft.sh/object-host-name​

Type: Annotation (internal)

Used on: Synced resources

Stores the translated name of the resource in the control plane cluster.

vcluster.loft.sh/object-host-namespace​

Type: Annotation (internal)

Used on: Synced resources

Stores the namespace of the resource in the control plane cluster.

vcluster.loft.sh/object-imported​

Type: Annotation (internal)

Used on: Imported resources

Marks a resource as imported from the control plane 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 (k8s).

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 vCluster CLI to use this endpoint instead of the default platform 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.