From f656ac533a1231aa61e40400d5a469552bdf8192 Mon Sep 17 00:00:00 2001 From: kitzy Date: Fri, 7 Aug 2026 08:58:59 -0500 Subject: [PATCH] Update custom host vitals guide: style cleanup and Host vitals label support (#50660) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **Related issue:** N/A ## Summary Audits and updates `articles/custom-host-vitals.md` against Fleet's guide-formatting and content-style skills, and documents that custom host vitals can be used as Host vitals label criteria: - Trimmed the opening from 3 paragraphs to 2, and added a sentence pointing to the new labels use case. - Renamed "Using a custom host vital in scripts and configuration profiles" → "Reference a custom host vital in scripts and configuration profiles" to match the imperative, action-led heading style used by sibling sections. - Dissolved the standalone "Known limitations and issues" section — its items are now `> **Note:**`/`> **Warning:**` callouts placed next to the step each one actually affects, instead of collected at the bottom. The delete-protection callout now also covers Host vitals labels, not just scripts/profiles. - Removed em dashes and bolding used for emphasis rather than UI elements, per Fleet's content style guide. - New "Filter hosts by a custom host vital" section (UI + GitOps) documenting the existing Host vitals label type's support for custom host vitals, including the current exact-match-only limitation. # Checklist for submitter - [ ] QA'd all new/changed functionality manually --- articles/custom-host-vitals.md | 56 +++++++++++++++++++++++++--------- 1 file changed, 42 insertions(+), 14 deletions(-) diff --git a/articles/custom-host-vitals.md b/articles/custom-host-vitals.md index 7abc21a218..312f3a647a 100644 --- a/articles/custom-host-vitals.md +++ b/articles/custom-host-vitals.md @@ -1,10 +1,8 @@ # Use custom host vitals in scripts and configuration profiles -Custom host vitals let you define your own host fields, set a value for each host, and reference those values as variables (prefixed with `$FLEET_HOST_VITAL_`) in [scripts](https://fleetdm.com/guides/scripts) and [configuration profiles](https://fleetdm.com/guides/custom-os-settings). +Custom host vitals let you define your own host fields, set a value for each host, and reference those values as variables (prefixed with `$FLEET_HOST_VITAL_`) in [scripts](https://fleetdm.com/guides/scripts) and [configuration profiles](https://fleetdm.com/guides/custom-os-settings). You can also use a custom host vital's value to target hosts with a [Host vitals label](https://fleetdm.com/guides/managing-labels-in-fleet). -Unlike [custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles) (`$FLEET_SECRET_*`), which hold a single value shared across all hosts, a custom host vital can hold a **different value per host**. For example, an "Asset tag" vital can resolve to a different asset tag on every device. Custom host vital values are **not** hidden in the UI or API — don't use them for secrets. - -Support for custom host vitals in [Android configuration profiles](https://github.com/fleetdm/fleet/issues/49421) and [host name templates](https://github.com/fleetdm/fleet/issues/49489) is coming in Fleet 4.91. +Unlike [custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles) (`$FLEET_SECRET_*`), which hold a single value shared across all hosts, a custom host vital can hold a different value per host. For example, an "Asset tag" vital can resolve to a different asset tag on every device. Support for custom host vitals in [Android configuration profiles](https://github.com/fleetdm/fleet/issues/49421) and [host name templates](https://github.com/fleetdm/fleet/issues/49489) is coming in Fleet 4.91. ## Prerequisites @@ -15,11 +13,13 @@ Support for custom host vitals in [Android configuration profiles](https://githu Each custom host vital has a unique name and is referenced by a variable in the format `$FLEET_HOST_VITAL_` (or `${FLEET_HOST_VITAL_}`), where `` is the vital's ID. You can copy the exact variable from the **Variable** column of the Custom host vitals table. -Custom host vitals are global, meaning they can be used in scripts and profiles across all fleets. +Custom host vitals are global: you can reference them in scripts and profiles, or use them as label criteria, across all fleets. + +> **Warning:** Custom host vital values are not masked in the Fleet UI, API, or script results. Use [custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles) (`$FLEET_SECRET_*`) for secrets. ### UI -To add a custom host vital, go to **Controls > Variables > Custom host vitals** and click **Add vital**. Give it a name — this becomes the vital's label on the host details page: +To add a custom host vital, go to **Controls > Variables > Custom host vitals** and click **Add vital**. Give it a name. This becomes the vital's label on the host details page: ![Add a custom host vital](../website/assets/images/articles/custom-host-vitals-tab-add-vital-modal-1509x716@2x.png) @@ -35,10 +35,12 @@ Custom host vitals are global and are specified inline in your `default.yml` fil custom_host_vitals: - name: Asset tag - name: Function - - name: Jamf device ID + - name: ITAM device ID ``` -Custom host vitals removed from `default.yml` are deleted on the next GitOps run. A run fails if you try to delete a vital that's still referenced by a script or profile — remove the reference first (see [Known limitations and issues](#known-limitations-and-issues)). +Custom host vitals removed from `default.yml` are deleted on the next GitOps run. + +> **Warning:** A custom host vital can't be deleted while it's referenced by a script, configuration profile, or Host vitals label. Edit or delete the reference first, then delete the vital (or remove it from `default.yml`). ## Set a host's value @@ -71,7 +73,7 @@ curl -X PUT https:///api/v1/fleet/hosts//custom_host_vi -d '{"value": "C02XL0Zerato"}' ``` -## Using a custom host vital in scripts and configuration profiles +## Reference a custom host vital in scripts and configuration profiles Reference the vital by its variable anywhere in a script or configuration profile. When Fleet sends the script or profile to a host, it replaces `$FLEET_HOST_VITAL_` with that host's value. @@ -82,14 +84,40 @@ For example, a configuration profile that writes the host's asset tag (defined a $FLEET_HOST_VITAL_1 ``` +> **Note:** Referencing a `$FLEET_HOST_VITAL_` that doesn't exist (for example, a typo like `$FLEET_HOST_VITAL_asset_tag`) is rejected when the script or profile is added. + +> **Note:** Custom host vitals can't be used in certificate authority (SCEP/ACME/DigiCert) payloads. Those fields accept [built-in variables](https://fleetdm.com/guides/fleet-variables) only. + When a host's value changes, Fleet automatically resends the Apple (macOS, iOS, iPadOS) and Windows configuration profiles that reference the vital, so each device receives its updated value. -## Known limitations and issues +## Filter hosts by a custom host vital -- Custom host vital values are **not** masked in the Fleet UI, API, or script results. Use [custom variables](https://fleetdm.com/guides/secrets-in-scripts-and-configuration-profiles) (`$FLEET_SECRET_*`) for secrets. -- A custom host vital **can't be deleted while it's referenced** by a script or configuration profile. Edit or delete the referencing script/profile first, then delete the vital. -- Referencing a `$FLEET_HOST_VITAL_` that doesn't exist (for example, a typo like `$FLEET_HOST_VITAL_asset_tag`) is rejected when the script or profile is added. -- Custom host vitals can't be used in certificate authority (SCEP/ACME/DigiCert) payloads; those fields accept [built-in variables](https://fleetdm.com/guides/fleet-variables) only. +Instead of writing a custom host vital into a dynamic label's SQL query, you can create a **Host vitals** label that matches hosts by the vital's value directly. See [Labels in Fleet](https://fleetdm.com/guides/managing-labels-in-fleet) for the full list of label types and how they're scoped. + +> **Note:** Host vitals labels only support an exact match (`is equal to`) today. To match a pattern instead (for example, every asset tag starting with a prefix), use a dynamic label's SQL query. + +### UI + +To create one, select the avatar on the right side of the top navigation, select **Labels**, then click **Add label**. Choose **Host vitals** as the label type, select your custom host vital from the **Label criteria** dropdown, and enter the value it must equal. Give the label a name and click **Save**. + +To change a Host vitals label's criteria, delete and recreate the label. Fleet doesn't currently support editing Host vitals criteria in place. + +### GitOps + +Set `label_membership_type` to `host_vitals`, and set `criteria.vital` to `custom_host_vital` with `criteria.custom_host_vital_id` set to the vital's ID: + +```yaml +labels: + - name: Point of sale terminals + description: Hosts whose "Function" custom host vital is set to "Point of sale" + label_membership_type: host_vitals + criteria: + vital: custom_host_vital + custom_host_vital_id: 2 + value: Point of sale +``` + +See [GitOps labels](https://fleetdm.com/docs/configuration/yaml-files#labels) for the full label schema.