Catalog item reference field specification

The catalogItemRef field lets you reference Software Catalog items directly in Device and Fleet specifications through the CLI or API, replacing manual OCI image references with an API-validated catalog reference.

The catalogItemRef field is mutually exclusive with the image field. In spec.os and in each entry under spec.applications, you specify either image (a direct OCI image reference) or catalogItemRef (a catalog-sourced reference), but not both. The image and catalogItemRef fields apply to Container, Quadlet, Compose, and Helm application types. VM applications use neither field and must specify their configuration as an inline vm.yaml file.

The YAML examples in this section show Device and Fleet resources, which use the flightctl.io/v1beta1 API version. Catalog and CatalogItem resources use flightctl.io/v1alpha1. For catalog definition examples, see Managing a catalog repository on the CLI in the Additional resources section.

catalogItemRef sub-fields

The following table describes the sub-fields of the catalogItemRef object:

Table 1. catalogItemRef sub-fields
Sub-field Type Required Description

catalog

String

Yes

The name of the catalog that contains the item. This must match the metadata.name of an existing Catalog resource.

item

String

Yes

The name of the catalog item to deploy. This must match the metadata.name of an existing CatalogItem resource within the specified catalog.

version

String

Yes

The semantic version of the catalog item to deploy, for example 1.2.0. This must match a version entry defined in the CatalogItem resource.

channel

String

No

An informational indicator that tracks update availability for the referenced catalog item. The channel value is displayed in the Flight Control web console to show when newer versions are available along the same update path. The channel sub-field is informational only and never triggers automatic device updates to a newer version.
Note

The catalogItemRef field does not affect other application specification fields. Fields such as appType, envVars, runAs, and ports continue to work independently of whether you use image or catalogItemRef.

Referencing a catalog operating system image for a device

The following example shows a Device resource that uses catalogItemRef in spec.os to deploy an operating system image from the catalog:

apiVersion: flightctl.io/v1beta1
kind: Device
metadata:
  name: <device_name>
spec:
  os:
    catalogItemRef:
      catalog: <catalog_name>
      item: <os_image_item_name>
      version: "<version>"
      channel: "<channel (optional)>"

Where:

<catalog_name>
The name of the catalog that contains the operating system image item.
<os_image_item_name>
The name of the catalog item for the operating system image.
<version>
The semantic version to deploy, for example 9.5.0.

Referencing a catalog application for a device

The following example shows a Device resource that uses catalogItemRef in spec.applications to deploy an application from the catalog:

apiVersion: flightctl.io/v1beta1
kind: Device
metadata:
  name: <device_name>
spec:
  applications:
  - name: <application_name>
    appType: container
    catalogItemRef:
      catalog: <catalog_name>
      item: <app_item_name>
      version: "<version>"
      channel: "<channel (optional)>"
    runAs: flightctl
    envVars:
      APP_ENV: production

Where:

<catalog_name>
The name of the catalog that contains the application item.
<app_item_name>
The name of the catalog item for the application.
<version>
The semantic version to deploy, for example 1.0.0.

Referencing catalog items in a fleet device template

You can use catalogItemRef in a fleet device template so that all devices in the fleet receive the catalog-sourced operating system image and applications. The following example shows a Fleet resource with catalogItemRef for both the operating system image and an application:

apiVersion: flightctl.io/v1beta1
kind: Fleet
metadata:
  name: <fleet_name>
spec:
  selector:
    matchLabels:
      region: <region>
  template:
    spec:
      os:
        catalogItemRef:
          catalog: <catalog_name>
          item: <os_image_item_name>
          version: "<version>"
          channel: "<channel (optional)>"
      applications:
      - name: <application_name>
        appType: container
        catalogItemRef:
          catalog: <catalog_name>
          item: <app_item_name>
          version: "<version>"
          channel: "<channel (optional)>"
        runAs: flightctl