Device Attributes¶
Device attributes are metadata fields attached to individual devices in your Qbee fleet. They store identifying information — such as a device name, physical location, or environment type — that you can use to search, filter, and organize devices.
Qbee supports two types of device attributes:
- Legacy attributes — a fixed set of built-in fields (device name, description, and location data)
- Custom attributes — user-defined key-value pairs you create to match your use case
You can set attributes through the web UI, the REST API, or directly from the device using the qbee-agent CLI.
Legacy attributes¶
Legacy attributes are predefined fields available on every device. They cover basic identification and geographic location.
| Field | Description | User-settable | Auto-discovered |
|---|---|---|---|
device_name | Human-readable device name | ✅ | — |
description | Free-text device description | ✅ | — |
latitude | Geographic latitude | ✅ | ✅ |
longitude | Geographic longitude | ✅ | ✅ |
country | Country | ✅ | ✅ |
city | City | ✅ | ✅ |
zip | ZIP / postal code | ✅ | ✅ |
address | Street address | ✅ | ✅ |
Location fields (latitude, longitude, country, city, zip, address) can be auto-discovered from the device's public IP address. Auto-discovered values are stored separately from user-set values, so manually setting a location field does not interfere with automatic discovery.
Custom attributes¶
Custom attributes are key-value pairs you define yourself. Use them to attach any metadata relevant to your fleet — for example, hardware revision, deployment environment, customer ID, or rack location.
Current limits¶
| Constraint | Limit |
|---|---|
| Maximum attributes per device | 10 |
| Maximum key length | 64 characters |
| Maximum value length | 4096 characters (4 KB) |
| Value type | String only |
All custom attribute values are stored as strings. If you need numeric or structured data, store it as a string and parse it on the consuming side.
How attributes differ from tags, parameters, secrets, and template parameters¶
Qbee offers several ways to attach metadata and configuration to devices. Here is how they compare:
| Feature | Purpose | Scope | Set from device? |
|---|---|---|---|
| Attributes | Per-device metadata for identification and filtering | Individual device | ✅ |
| Tags | Organizational labels for grouping devices and inheriting configuration | Device or group | — |
| Configuration parameters | Shared key-value pairs usable anywhere in the Qbee configuration | Any level (inherits down) | — |
Tags group devices for configuration inheritance. When you apply a configuration to a tag, every device with that tag receives it. Tags are organizational tools — they determine what configuration a device gets.
Configuration parameters are shared key-value pairs defined on the Parameters tab. They are referenced through $(parameter) placeholders and can be used anywhere in the Qbee configuration itself. Parameters inherit down the group tree, so a parameter defined at a parent level is available to every device below. See Parameters and secrets for details.
Secrets are a type of configuration parameter whose value is hidden once saved. They are referenced through the same $(parameter) syntax as regular parameters, but the value cannot be retrieved after saving — the UI and API return only an internal reference, and the device receives the real value only when it pulls its configuration. Secrets are immutable: setting a new value overrides the previous reference. Use them for credentials, tokens, and any value that must not appear in committed configuration or device logs. See Parameters and secrets for details.
Template parameters are per-item key-value pairs that live inside a specific File Distribution, Software Management, or Docker Compose item. They use {{key}} placeholders that get substituted into the deployed file at converge time. A common pattern is to feed a configuration parameter (or a secret) into a template parameter — for example, setting a template parameter PASSWORD to $(my-secret) so the secret's value is injected when the agent deploys the file. See Key-Value Templating for details.
Attributes describe individual devices. They are set per-device (via UI, API, or from the device itself) and are used for searching and filtering the fleet. Attributes do not affect configuration inheritance.
What Next?¶
| I want to... | Go to |
|---|---|
| Create, update, and delete attributes via the UI and API | Managing Attributes |
| Read and set attributes from the device using qbee-agent | Device-Side Access |
| Filter my fleet by attribute values | Searching by Attributes |