Fleet Observability labels reference

The Write Gateway owns the full vcluster_platform_* label namespace. These labels are stamped from authenticated Platform context and are safe to use for dashboards, recording rules, and backend queries.

warning

Don't set labels with the vcluster_platform_* prefix in collectors or applications. The Write Gateway strips caller-supplied platform labels before adding authenticated values.

Scope-controlling labels

The Query Proxy uses these labels for read authorization.

Label	Meaning	Header equivalent
vcluster_platform_cluster	Control plane cluster identity.	X-Vcluster-Platform-Cluster
vcluster_platform_project	Tenant cluster project.	X-Vcluster-Platform-Project
vcluster_platform_instance	VirtualClusterInstance name.	X-Vcluster-Platform-Instance

Use either cluster scope or tenant scope, not both:

• Cluster scope: vcluster_platform_cluster
• Tenant scope: vcluster_platform_project and vcluster_platform_instance

Descriptive labels

These labels are stamped at write time for filtering and grouping, but they don't authorize reads.

Label	Meaning
vcluster_platform_hosted_on	Registered control plane cluster that hosts the tenant cluster.
vcluster_platform_placement	Placement category, such as hosted, standalone, or external.
vcluster_platform_shape	Node arrangement, such as control_plane, shared_nodes, or private_nodes.
vcluster_platform_node_management	Private-node management mode, such as manual or auto. Empty for non-private-node shapes.

Matcher rules

The Query Proxy restricts matchers on scope-controlling labels:

Matcher	Scope labels	Example
Equality	Allowed	vcluster_platform_instance="api"
Literal alternation regular expression	Allowed	vcluster_platform_instance=~"api|worker"
Negative equality	Rejected	vcluster_platform_instance!="api"
Negative regular expression	Rejected	vcluster_platform_instance!~"api"
Wildcard regular expression	Rejected	vcluster_platform_instance=~".*"

Descriptive labels can use normal PromQL matcher forms because they don't determine authorization scope.

Label examples

Tenant cluster metric:

vcluster_platform_project="team-a"
vcluster_platform_instance="api"
vcluster_platform_hosted_on="local-cluster"
vcluster_platform_placement="hosted"
vcluster_platform_shape="shared_nodes"

Control plane cluster metric:

vcluster_platform_cluster="local-cluster"

Private-nodes tenant cluster metric:

vcluster_platform_project="gpu-team"
vcluster_platform_instance="inference"
vcluster_platform_hosted_on="local-cluster"
vcluster_platform_placement="hosted"
vcluster_platform_shape="private_nodes"
vcluster_platform_node_management="auto"

Migration from older labels

Aggregating metrics and Fleet monitoring with OpenTelemetry predate the Fleet Observability gateway and use their own self-reported label schemes. These aren't migrations in the sense of a renamed field. The authenticated vcluster_platform_* labels come from a different collection and authorization model, so some older labels have no direct equivalent. Prefer vcluster_platform_* for anything going through the Fleet Observability gateway.

Older label	Source guide	Meaning	vcluster_platform_* equivalent
cluster	Fleet monitoring with OpenTelemetry	Control plane cluster hosting the tenant cluster (this guide's pipeline always pairs it with tenant identity)	vcluster_platform_hosted_on. vcluster_platform_cluster is reserved for cluster-scoped metrics with no tenant identity, which this guide's pipeline doesn't produce.
vcluster_name	Fleet monitoring with OpenTelemetry	Tenant cluster name	vcluster_platform_instance
vcluster_project	Fleet monitoring with OpenTelemetry	Project	vcluster_platform_project
vcluster_project_namespace	Fleet monitoring with OpenTelemetry	Namespace backing the tenant cluster	No direct equivalent — the gateway doesn't expose the backing namespace as a scope label
vcluster_user	Fleet monitoring with OpenTelemetry	Tenant cluster owner	No direct equivalent — not part of the authenticated scope model
vcluster_virtual_namespace	Fleet monitoring with OpenTelemetry	Namespace as seen inside the tenant cluster	No direct equivalent
vcluster_virtual_pod	Fleet monitoring with OpenTelemetry	Pod as seen inside the tenant cluster	No direct equivalent
loft_project_name	Aggregating Metrics	Project	vcluster_platform_project
loft_virtualcluster_name	Aggregating Metrics	Tenant cluster name	vcluster_platform_instance
loft_space_name	Aggregating Metrics	Space name (Space-type tenants only)	No direct equivalent

For the status and operational ownership of each architecture, see Fleet metrics architectures.