Platform annotations and labels reference
This page documents the well-known annotations and labels in the loft.sh namespace used by vCluster Platform for managing clusters, projects, spaces, users, teams, and integrations.
Cluster management​
These annotations configure connected clusters in vCluster Platform.
loft.sh/cluster-uid​
Type: Annotation
Example: loft.sh/cluster-uid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Used on: Cluster
Set by: Platform
The unique identifier assigned to this cluster by vCluster Platform. Used internally for cluster identification and correlation.
loft.sh/cluster-name​
Type: Annotation
Example: loft.sh/cluster-name: "production-east"
Used on: NetworkPeer, Agent resources
Set by: Platform
Identifies the cluster name for network peer and agent resources.
loft.sh/display-name​
Type: Annotation
Example: loft.sh/display-name: "Production East US"
Used on: Cluster, Project, Team, User
Set by: User-configurable
A human-readable display name shown in the platform UI. Can be different from the resource's actual name.
loft.sh/ingress-suffix​
Type: Annotation
Example: loft.sh/ingress-suffix: "vclusters.example.com"
Used on: Cluster
Set by: User-configurable
Sets the domain suffix for vCluster ingress access points on this cluster. Required for external vCluster access.
loft.sh/cluster-domain​
Type: Annotation
Example: loft.sh/cluster-domain: "cluster.local"
Used on: Cluster
Set by: User-configurable
Specifies the cluster's internal DNS domain. Defaults to cluster.local.
loft.sh/cluster-domain-target​
Type: Annotation
Example: loft.sh/cluster-domain-target: "192.168.1.100"
Used on: Cluster
Set by: User-configurable
Specifies the target address for cluster domain resolution.
loft.sh/direct-cluster-endpoint​
Type: Annotation
Example: loft.sh/direct-cluster-endpoint: "https://cluster.example.com:6443"
Used on: Cluster
Set by: User-configurable
Specifies a direct endpoint for the cluster, enabling clients to connect directly instead of routing through the platform.
loft.sh/direct-cluster-endpoint-insecure​
Type: Annotation
Example: loft.sh/direct-cluster-endpoint-insecure: "true"
Used on: Cluster
Set by: User-configurable
When true, allows insecure TLS connections to the regional cluster endpoint.
loft.sh/derp-endpoint​
Type: Annotation
Example: loft.sh/derp-endpoint: "derp.example.com"
Used on: Cluster
Set by: User-configurable
Specifies a publicly accessible DERP relay endpoint for this cluster.
loft.sh/derp-endpoint-insecure​
Type: Annotation
Example: loft.sh/derp-endpoint-insecure: "true"
Used on: Cluster
Set by: User-configurable
When true, allows insecure connections to the DERP relay endpoint.
loft.sh/streaming-connection-idle-timeout​
Type: Annotation
Example: loft.sh/streaming-connection-idle-timeout: "4h"
Used on: Cluster
Set by: User-configurable
Sets the idle timeout for streaming connections (exec, port-forward, logs) to this cluster.
loft.sh/cluster-access​
Type: Annotation
Example: loft.sh/cluster-access: "direct"
Used on: Cluster
Set by: Platform
Indicates the access method configured for this cluster.
loft.sh/skip-direct-connection​
Type: Annotation
Example: loft.sh/skip-direct-connection: "true"
Used on: Cluster
Set by: User-configurable
When true, forces connections through the platform proxy even when direct connection is available.
loft.sh/cluster-role-cluster​
Type: Label
Example: loft.sh/cluster-role-cluster: "true"
Used on: ClusterRole
Set by: Platform
Marks a ClusterRole as applicable at the cluster level.
loft.sh/cluster-role-management​
Type: Label
Example: loft.sh/cluster-role-management: "true"
Used on: ClusterRole
Set by: Platform
Marks a ClusterRole as a management role for the platform.
loft.sh/account-cluster-role​
Type: Label
Example: loft.sh/account-cluster-role: "true"
Used on: ClusterRole
Set by: Platform
Marks a ClusterRole as available for account-level assignment.
loft.sh/space-cluster-role​
Type: Label
Example: loft.sh/space-cluster-role: "true"
Used on: ClusterRole
Set by: Platform
Marks a ClusterRole as available for space-level assignment.
loft.sh/cluster-account-template​
Type: Label
Example: loft.sh/cluster-account-template: "default-template"
Used on: ClusterAccountTemplate
Set by: Platform
Identifies the cluster account template.
loft.sh/account-templates-ignore-clusters​
Type: Annotation
Example: loft.sh/account-templates-ignore-clusters: "cluster1,cluster2"
Used on: User, Team
Set by: User-configurable
Comma-separated list of clusters where account templates should not be applied for this user or team.
loft.sh/agent-values​
Type: Annotation
Example: loft.sh/agent-values: '{"resources":{"limits":{"memory":"512Mi"}}}'
Used on: Cluster
Set by: User-configurable
Extra Helm values that should be applied when deploying the platform agent to this cluster.
loft.sh/cluster-ignore-agent​
Type: Annotation
Example: loft.sh/cluster-ignore-agent: "true"
Used on: Cluster
Set by: User-configurable
When true, the platform will not deploy or manage an agent on this cluster.
loft.sh/cluster-ignore-kiosk​
Type: Annotation
Example: loft.sh/cluster-ignore-kiosk: "true"
Used on: Cluster
Set by: User-configurable
When true, the platform will not deploy or manage kiosk on this cluster.
loft.sh/direct-cluster-endpoint-ca-data​
Type: Annotation
Example: loft.sh/direct-cluster-endpoint-ca-data: "LS0tLS1CRUdJTi..."
Used on: Cluster
Set by: User-configurable
Base64-encoded certificate authority data for verifying the regional cluster endpoint certificate.
Project management​
These labels and annotations are used on project resources and project-owned namespaces.
loft.sh/project​
Type: Label
Example: loft.sh/project: "team-alpha"
Used on: Namespace, VirtualClusterInstance, SpaceInstance
Set by: Platform
Identifies the vCluster Platform project that owns this resource.
loft.sh/project-namespace​
Type: Annotation
Example: loft.sh/project-namespace: "loft-p-team-alpha"
Used on: Various resources
Set by: Platform
The namespace where project resources are stored.
loft.sh/project-role​
Type: Label
Example: loft.sh/project-role: "true"
Used on: ClusterRole
Set by: User-configurable
Marks a ClusterRole as available for use as a project role. Required for ClusterRoles to appear in project member role selection.
loft.sh/project-cluster-quota​
Type: Label
Example: loft.sh/project-cluster-quota: "team-alpha-quota"
Used on: ResourceQuota
Set by: Platform
Links a ResourceQuota to a project's cluster quota.
loft.sh/project-user-cluster-quota​
Type: Label
Example: loft.sh/project-user-cluster-quota: "user-quota"
Used on: ResourceQuota
Set by: Platform
Links a ResourceQuota to a per-user quota within a project.
Space management​
These annotations and labels are used on spaces (namespaces) managed by the platform.
loft.sh/space-instance-name​
Type: Label
Example: loft.sh/space-instance-name: "dev-space"
Used on: Namespace
Set by: Platform
The name of the SpaceInstance that created this namespace.
loft.sh/space-instance-namespace​
Type: Label
Example: loft.sh/space-instance-namespace: "loft-p-default"
Used on: Namespace
Set by: Platform
The namespace containing the SpaceInstance resource.
loft.sh/space-instance-project​
Type: Label
Example: loft.sh/space-instance-project: "default"
Used on: Namespace
Set by: Platform
The project that owns the SpaceInstance.
loft.sh/owned​
Type: Label
Example: loft.sh/owned: "true"
Used on: Namespace
Set by: Platform
Indicates that this namespace is owned by a specific user or team.
loft.sh/space-constraints​
Type: Label
Example: loft.sh/space-constraints: "restricted"
Used on: Namespace
Set by: Platform
Identifies the space constraints applied to this namespace.
loft.sh/space-constraints-status​
Type: Annotation
Example: loft.sh/space-constraints-status: "applied"
Used on: Namespace
Set by: Platform
Status of space constraints application.
loft.sh/space-objects​
Type: Annotation
Example: loft.sh/space-objects: '{"configmaps":["config1"]}'
Used on: Namespace
Set by: Platform
JSON object tracking space template objects created in this namespace.
loft.sh/space-objects-status​
Type: Annotation
Example: loft.sh/space-objects-status: "synced"
Used on: Namespace
Set by: Platform
Status of space objects synchronization.
loft.sh/disable-space-creation​
Type: Annotation
Example: loft.sh/disable-space-creation: "true"
Used on: Cluster
Set by: User-configurable
When true, disables direct space creation on this cluster. Spaces must be created through projects.
vCluster instance management​
These labels and annotations are used on vCluster instances managed by the platform.
loft.sh/vcluster-instance-name​
Type: Label
Example: loft.sh/vcluster-instance-name: "dev-vcluster"
Used on: Namespace, Pod
Set by: Platform
The name of the VirtualClusterInstance that created this vCluster.
loft.sh/vcluster-instance-namespace​
Type: Label
Example: loft.sh/vcluster-instance-namespace: "loft-p-default"
Used on: Namespace, Pod
Set by: Platform
The namespace containing the VirtualClusterInstance resource.
loft.sh/vcluster-instance-project​
Type: Label
Example: loft.sh/vcluster-instance-project: "default"
Used on: Namespace, Pod
Set by: Platform
The project that owns the VirtualClusterInstance.
platform.vcluster.com/vcluster-instance-name​
Type: Label
Example: platform.vcluster.com/vcluster-instance-name: "dev-vcluster"
Used on: Resources associated with vCluster instances
Set by: Platform
The name of the virtual cluster an object is associated with.
platform.vcluster.com/vcluster-instance-namespace​
Type: Label
Example: platform.vcluster.com/vcluster-instance-namespace: "loft-p-default"
Used on: Resources associated with vCluster instances
Set by: Platform
The namespace of the virtual cluster an object is associated with.
vcluster.loft.sh/managed-by​
Type: Label
Example: vcluster.loft.sh/managed-by: "loft"
Used on: vCluster resources
Set by: Platform
Indicates that this vCluster is managed by vCluster Platform.
vcluster.loft.sh/vcluster-name​
Type: Label
Example: vcluster.loft.sh/vcluster-name: "my-vcluster"
Used on: vCluster pods and resources
Set by: Platform
The name of the vCluster.
vcluster.loft.sh/vcluster-namespace​
Type: Label
Example: vcluster.loft.sh/vcluster-namespace: "vcluster-my-vcluster"
Used on: vCluster pods and resources
Set by: Platform
The namespace where the vCluster is deployed.
vcluster.loft.sh/fake-node​
Type: Label
Example: vcluster.loft.sh/fake-node: "true"
Used on: Node
Set by: Platform
Identifies nodes that are virtual/fake nodes created by vCluster.
vcluster.loft.sh/dynamic-node-pool​
Type: Label
Example: vcluster.loft.sh/dynamic-node-pool: "default-pool"
Used on: Node
Set by: Platform
Identifies the dynamic node pool this node belongs to.
vcluster.loft.sh/control-plane-endpoint​
Type: Annotation
Example: vcluster.loft.sh/control-plane-endpoint: "https://vcluster.example.com:443"
Used on: VirtualClusterInstance
Set by: Platform
The control plane endpoint for accessing this vCluster.
vcluster.loft.sh/object-imported​
Type: Annotation
Example: vcluster.loft.sh/object-imported: "true"
Used on: Various resources
Set by: Platform
Indicates that this resource was imported into a vCluster.
loft.sh/hpm-enabled​
Type: Annotation
Example: loft.sh/hpm-enabled: "true"
Used on: VirtualClusterInstance
Set by: User-configurable
Enables the Host Path Mapper for this vCluster instance.
loft.sh/skip-helm-deploy​
Type: Annotation
Example: loft.sh/skip-helm-deploy: "true"
Used on: VirtualClusterInstance
Set by: User-configurable
Skips Helm deployment for this vCluster. Use when managing vCluster deployment externally.
loft.sh/database-vcluster​
Type: Label
Example: loft.sh/database-vcluster: "my-vcluster"
Used on: Secret
Set by: Platform
Links a database secret to a specific vCluster.
virtualcluster.loft.sh/latest-version​
Type: Annotation
Example: virtualcluster.loft.sh/latest-version: "0.20.0"
Used on: VirtualClusterInstance
Set by: Platform
Stores the latest available vCluster version for upgrade notifications.
vcluster.loft.sh/kubernetes-name​
Type: Annotation
Example: vcluster.loft.sh/kubernetes-name: "my-vcluster"
Used on: Node
Set by: Platform
Identifies the Kubernetes name associated with the vCluster node.
vcluster.loft.sh/object-namespace​
Type: Annotation
Example: vcluster.loft.sh/object-namespace: "default"
Used on: Various synced resources
Set by: Platform
Indicates the original namespace of an object synced from the vCluster to the host cluster.
Auto sleep configuration​
These annotations configure auto sleep behavior.
loft.sh/sleep-mode​
Type: Annotation
Example: loft.sh/sleep-mode: "true"
Used on: Namespace, VirtualClusterInstance
Set by: Platform
Indicates that auto sleep is enabled for this resource.
loft.sh/sleep-mode-replicas​
Type: Annotation
Example: loft.sh/sleep-mode-replicas: "3"
Used on: Deployment, StatefulSet
Set by: Platform
Stores the original replica count before auto sleep scaled down the workload.
Auto sleep annotations (sleepmode.loft.sh)​
These annotations in the sleepmode.loft.sh namespace control auto sleep behavior for namespaces and vCluster instances.
sleepmode.loft.sh/sleep-after​
Type: Annotation
Example: sleepmode.loft.sh/sleep-after: "3600"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Specifies the number of seconds of inactivity after which the namespace or vCluster should automatically sleep.
sleepmode.loft.sh/delete-after​
Type: Annotation
Example: sleepmode.loft.sh/delete-after: "86400"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Specifies the number of seconds of inactivity after which the namespace or vCluster should be automatically deleted.
sleepmode.loft.sh/sleep-schedule​
Type: Annotation
Example: sleepmode.loft.sh/sleep-schedule: "0 20 * * *"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Specifies a cron schedule for when the namespace or vCluster should automatically sleep. Uses standard cron format.
sleepmode.loft.sh/wakeup-schedule​
Type: Annotation
Example: sleepmode.loft.sh/wakeup-schedule: "0 8 * * 1-5"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Specifies a cron schedule for when the namespace or vCluster should automatically wake up.
sleepmode.loft.sh/timezone​
Type: Annotation
Example: sleepmode.loft.sh/timezone: "America/New_York"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Specifies the timezone for scheduled sleep and wakeup operations. Accepts IANA timezone names. Defaults to UTC.
sleepmode.loft.sh/force​
Type: Annotation
Example: sleepmode.loft.sh/force: "true"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Forces the namespace or vCluster to sleep immediately, regardless of activity.
sleepmode.loft.sh/force-duration​
Type: Annotation
Example: sleepmode.loft.sh/force-duration: "3600"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Forces sleep for a specific duration in seconds. After this period, normal activity tracking resumes. Set to 0 for indefinite sleep until manually woken.
sleepmode.loft.sh/exclude​
Type: Annotation
Example: sleepmode.loft.sh/exclude: "true"
Used on: Deployment, StatefulSet, ReplicaSet, Pod
Set by: User-configurable
Excludes this workload from auto sleep. When the namespace sleeps, this workload continues running.
sleepmode.loft.sh/ignore-all​
Type: Annotation
Example: sleepmode.loft.sh/ignore-all: "true"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Ignores all activity when determining whether the namespace or vCluster should sleep.
sleepmode.loft.sh/ignore-ingresses​
Type: Annotation
Example: sleepmode.loft.sh/ignore-ingresses: "true"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Ignores ingress requests when determining activity. Useful when the namespace receives automated health checks that should not prevent sleep.
sleepmode.loft.sh/ignore-groups​
Type: Annotation
Example: sleepmode.loft.sh/ignore-groups: "apps,batch"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Ignores requests to specific API groups when determining activity. Comma-separated list of API group names.
sleepmode.loft.sh/ignore-vclusters​
Type: Annotation
Example: sleepmode.loft.sh/ignore-vclusters: "true"
Used on: Namespace
Set by: User-configurable
Ignores vCluster-related requests when determining namespace activity.
sleepmode.loft.sh/ignore-resources​
Type: Annotation
Example: sleepmode.loft.sh/ignore-resources: "pods,configmaps"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Ignores requests to specific resource types when determining activity. Comma-separated list of resource names.
sleepmode.loft.sh/ignore-verbs​
Type: Annotation
Example: sleepmode.loft.sh/ignore-verbs: "get,list,watch"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Ignores requests with specific HTTP verbs when determining activity. Comma-separated list.
sleepmode.loft.sh/ignore-resource-verbs​
Type: Annotation
Example: sleepmode.loft.sh/ignore-resource-verbs: "pods.core=get list,deployments.apps=get"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Ignores specific verb combinations for specific resources. Format: resource.group=verb1 verb2, resource2.group=verb3.
sleepmode.loft.sh/ignore-resource-names​
Type: Annotation
Example: sleepmode.loft.sh/ignore-resource-names: "pods.core=monitoring-pod,configmaps.core=config1"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Ignores requests to specific named resources. Format: resource.group=name1 name2.
sleepmode.loft.sh/ignore-active-connections​
Type: Annotation
Example: sleepmode.loft.sh/ignore-active-connections: "true"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Ignores active connections (such as kubectl exec or kubectl port-forward) when determining whether to sleep. Allows sleep even with open connections.
sleepmode.loft.sh/ignore-user-agents​
Type: Annotation
Example: sleepmode.loft.sh/ignore-user-agents: "kube-probe/*,prometheus/*"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Ignores requests from specific user agents. Supports trailing wildcards. Comma-separated list.
sleepmode.loft.sh/disable-ingress-wakeup​
Type: Annotation
Example: sleepmode.loft.sh/disable-ingress-wakeup: "true"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Disables automatic wakeup from ingress traffic. When set, the namespace or vCluster remains asleep even when receiving ingress requests.
sleepmode.loft.sh/disable-metrics-tracking​
Type: Annotation
Example: sleepmode.loft.sh/disable-metrics-tracking: "true"
Used on: Namespace, VirtualClusterInstance
Set by: User-configurable
Disables metrics-based activity tracking. Only API server activity is tracked.
Auto sleep status annotations​
These annotations are set by the platform to indicate auto sleep status. They are read-only.
sleepmode.loft.sh/last-activity​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/last-activity: "1706745600"
Used on: Namespace, VirtualClusterInstance
Set by: Platform
Unix timestamp of the last detected activity. Set automatically by the platform.
sleepmode.loft.sh/sleeping-since​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/sleeping-since: "1706745600"
Used on: Namespace, VirtualClusterInstance
Set by: Platform
Unix timestamp of when the namespace or vCluster entered auto sleep. Present only when sleeping.
sleepmode.loft.sh/sleep-type​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/sleep-type: "inactivitySleep"
Used on: Namespace, VirtualClusterInstance
Set by: Platform
Indicates how sleep was triggered. Values: inactivitySleep, forcedSleep, forcedDurationSleep, scheduledSleep.
sleepmode.loft.sh/scheduled-sleep​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/scheduled-sleep: "1706832000"
Used on: Namespace, VirtualClusterInstance
Set by: Platform
Unix timestamp of the next scheduled sleep based on the sleep schedule.
sleepmode.loft.sh/scheduled-wakeup​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/scheduled-wakeup: "1706774400"
Used on: Namespace, VirtualClusterInstance
Set by: Platform
Unix timestamp of the next scheduled wakeup based on the wakeup schedule.
sleepmode.loft.sh/endpoint-slices​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/endpoint-slices: '{"endpoints":[{"addresses":["10.0.0.1"]}]}'
Used on: EndpointSlice
Set by: Platform
Stores the original endpoint slice configuration before sleep mode modifications for restoration on wakeup.
sleepmode.loft.sh/endpoints-subsets​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/endpoints-subsets: '{"addresses":[{"ip":"10.0.0.1"}]}'
Used on: Endpoints
Set by: Platform
Stores the original endpoints subsets before sleep mode modifications for restoration on wakeup.
sleepmode.loft.sh/service-selector​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/service-selector: '{"app":"nginx"}'
Used on: Service
Set by: Platform
Stores the original service selector before sleep mode modifications for restoration on wakeup.
sleepmode.loft.sh/service-ports​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/service-ports: '[{"port":80,"targetPort":8080}]'
Used on: Service
Set by: Platform
Stores the original service ports before sleep mode modifications for restoration on wakeup.
sleepmode.loft.sh/target-service-name​
Type: Annotation
Example: sleepmode.loft.sh/target-service-name: "nginx-service"
Used on: Ingress
Set by: Platform
Identifies the target service for sleep mode ingress wakeup functionality.
sleepmode.loft.sh/target-service-namespace​
Type: Annotation
Example: sleepmode.loft.sh/target-service-namespace: "production"
Used on: Ingress
Set by: Platform
Identifies the target service namespace when the service is in a different namespace than the ingress.
sleepmode.loft.sh/target-service-port​
Type: Annotation
Example: sleepmode.loft.sh/target-service-port: "8080"
Used on: Ingress
Set by: Platform
Identifies the target service port for sleep mode ingress wakeup. Can be a port name or number.
sleepmode.loft.sh/istio-virtual-service-http-routes​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/istio-virtual-service-http-routes: '[{"route":[{"destination":{"host":"nginx"}}]}]'
Used on: VirtualService (Istio)
Set by: Platform
Stores the original Istio virtual service HTTP routes before sleep mode modifications for restoration on wakeup.
sleepmode.loft.sh/istio-virtual-service-sleeping​
Type: Annotation (read-only)
Example: sleepmode.loft.sh/istio-virtual-service-sleeping: "true"
Used on: VirtualService (Istio)
Set by: Platform
Indicates that the Istio virtual service should continue reconciling to sleep or be restored when removed.
User and team management​
These labels and annotations are used on user and team resources.
loft.sh/user​
Type: Label
Example: loft.sh/user: "john-doe"
Used on: Namespace, VirtualClusterInstance, SpaceInstance, AccessKey
Set by: Platform
Identifies the user that owns this resource.
loft.sh/team​
Type: Label
Example: loft.sh/team: "platform-team"
Used on: Namespace, VirtualClusterInstance, SpaceInstance, AccessKey
Set by: Platform
Identifies the team that owns this resource.
loft.sh/last-activity​
Type: Annotation
Example: loft.sh/last-activity: "1706745600"
Used on: User
Set by: Platform
Unix timestamp of the user's last activity in the platform.
loft.sh/custom-data​
Type: Annotation
Example: loft.sh/custom-data: '{"department":"engineering"}'
Used on: User
Set by: User-configurable
Custom JSON data attached to a user. Can be used for external integrations.
loft.sh/create-account​
Type: Annotation
Example: loft.sh/create-account: "true"
Used on: User
Set by: User-configurable
When true, automatically creates an account for this user.
loft.sh/previous-email​
Type: Annotation
Example: loft.sh/previous-email: "old@example.com"
Used on: User
Set by: Platform
Stores the user's previous email address after an email change.
loft.sh/notification-email​
Type: Annotation
Example: loft.sh/notification-email: "alerts@example.com"
Used on: User
Set by: User-configurable
Alternate email address for platform notifications.
loft.sh/notification-email-change-time​
Type: Annotation
Example: loft.sh/notification-email-change-time: "1706745600"
Used on: User
Set by: Platform
Unix timestamp when the notification email was last changed.
SSO and authentication​
These annotations relate to single sign-on and authentication.
loft.sh/single-sign-on​
Type: Annotation
Example: loft.sh/single-sign-on: "true"
Used on: User, Team
Set by: Platform
Indicates that this user or team was created through SSO.
loft.sh/sso-provider​
Type: Annotation
Example: loft.sh/sso-provider: "github"
Used on: User, Team
Set by: Platform
Identifies the SSO provider that created this user or team.
RBAC and access control​
These labels and annotations control role-based access.
loft.sh/admin​
Type: Label
Example: loft.sh/admin: "true"
Used on: ClusterRoleBinding
Set by: Platform
Marks a ClusterRoleBinding as granting admin privileges.
loft.sh/aggregate-to-admin​
Type: Label
Example: loft.sh/aggregate-to-admin: "true"
Used on: ClusterRole
Set by: User-configurable
Aggregates this ClusterRole's permissions into the admin role.
loft.sh/aggregate-to-view​
Type: Label
Example: loft.sh/aggregate-to-view: "true"
Used on: ClusterRole
Set by: User-configurable
Aggregates this ClusterRole's permissions into the view role.
loft.sh/default-template​
Type: Label
Example: loft.sh/default-template: "true"
Used on: VirtualClusterTemplate, SpaceTemplate, ClusterAccountTemplate
Set by: User-configurable
Marks this template as the default when no template is specified.
loft.sh/default-role​
Type: Label
Example: loft.sh/default-role: "true"
Used on: ClusterRole
Set by: User-configurable
Marks this ClusterRole as the default role assigned to new users.
loft.sh/management-default-role​
Type: Label
Example: loft.sh/management-default-role: "true"
Used on: ClusterRole
Set by: User-configurable
Marks this ClusterRole as the default management role.
loft.sh/management-namespace​
Type: Label
Example: loft.sh/management-namespace: "loft"
Used on: Namespace
Set by: Platform
Identifies the namespace containing platform management resources.
rbac.loft.sh/auto-update​
Type: Annotation
Example: rbac.loft.sh/auto-update: "true"
Used on: ClusterRole, ClusterRoleBinding
Set by: Platform
When true, allows the platform to automatically update this RBAC resource.
rbac.loft.sh/generation​
Type: Annotation
Example: rbac.loft.sh/generation: "5"
Used on: ClusterRole, ClusterRoleBinding
Set by: Platform
Tracks the generation number for RBAC reconciliation.
Access keys​
These labels identify access key purposes and associations.
loft.sh/cluster​
Type: Label
Example: loft.sh/cluster: "production"
Used on: AccessKey
Set by: Platform
Associates this access key with a specific cluster agent.
loft.sh/vcluster​
Type: Label
Example: loft.sh/vcluster: "my-vcluster"
Used on: AccessKey
Set by: Platform
Associates this access key with a specific vCluster.
loft.sh/runner​
Type: Label
Example: loft.sh/runner: "ci-runner"
Used on: AccessKey
Set by: Platform
Associates this access key with a specific runner.
loft.sh/control-plane-access-key​
Type: Label
Example: loft.sh/control-plane-access-key: "true"
Used on: AccessKey
Set by: Platform
Identifies this access key as used for control plane communication.
loft.sh/vcluster-node​
Type: Label
Example: loft.sh/vcluster-node: "true"
Used on: AccessKey
Set by: Platform
Identifies this access key as used for vCluster node registration.
platform.vcluster.com/cooldown-seconds​
Type: Label
Example: platform.vcluster.com/cooldown-seconds: "300"
Used on: AccessKey
Set by: Platform
Specifies a custom cooldown duration in seconds for this access key, overriding the default cooldown period.
platform.vcluster.com/shell-pod-uid​
Type: Label
Example: platform.vcluster.com/shell-pod-uid: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
Used on: AccessKey
Set by: Platform
Associates this access key with a specific shell pod by its UID for session management.
Integrations​
These annotations and labels configure external integrations.
loft.sh/import-argocd​
Type: Label
Example: loft.sh/import-argocd: "true"
Used on: VirtualClusterInstance, Cluster
Set by: User-configurable
Enables ArgoCD integration for this vCluster or cluster. When set, the platform automatically registers this cluster/vCluster with ArgoCD.
loft.sh/user-managed-destinations​
Type: Annotation
Example: loft.sh/user-managed-destinations: '["https://kubernetes.default.svc"]'
Used on: AppProject (ArgoCD)
Set by: Platform
Tracks which ArgoCD AppProject destinations are managed by the loft project controller. This prevents the controller from removing destinations managed by vCluster instances when syncing project specifications.
loft.sh/connector-type​
Type: Label
Example: loft.sh/connector-type: "rancher"
Used on: Connector
Set by: Platform
Identifies the type of external connector (rancher, etc.).
loft.sh/made-by-connector​
Type: Annotation
Example: loft.sh/made-by-connector: "rancher-connector"
Used on: Cluster
Set by: Platform
Indicates this cluster was imported by an external connector.
loft.sh/is-imported​
Type: Annotation
Example: loft.sh/is-imported: "true"
Used on: Cluster, VirtualClusterInstance
Set by: Platform
Indicates this resource was imported into the platform rather than created by it.
platform.vcluster.com/made-by-connector​
Type: Annotation
Example: platform.vcluster.com/made-by-connector: "database-connector"
Used on: Database resources
Set by: Platform
Identifies the connector that was used to create the database.
Networking​
These annotations configure network-related features.
loft.sh/network-peer-type​
Type: Annotation
Example: loft.sh/network-peer-type: "tailscale"
Used on: NetworkPeer
Set by: Platform
Identifies the type of network peer connection.
loft.sh/network-peer-tags​
Type: Annotation
Example: loft.sh/network-peer-tags: "tag:production,tag:us-east"
Used on: NetworkPeer
Set by: User-configurable
Tailscale tags for this network peer.
loft.sh/network-peer-routes​
Type: Annotation
Example: loft.sh/network-peer-routes: "10.0.0.0/8,172.16.0.0/12"
Used on: NetworkPeer
Set by: User-configurable
Routes to advertise for this network peer.
loft.sh/allowed-hostname​
Type: Annotation
Example: loft.sh/allowed-hostname: "cluster.internal"
Used on: AccessKey
Set by: User-configurable
Restricts this access key to connections from specific hostnames.
loft.sh/allowed-peers​
Type: Annotation
Example: loft.sh/allowed-peers: "peer1,peer2"
Used on: AccessKey
Set by: User-configurable
Restricts this access key to connections from specific network peers.
loft.sh/coordinator-instance-id​
Type: Annotation
Example: loft.sh/coordinator-instance-id: "coord-123"
Used on: NetworkPeer
Set by: Platform
Identifies the coordination instance for distributed networking.
loft.sh/ingress-mirror​
Type: Annotation
Example: loft.sh/ingress-mirror: "true"
Used on: Ingress
Set by: Platform
Indicates that this ingress is a mirror of another ingress resource for management purposes.
loft.sh/network-peer-persistence​
Type: Annotation
Example: loft.sh/network-peer-persistence: "true"
Used on: NetworkPeer, AccessKey
Set by: User-configurable
Marks a network peer as persistent to exclude it from garbage collection. When set on an access key, prevents garbage collection of network peers created by that access key, enabling compatibility with vanilla Tailscale clients.
Shared and project secrets​
These annotations and labels are used for secret management.
loft.sh/sharedsecret-name​
Type: Label
Example: loft.sh/sharedsecret-name: "database-creds"
Used on: Secret
Set by: Platform
The name of the shared secret this secret was created from.
loft.sh/sharedsecret-namespace​
Type: Label
Example: loft.sh/sharedsecret-namespace: "loft-default-p-default-s-default"
Used on: Secret
Set by: Platform
The namespace where the source shared secret is stored.
loft.sh/disable-sync​
Type: Annotation
Example: loft.sh/disable-sync: "true"
Used on: Secret
Set by: User-configurable
When set, prevents the platform from syncing this secret from a shared secret.
loft.sh/project-secret​
Type: Label
Example: loft.sh/project-secret: "true"
Used on: Secret
Set by: Platform
Marks this secret as a synced instance of a project secret.
loft.sh/project-secret-name​
Type: Annotation
Example: loft.sh/project-secret-name: "api-keys"
Used on: Secret
Set by: Platform
The name of the project secret this secret was created from.
loft.sh/project-secret-description​
Type: Annotation
Example: loft.sh/project-secret-description: "API keys for external services"
Used on: ProjectSecret
Set by: User-configurable
Human-readable description of the project secret.
loft.sh/project-secret-displayname​
Type: Annotation
Example: loft.sh/project-secret-displayname: "External API Keys"
Used on: ProjectSecret
Set by: User-configurable
Display name for the project secret shown in the UI.
loft.sh/project-secret-owner​
Type: Annotation
Example: loft.sh/project-secret-owner: "user:john-doe"
Used on: ProjectSecret
Set by: Platform
Identifies the owner of this project secret.
loft.sh/project-secret-access​
Type: Annotation
Example: loft.sh/project-secret-access: "project"
Used on: ProjectSecret
Set by: User-configurable
Access scope for the project secret.
Applications​
These labels are used for application management.
loft.sh/app​
Type: Label
Example: loft.sh/app: "nginx"
Used on: Helm release resources
Set by: Platform
Identifies resources belonging to a platform-managed application.
loft.sh/system-app​
Type: Label
Example: loft.sh/system-app: "true"
Used on: Application resources
Set by: Platform
Marks this application as a system application managed by the platform.
loft.sh/extra-recommended-apps​
Type: Annotation
Example: loft.sh/extra-recommended-apps: "prometheus,grafana"
Used on: Cluster
Set by: User-configurable
Comma-separated list of additional recommended applications for this cluster.
loft.sh/app-name​
Type: Annotation
Example: loft.sh/app-name: "nginx"
Used on: HelmRelease
Set by: Platform
Indicates that the Helm release was deployed via the platform app store and identifies the app name.
loft.sh/app-version​
Type: Annotation
Example: loft.sh/app-version: "1.2.3"
Used on: HelmRelease
Set by: Platform
The version of the platform app that was deployed.
loft.sh/url​
Type: Annotation
Example: loft.sh/url: "https://charts.example.com/stable"
Used on: HelmRelease
Set by: Platform
The Helm repository URL from which the release was deployed.
loft.sh/insecure-skip-tls​
Type: Annotation
Example: loft.sh/insecure-skip-tls: "true"
Used on: HelmRelease
Set by: User-configurable
When true, TLS certificate verification is skipped during Helm operations for this release.
Cleanup and finalizers​
These finalizers and labels control resource cleanup behavior.
loft.sh/cleanup​
Type: Finalizer
Example: finalizers: ["loft.sh/cleanup"]
Used on: Various resources
Set by: Platform
General cleanup finalizer ensuring proper resource deletion.
loft.sh/cleanup-management​
Type: Finalizer
Example: finalizers: ["loft.sh/cleanup-management"]
Used on: Cluster, Project
Set by: Platform
Ensures management resources are cleaned up when the parent resource is deleted.
loft.sh/cleanup-workload​
Type: Finalizer
Example: finalizers: ["loft.sh/cleanup-workload"]
Used on: VirtualClusterInstance, SpaceInstance
Set by: Platform
Ensures workload resources are cleaned up when deleted.
loft.sh/cleanup-rancher​
Type: Finalizer
Example: finalizers: ["loft.sh/cleanup-rancher"]
Used on: Cluster
Set by: Platform
Ensures Rancher integration resources are cleaned up.
loft.sh/cleanup-connectors​
Type: Finalizer
Example: finalizers: ["loft.sh/cleanup-connectors"]
Used on: Cluster
Set by: Platform
Ensures connector resources are cleaned up.
loft.sh/cleanup-nodes​
Type: Finalizer
Example: finalizers: ["loft.sh/cleanup-nodes"]
Used on: Cluster
Set by: Platform
Ensures dynamically provisioned nodes are cleaned up.
loft.sh/cleanup-cloud-resources​
Type: Finalizer
Example: finalizers: ["loft.sh/cleanup-cloud-resources"]
Used on: Cluster
Set by: Platform
Ensures cloud provider resources are cleaned up.
loft.sh/cleanup-identity-provider​
Type: Finalizer
Example: finalizers: ["loft.sh/cleanup-identity-provider"]
Used on: SSO configuration
Set by: Platform
Ensures identity provider resources are cleaned up.
Drift detection​
These annotations control drift detection behavior.
drift.loft.sh/force-check​
Type: Annotation
Example: drift.loft.sh/force-check: "true"
Used on: VirtualClusterInstance, SpaceInstance
Set by: User-configurable
Forces an immediate drift check on this resource.
Miscellaneous​
These annotations are used for various platform features.
loft.sh/version​
Type: Annotation
Example: loft.sh/version: "4.0.0"
Used on: Platform configuration
Set by: Platform
The platform version that last modified this resource.
loft.sh/warn-deletion​
Type: Annotation
Example: loft.sh/warn-deletion: "true"
Used on: Cluster, Project, VirtualClusterInstance
Set by: User-configurable
Enables a deletion warning in the UI for this resource.
loft.sh/non-deletable​
Type: Annotation
Example: loft.sh/non-deletable: "true"
Used on: Various resources
Set by: User-configurable
Prevents deletion of this resource through the platform API and UI.
loft.sh/platform-db-applied-time​
Type: Annotation
Example: loft.sh/platform-db-applied-time: "1706745600"
Used on: Platform database resources
Set by: Platform
Timestamp of when database migrations were last applied.
platform.vcluster.com/is-browser-shell-ns​
Type: Annotation
Example: platform.vcluster.com/is-browser-shell-ns: "true"
Used on: Namespace
Set by: Platform
Indicates and confirms that a namespace was created for the browser shell feature.