Safely remove or update in-use catalog items

You can remove or update a catalog item version that is actively referenced by devices or fleets by first removing the references from all affected resources. Red Hat Edge Manager blocks deletion or modification of in-use catalog item versions.

Before you begin

  • You are logged in to the Flight Control CLI.
  • You have identified the catalog item version that you want to remove or update.

Procedure

  1. Identify the devices and fleets that reference the target catalog item.

    List devices that reference a specific catalog item:

    flightctl get devices -o json | jq -r \
  '.items[] | select(
    (.spec.os.catalogItemRef.item == "<catalog_item_name>") or
    (.spec.applications[]?.catalogItemRef.item == "<catalog_item_name>")
  ) | .metadata.name'

    List fleets that reference a specific catalog item:

    flightctl get fleets -o json | jq -r \
  '.items[] | select(
    (.spec.template.spec.os.catalogItemRef.item == "<catalog_item_name>") or
    (.spec.template.spec.applications[]?.catalogItemRef.item == "<catalog_item_name>")
  ) | .metadata.name'

    Replace <catalog_item_name> with the name of the catalog item that you want to remove or update. These commands output the names of the affected devices and fleets.

  2. For each affected device, update or remove the catalogItemRef field in the device specification.
    1. Export the device specification: 
      flightctl get device/<device_name> -o yaml > device_spec.yaml
    2. Edit device_spec.yaml to replace the catalogItemRef with a direct image reference, or to remove the catalog-sourced entry entirely.
    3. Apply the updated specification: 
      flightctl apply -f device_spec.yaml
    4. Verify that the catalogItemRef was removed from the device: 
      flightctl get device/<device_name> -o yaml
  3. For each affected fleet, update or remove the catalogItemRef field in the fleet device template.
    1. Export the fleet specification: 
      flightctl get fleet/<fleet_name> -o yaml > fleet_spec.yaml
    2. Edit fleet_spec.yaml to replace the catalogItemRef in the device template with a direct image reference, or to remove the catalog-sourced entry entirely.
    3. Apply the updated specification: 
      flightctl apply -f fleet_spec.yaml
    4. Verify that the catalogItemRef was removed from the fleet device template: 
      flightctl get fleet/<fleet_name> -o yaml
  4. After all references are removed, delete or modify the catalog item version.

    To delete a catalog item:

    flightctl delete catalogitem/<catalog_item_name> --catalog <catalog_name>

    To update a catalog item, edit the catalog item YAML definition and apply it:

    flightctl apply -f <catalog_item_file>.yaml

Results

  • Verify that the catalog item was deleted or updated successfully: 
    flightctl get catalogitems --catalog <catalog_name>

If you attempt to delete or modify a catalog item version that is still referenced by a device or fleet, the API returns an error similar to the following:

Error: catalog item version is actively referenced by one or more devices or fleets

To resolve this error, repeat steps 1 through 3 to identify and remove all remaining references before retrying the operation.

Note

If you update a device or fleet specification with a catalogItemRef that references a catalog item type incompatible with the specification context (for example, a system-category catalog item in spec.applications), the API rejects the request with a type-mismatch error. Verify that the catalog item type matches the target specification field.