Procedure

1. Choose one of the following recovery options and complete the associated steps:

   Option A: Separate image-mode and package-mode devices into different fleets.

   Use this option when you want to apply OS image targets to image-mode devices while managing package-mode devices with a separate fleet template that does not include OS image settings.

   1. Label your devices to distinguish OS modes. For each device, export the current manifest, add a label, and apply the change. In the following example, replace <device_name> with the name of each device:

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

      Copy code to clipboard

      Edit device.yaml to add an osMode label under metadata.labels:

      metadata:
        labels:
          osMode: image

      Copy code to clipboard

      Set osMode to image for image-mode devices or package for package-mode devices.

      Apply the updated manifest:

      flightctl apply -f device.yaml

      Copy code to clipboard
   2. Create separate fleets with matching label selectors. The image-mode fleet includes the OS image target in its template. The package-mode fleet template includes only configuration and application workloads.

   Option B: Remove the OS image target from the fleet template.

   Use this option when OS management is handled per-device or through external tooling, and you want all devices in the fleet to receive only configuration and application specs.

   1. Edit the fleet spec and remove the spec.os.image field from the device template.

   2. Apply the updated fleet spec:

      flightctl apply -f <fleet_spec>.yaml

      Copy code to clipboard

      Replace <fleet_spec> with the path to your fleet spec file.

   Option C: Move package-mode devices out of the fleet.

   Use this option when most devices in the fleet are image-mode and you want to keep the OS image target in the fleet template.

   1. Update device labels so that package-mode devices no longer match the fleet selector. Export the device manifest, edit the labels, and apply the change:

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

      Copy code to clipboard

      Edit device.yaml to change or add labels so that the device no longer matches the fleet label selector, then apply:

      flightctl apply -f device.yaml

      Copy code to clipboard

Procedure

1. Run the following command to verify that the label selector returns the devices that you want to add to the fleet:

   flightctl get devices -l 'type=pos-terminal,stage=development'

   Copy code to clipboard

2. If running the command returns the expected list of devices, you can define a fleet that selects the devices by using the following YAML file:

   apiVersion: flightctl.io/v1beta1
   kind: Fleet
   metadata:
     name: my-fleet
   spec:
     selector:
       matchLabels:
         type: pos-terminal
         stage: development
   # ...

   Copy code to clipboard

3. Apply the change by running the following command:

   flightctl apply -f my-fleet.yaml

   Copy code to clipboard

4. Check that no devices in the fleet have overlapping selectors by running the following command:

   flightctl get devices -l 'type=pos-terminal,stage=development' -o json | jq -r '.items[].status.conditions[] | select(.type=="MultipleOwners").status'

   Copy code to clipboard

   If the output shows False for each device, no other fleet selects the same devices. If any device shows True, review your fleet selectors to remove the overlap.

   Additional resources

   • Example: fleet selection from system information

Procedure

1. Add the acm-crd resource configuration, which includes the filePath for your crd.yaml file, your repository, and suffix to your Fleet resource. See the following example:

   apiVersion: flightctl.io/v1beta1
   kind: Fleet
   metadata:
     name: fleet-acm
   spec:
     selector:
       matchLabels:
         fleet: acm
     template:
       spec:
         os:
           image: <your_os_image>
         config:
           - name: acm-crd
             httpRef:
               filePath: /var/local/acm-import/crd.yaml
               repository: acm-registration
               suffix: /agent-registration/crds/v1

   Copy code to clipboard

2. Add the acm-import resource configuration with the filePath, repository, and suffix, as shown in the following example:

         config:
           - name: acm-import
             httpRef:
               filePath: /var/local/acm-import/import.yaml
               repository: acm-registration
               suffix: /agent-registration/manifests/{{.metadata.name}}

   Copy code to clipboard

3. MicroShift must authenticate to the container registries that host the Red Hat Advanced Cluster Management images. If the device already has a suitable pull secret for those registries (for example, at /etc/crio/openshift-pull-secret), you do not need to add another one here. Otherwise, add the pull-secret resource, as you see in the following addition to the template:

         config:
           - name: pull-secret
             inline:
               - path: "/etc/crio/openshift-pull-secret"
                 content: "{\"auths\":{...}}"

   Copy code to clipboard

4. Add the apply-acm-manifests resource. The following hook waits until the kubeadmin kubeconfig file exists and MicroShift pods are ready, then runs kubectl apply on your crd.yaml and import.yaml files when those files are created. The afterupdating hook fires both when a device first joins the fleet and receives its initial configuration, and on subsequent updates.

   Include the wait steps because MicroShift might not be running when the hook runs. For example, you might apply an operating system image update and this registration configuration together in a single device update. See the following example:

         config:
           - name: apply-acm-manifests
             inline:
               - path: "/etc/flightctl/hooks.d/afterupdating/50-acm-registration.yaml"
                 content: |
                   - run: /usr/bin/bash -c "until [ -f $KUBECONFIG ]; do sleep 1; done"
                     timeout: 5m
                     envVars:
                       KUBECONFIG: /var/lib/microshift/resources/kubeadmin/kubeconfig
                   - run: kubectl wait --for=condition=Ready pods --all --all-namespaces --timeout=300s
                     timeout: 5m
                     envVars:
                       KUBECONFIG: /var/lib/microshift/resources/kubeadmin/kubeconfig
                   - if:
                     - path: /var/local/acm-import/crd.yaml
                       op: [created]
                     run: kubectl apply -f /var/local/acm-import/crd.yaml
                     envVars:
                       KUBECONFIG: /var/lib/microshift/resources/kubeadmin/kubeconfig
                   - if:
                     - path: /var/local/acm-import/import.yaml
                       op: [created]
                     run: kubectl apply -f /var/local/acm-import/import.yaml
                     envVars:
                       KUBECONFIG: /var/lib/microshift/resources/kubeadmin/kubeconfig

   Copy code to clipboard

   Auto-registration uses the Red Hat Advanced Cluster Management agent registration API: devices fetch the Kubernetes manifests for the klusterlet agent and apply them to MicroShift. The resources under spec.template.spec.config in your fleet template do the following:

   • acm-crd uses the HTTP configuration provider to query the agent registration server for manifests that contain the custom resource definition for the Red Hat Advanced Cluster Management klusterlet agent. The Red Hat Edge Manager agent writes those manifests to /var/local/acm-import/crd.yaml on each device.
   • acm-import queries the server for import manifests for a cluster whose name matches the device. The {{.metadata.name}} template variable supplies the device name. The agent writes the returned manifests to /var/local/acm-import/import.yaml.
   • pull-secret adds registry credentials on the device so that MicroShift can pull the Red Hat Advanced Cluster Management agent images. Skip this item if you already provide a suitable pull secret by another method, for example by embedding it in the operating system image or by using another configuration provider.
   • apply-acm-manifests adds an afterupdating lifecycle hook rule file under /etc/flightctl/hooks.d/afterupdating/. The hook runs after the configuration is applied and the crd.yaml and import.yaml files exist; it applies those manifests to MicroShift by using kubectl. For more information, see Device lifecycle hooks.

5. In the console, label the device fleet:acm and click Approve, which automatically selects the fleet-acm fleet. For more information about labels on devices, see Labels and label selectors.

   Additional resources

   • Configuring your device
   • Device lifecycle hooks
   • Labels and label selectors

Procedure

1. Export fleet definitions and compare their configuration entries:

   flightctl get fleets -o yaml > all-fleets.yaml

   Copy code to clipboard

   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

   Copy code to clipboard

   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>

   Copy code to clipboard

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

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

   Copy code to clipboard

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

   flightctl apply -f device.yaml

   Copy code to clipboard

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 }}

   Copy code to clipboard

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'

   Copy code to clipboard

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>

   Copy code to clipboard