Migrate label-based catalog references

When you upgrade Red Hat Edge Manager from a previous version, the upgrade process automatically migrates label-based catalog references to the catalogItemRef field in Device and Fleet specifications.

Before you begin

  • You have administrator access to the Red Hat Edge Manager service.
  • You have the flightctl CLI installed and configured.
  • You are planning an upgrade from a previous version of Red Hat Edge Manager.

Procedure

  1. Pre-upgrade: Identify devices and fleets with label-based catalog references.

    List devices with operating system catalog labels:

    flightctl get devices -l "os.catalog.flightctl.io/catalog" -o yaml

    List devices with application catalog labels:

    flightctl get devices -l "apps.catalog.flightctl.io/catalog" -o yaml

    List fleets with operating system catalog labels:

    flightctl get fleets -l "os.catalog.flightctl.io/catalog" -o yaml

    List fleets with application catalog labels:

    flightctl get fleets -l "apps.catalog.flightctl.io/catalog" -o yaml

    Record the device and fleet names so you can verify them after the upgrade.

  2. Pre-upgrade: Run a dry-run migration to validate the migration without committing changes. 
    flightctl-db-migrate --dry-run

    Review the dry-run output to identify any catalog references that cannot be migrated. The dry-run validates all migration steps and reports errors without modifying the database.

  3. Perform the upgrade.

    Follow the standard upgrade procedure for your deployment type (OpenShift Helm chart or standalone). The database migration runs automatically during the upgrade and converts label-based catalog references to catalogItemRef fields.

  4. Post-upgrade: Verify that catalogItemRef fields are populated on previously catalog-associated devices.

    For each device that you recorded in step 1, check that the specification contains a catalogItemRef field:

    flightctl get device/<device_name> -o yaml

    Look for the catalogItemRef field in spec.os or spec.applications. A successful migration replaces the label-based association with the corresponding catalogItemRef values.

  5. Post-upgrade: Identify devices or fleets where the migration did not populate a catalogItemRef field.

    Compare the list of devices and fleets from step 1 with the verification results from step 4. If a device or fleet that previously had label-based catalog references does not have a catalogItemRef field, the migration could not convert that reference.

  6. Manually remediate any references that were not migrated by applying the catalogItemRef field.
    1. Export the device or fleet specification: 
      flightctl get device/<device_name> -o yaml > device_spec.yaml
    2. Add the appropriate catalogItemRef field to the specification. For example, for an operating system image: 
      spec:
  os:
    catalogItemRef:
      catalog: <catalog_name>
      item: <os_image_item_name>
      version: "<version>"
      channel: "<channel (optional)>"

      For an application catalog item:

      spec:
  applications:
  - name: <application_name>
    appType: container
    catalogItemRef:
      catalog: <catalog_name>
      item: <app_item_name>
      version: "<version>"
      channel: "<channel (optional)>"
    3. Apply the updated specification: 
      flightctl apply -f device_spec.yaml

Results

  • Verify that all previously catalog-associated devices have a catalogItemRef field by running: 
    flightctl get devices -o yaml | grep -c "catalogItemRef"

    The count should match the number of devices that had label-based catalog references before the upgrade.