The label-based catalog reference mechanism is replaced by the catalogItemRef specification field. Update your CLI or API workflows to use catalogItemRef instead of catalog-related labels.

Important

The label-based catalog reference model is deprecated. Existing label-based catalog references are automatically migrated during upgrade, but labels are no longer the mechanism for associating catalog items with devices and fleets. Use the catalogItemRef field in Device and Fleet specifications instead.

Deprecated labels

The following labels were previously used as a UI-only convention to associate catalog items with devices and fleets. These labels are no longer used for catalog associations:

• os.catalog.flightctl.io/catalog
• os.catalog.flightctl.io/item
• os.catalog.flightctl.io/channel
• Equivalent labels for application and data volumes catalog associations

Why the label-based model is replaced

The label-based catalog reference model was a UI-only convention that was not enforced by the Flight Control API. This approach had several limitations:

• Fragile associations: Labels could be edited or removed by any user or automation with write access to the device or fleet, silently breaking the catalog association without API-level validation.
• No reference integrity: The API did not prevent deletion or modification of catalog items that were associated with devices through labels. Removing a catalog item left devices with stale label references that pointed to nonexistent content.
• UI-only visibility: The label-based associations were meaningful only in the Flight Control web console. API and CLI users had no documented way to set or read catalog associations and had to reverse-engineer the label patterns to automate catalog-based deployments.

The catalogItemRef field addresses these limitations by providing a first-class, API-validated mechanism for catalog references. The field is part of the Device and Fleet specification, which means it is subject to API validation, lifecycle protection, and type checking.

Who is affected

• UI users: The Flight Control web console handles the change transparently. You do not need to take action.
• API and CLI users: If your automation or tools read or write catalog.flightctl.io labels for catalog purposes, you must update them to use the catalogItemRef field. See Catalog item reference field specification in the Additional resources section.
• Upgrade users: If you are upgrading from a previous version, existing label-based catalog references are automatically migrated. See Migrate label-based catalog references in the Additional resources section.