fleet/articles/custom-host-vitals.md

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 and configuration profiles. You can also use a custom host vital's value to target hosts with a Host vitals label.

Unlike custom variables ($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 and host name templates is coming in Fleet 4.91.

Prerequisites

• A global admin or maintainer role to add, edit, or delete custom host vitals.
• A Fleet API token if you'll set host values via the API.

Add custom host vitals

Each custom host vital has a unique name and is referenced by a variable in the format $FLEET_HOST_VITAL_<id> (or ${FLEET_HOST_VITAL_<id>}), where <id> 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: 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 ($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:

The new vital appears in the table. Copy its variable (for example, $FLEET_HOST_VITAL_21) from the Variable column to reference it in scripts and profiles, and use the pencil and trash icons to rename or delete it:

GitOps

Custom host vitals are global and are specified inline in your default.yml file. Each entry's name must be unique across all custom host vitals:

custom_host_vitals:
  - name: Asset tag
  - name: Function
  - name: ITAM device ID

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

A custom host vital starts with no value on each host. Until a value is set for a host, sending a script or profile that references the vital to that host will fail.

Global admins and maintainers can set a value on any host; fleet admins and maintainers can set values for hosts in their fleets.

UI

Each custom host vital appears in a host's Details > Vitals, showing --- until a value is set:

Click the pencil (edit) icon next to the vital, enter a value, and click Save:

The value now shows in the host's vitals, and the change is recorded in the host's activity:

API

Set a host's value with the Fleet REST API. This is useful for syncing values from an external system of record (for example, an asset management tool):

curl -X PUT https://<your-fleet-url>/api/v1/fleet/hosts/<host_id>/custom_host_vitals/<id> \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"value": "C02XL0Zerato"}'

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_<id> with that host's value.

For example, a configuration profile that writes the host's asset tag (defined as $FLEET_HOST_VITAL_1):

<key>PayloadContent</key>
<string>$FLEET_HOST_VITAL_1</string>

Note: Referencing a $FLEET_HOST_VITAL_<id> 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 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.

Filter hosts by a custom host vital

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 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:

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 for the full label schema.