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

Older OpenTelemetry examples used labels such as cluster, vcluster_name, vcluster_project, or loft_virtualcluster_name. For the Fleet Observability gateway, prefer the vcluster_platform_* labels. They are stamped after authentication and are the label contract used by the Query Proxy.