From 69a875d312f2d86df90029b45f3adacdebed2ea7 Mon Sep 17 00:00:00 2001
From: Jonathan Porter <38440687+jp-cpe@users.noreply.github.com>
Date: Fri, 10 Jul 2026 04:14:54 -0700
Subject: [PATCH] Enhance labels documentation in Fleet (#47753)
Expanded the section on labels in Fleet, detailing types, targeting,
scope, and management. Added recommendations for naming conventions to
avoid collisions.
**Related issue:** Resolves #44049
---------
Co-authored-by: Steven Palmesano <3100993+spalmesano0@users.noreply.github.com>
---
articles/managing-labels-in-fleet.md | 38 +++++++++++++++++++++++-----
1 file changed, 31 insertions(+), 7 deletions(-)
diff --git a/articles/managing-labels-in-fleet.md b/articles/managing-labels-in-fleet.md
index bf5d5bedd9..d7fdd03b98 100644
--- a/articles/managing-labels-in-fleet.md
+++ b/articles/managing-labels-in-fleet.md
@@ -1,14 +1,37 @@
# Labels
+In Fleet, labels organize hosts into groups you can target with [software](https://fleetdm.com/guides/deploy-software-packages), [policies](https://fleetdm.com/securing/what-are-fleet-policies), [reports](https://fleetdm.com/guides/queries), and [configuration profiles](https://fleetdm.com/guides/custom-os-settings). You can also use labels to filter the hosts view.
-In Fleet, you can use labels to scope [software](https://fleetdm.com/guides/deploy-software-packages), [policies](https://fleetdm.com/securing/what-are-fleet-policies), [queries](https://fleetdm.com/guides/queries), and [configuration profiles](https://fleetdm.com/guides/custom-os-settings) for specific hosts, and filter the hosts view.
+> We recommend labels, rather than separate fleets, as your primary way to target these features.
-Labels can be one of the following types:
-- **Dynamic**: A query-based label applied to any host that returns a result for the label's query.
-> If you want to change the query or platform on a dynamic label, you must delete the existing label and create a new one.
-- **Manual**: A manually assigned label used to filter selected hosts.
-- **Host vitals**: A Fleet-generated label applied to hosts that match a specific host vital (currently IdP group and department on macOS, iOS, iPadOS, and Android).
-> If you want to change the target of a host vitals label, you must delete the existing label and create a new one.
+## Label types
+
+- **Dynamic:** Query-based; auto-applied to any host returning a result for the label's SQL query. Optionally restrict to a platform (`darwin`, `windows`, `ubuntu`, `centos`).
+- **Manual:** Applied to an explicit list of hosts, specified by `hardware_serial`, `uuid`, or Fleet host ID. Useful for one-off groupings (e.g., a pilot group).
+- **Host vitals:** Auto-applied to hosts matching a host vital from your IdP. Supported criteria: `end_user_idp_group` and `end_user_idp_department`. Requires a connected IdP (Okta, Microsoft Entra ID, Google Workspace, authentik, or any SCIM provider; see [Foreign host vitals](https://fleetdm.com/guides/foreign-vitals-map-idp-users-to-hosts)).
+
+> To change a dynamic label's query/platform or a host vitals label's criteria in the UI, you must delete and re-create it.
+
+## Targeting with labels
+
+Labels can target or exclude hosts using one scoping mode per item. Configuration Profiles support custom targeting via "Include any" and "Exclude any":
+
+| Scope | Behavior | Available for |
+| --- | --- | --- |
+| **Include any** | Targets hosts with **any** of the labels | Software, policies, reports, configuration profiles |
+| **Include all** | Targets hosts with **all** of the labels | Software, policies, reports, configuration profiles |
+| **Exclude any** | Excludes hosts with **any** of the labels | Software, policies, configuration profiles |
+
+## Label scope: global vs. fleet
+
+A label's scope is set based on where it's created, not by its name:
+
+- **Global:** Available across all fleets. Created by a global user in the UI, or defined in `default.yml`.
+- **Fleet:** (Fleet Premium) Scoped to a single fleet and visible only alongside global labels for that fleet. Defined in that fleet's `fleets/fleet-name.yml`. Defining a label here scopes it to the fleet; it does **not** become global.
+
+> **Tip:** Label names share one namespace, so creating a label whose name already exists (global or fleet) will fail. If multiple teams manage labels independently, prefix them to avoid collisions—either **by owner/fleet** (e.g. `[Workstations] Kiosk`, `ws-kiosk`) or by **centralizing all labels** in one place (e.g. a `labels/` directory referenced from `default.yml`) as the single source of truth, so collisions surface in a single PR.
+
+## Managing labels
To add or edit a label in Fleet, select the avatar on the right side of the top navigation and select **Labels**.
@@ -63,6 +86,7 @@ If no label targeting is specified, the profile is delivered to all hosts on the
You can also set label targets through the Fleet UI when adding or editing a configuration profile under **Controls > OS settings > Configuration profiles**, or via the [REST API](https://fleetdm.com/docs/rest-api/rest-api#create-configuration-profile).
+