Consolidating duplicate fleet definitions

Migrate from multiple near-identical fleet definitions to a single fleet that uses template placeholders and layered configuration to eliminate duplication.

Before you begin

  • You have the flightctl CLI installed.
  • You have at least two fleet definitions with overlapping configuration.
  • You have access to the Git repository that stores your device configuration.

Procedure

  1. Export fleet definitions and compare their configuration entries: 
    flightctl get fleets -o yaml > all-fleets.yaml

    Review the output and identify configuration entries that are identical or nearly identical across fleets. Note which entries differ and what dimension, such as region, device type, or site, drives the difference.

  2. Restructure the Git repository to separate shared configuration from per-dimension overrides. For example: 
    site-settings/
  config/
    base/
      motd.conf
      ntp.conf
    regions/
      eu-west/
        ntp.conf
      us-east/
        ntp.conf

    Move shared files to the base/ directory. Move files that vary by dimension into the corresponding override directories.

  3. Decide which device labels encode the varying dimensions. For each dimension that differs across your current fleets, assign a label key. For example, if fleets differ by region, use a region label with values such as eu-west and us-east.
  4. Label each device with the appropriate dimension values. Edit the device resource and add the required labels under metadata.labels: 
    flightctl edit device/<device_name>

    Alternatively, export the device definition, edit the YAML file, and apply it:

    flightctl get device/<device_name> -o yaml > device.yaml

    Edit device.yaml to add or update labels, then apply the changes:

    flightctl apply -f device.yaml
  5. Create a consolidated fleet definition that uses multiple gitRef entries with template placeholders: 
    apiVersion: flightctl.io/v1beta1
kind: Fleet
metadata:
  name: pos-terminals
spec:
  selector:
    matchLabels:
      type: pos-terminal
  template:
    metadata:
      labels:
        type: pos-terminal
    spec:
      os:
        image: quay.io/example/pos-rhel:9.5
      config:
        - name: base-config
          gitRef:
            repository: site-settings
            targetRevision: main
            path: /config/base
        - name: region-config
          gitRef:
            repository: site-settings
            targetRevision: main
            path: /config/regions/{{ .metadata.labels.region }}
  6. Select one device from each dimension and verify that the consolidated fleet delivers the correct rendered configuration. All config providers are merged into a single rendered configuration. Review the rendered spec to confirm that files from both the base and override layers are present: 
    flightctl get device/<device_name> --rendered -o json | jq '.spec.config'
  7. Update device labels so that devices match the consolidated fleet selector and no longer match the old fleet selectors. Devices automatically leave their old fleet and join the new fleet when their labels match the new selector.
    Important

    If a device temporarily matches selectors for both an old fleet and the new fleet, Red Hat Edge Manager sets the MultipleOwners condition to true on the device. The device remains in its current fleet until the conflicting selector is resolved. Delete old fleet definitions or adjust their selectors to avoid this overlap.
  8. After all devices have migrated to the consolidated fleet and you have verified their status, delete the old fleet definitions: 
    flightctl delete fleet/<old_fleet_name>

Results

  • Run flightctl get devices -l 'type=pos-terminal' and verify that all devices show the expected OWNER value, which is the consolidated fleet name.
  • Run flightctl get device/<device_name> -o yaml for a device from each dimension and verify the rendered configuration matches expectations.
  • Check that no devices have the MultipleOwners condition set to true: 
    flightctl get devices -o json | jq '.items[] | select(.status.conditions[]? | select(.type=="MultipleOwners" and .status=="True")) | .metadata.name'