You can add catalog content to Flight Control by creating a Repository resource that points to a Git repository containing catalog definitions, and a ResourceSync resource with type catalog that synchronizes those definitions.

This procedure covers Git-synchronized catalogs. To publish catalog items from image builder instead, see Publishing an image build to the Software Catalog in the Additional resources section.

Default catalog

Every organization receives a default catalog automatically when the organization is first provisioned. You do not create this catalog manually. Image promotions and Git-synchronized catalogs can both target or coexist with the default catalog.

Verify the default catalog:

flightctl get catalog/default

Complete the following steps to synchronize catalog definitions from Git:

1. Create a Repository resource that points to your Git repository. The repository must contain Catalog and CatalogItem YAML definitions. Set type: git and the repository URL:

   apiVersion: flightctl.io/v1beta1
   kind: Repository
   metadata:
     name: <repository-name>
   spec:
     url: <repo_url_with_catalog_definition>
     type: git

2. Create a ResourceSync resource that imports the catalog from the repository. Set type: catalog, reference the repository name from step 1, and specify the path and branch to sync:

   apiVersion: flightctl.io/v1beta1
   kind: ResourceSync
   metadata:
     name: <resourcesync-name>
   spec:
     repository: <repository-name>
     targetRevision: <git_branch_name>
     path: <path_to_catalog_yaml>
     type: catalog

3. Apply both resources. For example, if you saved the Repository to my-repo.yaml and the ResourceSync to my-catalog-sync.yaml:

   flightctl apply -f my-repo.yaml
   flightctl apply -f my-catalog-sync.yaml

4. Verify that the resources were created and that synchronization succeeded:

   flightctl get repository/<repository-name>
   flightctl get resourcesync <resourcesync-name>

Defining catalogs and catalog items in Git

Your Git repository must contain Catalog and CatalogItem resources that describe the resources that will be imported into the Software Catalog. Store them under the directory (or file path) that you set in the ResourceSyncspec.path field.

Organize files in a layout similar to the following:

catalogs/
  <catalog-name>/
    catalog.yaml
    <catalog-item-name>.yaml

• catalog.yaml defines the Catalog resource (metadata.name is the catalog identifier).
• Each additional file in the same directory defines one CatalogItem. Every CatalogItem must set metadata.catalog to the same catalog name as the Catalog resource.

Catalog resource

The following example shows a minimal Catalog resource:

apiVersion: flightctl.io/v1alpha1
kind: Catalog
metadata:
  name: <catalog-name>
spec:
  displayName: <human_readable_catalog_title>
  shortDescription: <one_line_description>

CatalogItem versions, channels, and artifacts

Each CatalogItem declares a spec.type (for example, container for an application image), one or more spec.artifacts entries with a type and a versionless uri, and a spec.versions list. Every version entry must include:

• version: A semantic version string (for example, 1.2.0).
• channels: Labels that place the version in an update graph (for example, stable or candidate).
• references: A map from each artifact type in spec.artifacts to an image tag or digest for that version.

The following example defines two versions in a linear chain:

apiVersion: flightctl.io/v1alpha1
kind: CatalogItem
metadata:
  name: <catalog-item-name>
  catalog: <catalog-name>
spec:
  type: container
  displayName: <human_readable_item_title>
  artifacts:
    - type: container
      uri: quay.io/<namespace>/<image>
  versions:
    - version: "1.0.0"
      channels:
        - stable
      references:
        container: "1.0.0"
    - version: "1.1.0"
      channels:
        - stable
      references:
        container: "1.1.0"
      replaces: "1.0.0"

Configuring application parameters with configSchema and defaultValues

A CatalogItem can declare a configSchema and a defaultValues map so that operators can customize application parameters when they deploy the item from the Software Catalog.

configSchema

A JSON Schema object that defines the parameters the application accepts, including their types, descriptions, and any validation constraints. When configSchema is present, the Software Catalog web console displays a Form view that renders a validated input form based on the schema.

The configSchema must be a subset of the flightctl API schema for the same application type. You can only define fields that exist in the flightctl API for that application type — for example, envVars or runAs for a Quadlet application. Fields that do not exist in the flightctl API schema are accepted but have no effect; the system does not act on them. For example, a top-level myField has no effect because it is not a recognized API field, whereas envVars.myField is valid because envVars is a recognized field that accepts arbitrary key-value pairs. If configSchema is not set, the generic flightctl API schema for that application type applies.

defaultValues

A key-value map of parameter names to pre-populated values. The console pre-fills form fields with these values so that operators do not need to enter common settings manually. Operators can override any pre-populated value before applying the configuration.

When an operator deploys the item, the submitted values are written into the corresponding application fields in the Device or Fleet specification.

The following example defines a configSchema with runAs and envVars parameters, and pre-populates default values using defaults.config:

apiVersion: flightctl.io/v1alpha1
kind: CatalogItem
metadata:
  name: <catalog-item-name>
  catalog: <catalog-name>
spec:
  type: container
  displayName: <human_readable_item_title>
  artifacts:
    - type: container
      uri: quay.io/<namespace>/<image>
  versions:
    - version: "1.0.0"
      channels:
        - stable
      references:
        container: "1.0.0"
  defaults:
    config:
      envVars:
        APP_MODE: production
        LOG_LEVEL: info
      runAs: flightctl
    configSchema:
      type: object
      properties:
        runAs:
          type: string
          title: Run as user
          description: "User identity under which the application runs. Use 'flightctl' for rootless (recommended) or 'root' to run as root."
          default: flightctl
          enum:
            - flightctl
            - root
        envVars:
          type: object
          title: Environment variables
          properties:
            APP_MODE:
              type: string
              title: Application mode
              description: "Operating mode for the application."
              default: production
              enum:
                - production
                - staging
                - debug
            LOG_LEVEL:
              type: string
              title: Log level
              description: "Log verbosity level."
              default: INFO
              enum:
                - DEBUG
                - INFO
                - WARN
                - ERROR

Defining upgrade paths

Flight Control models relationships between versions by using the Cincinnati update protocol. Optional fields on each version entry describe which upgrades are valid:

• replaces: The single previous version that this version follows in the main chain.
• skips: A list of older versions that can upgrade directly to this version, bypassing intermediate steps.
• skipRange: A semantic version range (for example, >=1.0.0 <1.2.0) of older versions that can upgrade directly to this version. Use skipRange when listing every skipped version explicitly would be unwieldy.

If you omit these fields, only the linear replaces chain (when present) defines one-step moves.

API version for catalog resources

Verifying synchronized catalogs on the CLI

After the ResourceSync reports a successful sync, you can list catalogs and items:

flightctl get catalogs
flightctl get catalogitems --catalog <catalog-name>

After synchronization completes, the catalog contents from the synchronized repository are available in the Software Catalog in Flight Control. For operator tasks in the console, see Using the Software Catalog in the Additional resources section. For image-build publication, see Publishing an image build to the Software Catalog in the Additional resources section.