Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

Chapter 1. Managing devices

You can manage your devices individually or in a fleet. The Red Hat Edge Manager allows you to manage a whole fleet of devices as a single object instead of managing many devices individually.

You only need to specify the desired configuration once and then the Red Hat Edge Manager applies the configuration to all devices in the fleet.

Understanding individual device management is the foundation for managing devices in a fleet. You might want to manage your devices individually in the following scenarios:

  • If a few devices have significantly different configurations.
  • If you use external automation for updating the devices.

Required access: Cluster administrator

The following documentation focuses on managing individual devices:

To learn more about managing your devices in a fleet, see Managing device fleets.

1.1. Enrolling devices
Copiar o link

To manage your devices with Red Hat Edge Manager, you must enroll the devices to the Red Hat Edge Manager service.

The first time Red Hat Edge Manager agents runs on a device, the agent prepares for the enrollment process by generating a cryptographic key pair. The cryptographic key pair of the device consists of a public and a private key. The private key never leaves the device, so that the device cannot be duplicated or impersonated. The key pair is registered with the Red Hat Edge Manager service during enrollment and is deleted during decommissioning of the device.

When the device is not yet enrolled, the agent performs service discovery to find its Red Hat Edge Manager service instance. Then, the device establishes a secure, mTLS-protected network connection to the service. The device uses its X.509 enrollment certificate that the device acquired during image building or device provisioning. The device submits an enrollment request to the service that includes the following:

  • a description of the device hardware and operating system
  • an X.509 Certificate Signing Request which includes the cryptographic identity of the device to obtain the initial management certificate

The device is not considered trusted and remains quarantined in a device lobby until an authorized user approves or denies the request.

For more information, read the following sections:

1.1.1. Prerequisites
Copiar o link

1.1.2. Enrolling devices using the Flight Control CLI
Copiar o link

You must enroll devices into the Red Hat Edge Manager service before you can manage them. Complete the following steps:

  1. List all devices that are currently waiting for approval by running the following command: 

    flightctl get enrollmentrequests --field-selector="status.approval.approved != true"

    See the following example output: 

    NAME           APPROVAL  APPROVER  APPROVED LABELS
<device_name>  Pending   <none>    <none>

    Note: The unique device name is generated by the agent and cannot be changed. The agent chooses a base32-encoded hash of its public key as device name.

  2. Approve an enrollment request by specifying the name of the enrollment request. Optionally, you can add labels to the device by using the --label or -l flags. See the following example: 

    flightctl approve -l region=eu-west-1 -l site=factory-berlin enrollmentrequest/54shovu028bvj6stkovjcvovjgo0r48618khdd5huhdjfn6raskg

    See the following example output: 

    NAME           APPROVAL  APPROVER  APPROVED LABELS
<device_name>  Approved  user      region=eu-west-1,site=factory-berlin

After you approve the enrollment request, the service issues the management certificate and registers the device in the inventory. The device is now ready to be managed.

1.2. Viewing devices
Copiar o link

To obtain more information about the devices in your inventory, you can use the Flight Control CLI.

1.2.1. Prerequisites
Copiar o link

1.2.2. View device inventory and device details
Copiar o link

View devices in your device inventory. Complete the following steps:

  1. View the devices in the device inventory by running the following command: 

    flightctl get devices

    See the following example output: 

    NAME           ALIAS    OWNER   SYSTEM  UPDATED     APPLICATIONS  LAST SEEN
<device_name>  <none>   <none>  Online  Up-to-date  <none>        3 seconds ago

  2. View the details of this device in YAML format by running the following command: 

    flightctl get device/<device_name> -o yaml

    See the following example output: 

    apiVersion: flightctl.io/v1alpha1
kind: Device
metadata:
  name: <device_name>
  labels:
    1 
    
    region: eu-west-1
    site: factory-berlin
spec:
  os:
    image: quay.io/flightctl/rhel:9.5
    2 
    
  config:
    - name: my-os-configuration
    3 
    
      gitRef:
        path: /configuration
        repository: my-configuration-repo
        targetRevision: production
status:
  os:
    image: quay.io/flightctl/rhel:9.5
    4 
    
  config:
    renderedVersion: "1"
    5 
    
  applications: []
    6 
    
  applicationsSummary:
    status: Unknown
    7 
    
  resources:
    8 
    
    cpu: Healthy
    disk: Healthy
    memory: Healthy
  systemInfo:
    9 
    
    architecture: amd64
    bootID: 037750f7-f293-4c5b-b06e-481eef4e883f
    operatingSystem: linux
  summary:
    info: ""
    status: Online
    10 
    
  updated:
    status: UpToDate
    11 
    
[...]
    1
    User-defined labels assigned to the device.
    2
    The target OS image version of the device.
    3
    The target OS configuration of the device.
    4
    The current OS image version of the device
    5
    The current OS configuration version of the device.
    6
    The current list of deployed applications on the device (array of application status objects). This includes both Podman-based applications (quadlet, container) and Helm applications deployed to MicroShift; all application types report status in the same format.
    7
    The health status summary of all applications on the device.
    8
    The availability of CPU, disk, and memory resources.
    9
    Basic system information.
    10
    The health status of the device.
    11
    The update status of the device. See Section 1.2.3, “Device update status and update state” for possible values.

1.2.3. Device update status and update state
Copiar o link

The status.updated.status field indicates whether the device’s running OS and configuration match the device spec. It can have the following values:

Expand
ValueDescription

UpToDate

The device matches its device spec (and, if in a fleet, the fleet template version).

Updating

The device is currently applying an update.

OutOfDate

The device is not updating and does not match its device spec, or (if in a fleet) is not yet on the fleet template version.

Unknown

The agent has not reported status, or the last reported status was Updating and the device has been disconnected since.

When an update is in progress, status.conditions includes an Updating condition whose reason field indicates the current phase. After a failed update and rollback, the reason is Error; the device has returned to the previous OS version and the agent will not retry that failed version automatically. The following update states can appear:

Expand
Update stateDescription

Preparing

The agent is validating the spec and downloading dependencies.

ReadyToUpdate

Dependencies are ready; the agent has not yet applied changes.

ApplyingUpdate

The agent is writing the update to disk.

Rebooting

The device is rebooting to activate the new OS or configuration.

RollingBack

The agent detected a failure and is rolling back to the previous OS and configuration.

Updated

The update completed successfully.

Error

The update failed. The device has rolled back to the pre-update version and will not automatically retry the failed version.

The status.updated.info field may contain a short message about the last transition. For troubleshooting a rollback or failed update, see Troubleshooting OS update rollback.

1.3. Labels and label selectors
Copiar o link

You can organize your resources, including individual devices, fleets and any other resources, by assigning them labels. For example, you can use labels to record location, hardware type, or purpose. The Red Hat Edge Manager labels follow the same syntax, principles, and operators as Kubernetes labels and label selectors.

You can select devices with labels when viewing the device inventory or applying operations to the devices.

Labels follow the key=value format, where you want to use the key to group devices. For example, if your labels follow the site=<location> naming convention, you can group your devices by site.

You can also use labels that only consist of keys.

Labels must adhere to the following rules to be valid:

  • Keys and value must each be 63 characters or less.
  • Keys and values can consist of alphanumeric characters (a-z, A-Z, 0-9).
  • Keys and values can also contain dashes (-), underscores (_), dots (.) but not as the first or last character.
  • Value can be omitted.

You can apply labels to resources in the following ways:

  • Define a set of default labels during image building that are automatically applied to all devices during deployment.
  • Assign initial labels during enrollment.
  • Assign labels post-enrollment.

When resources are labeled, you can select a subset of resources by writing a label selector. A label selector is a comma-separated list of labels for selecting resources that have the same set of labels.

See the following examples:

Expand
Example label selectorSelected devices

site=factory-berlin

All devices with a site label key and a factory-berlin label value.

site!=factory-berlin

All devices with a site label key but where the label value is not factory-berlin.

site in (factory-berlin,factory-madrid)

All devices with a site label key and where the label value is either factory-berlin or factory-madrid.

For more information, see Labels and Selectors.

1.4. Using labels
Copiar o link

You can organize your devices by using labels.

1.4.1. Viewing devices and their labels using the Flight Control CLI
Copiar o link

View devices and their associated labels. You can use labels to organize your devices and device fleets.

Complete the following steps:

  1. View devices in your inventory by using the -o wide option: 

    flightctl get devices -o wide

    See the following example output: 

    NAME            ALIAS    OWNER   SYSTEM  UPDATED     APPLICATIONS  LAST SEEN      LABELS
<device1_name>  <none>   <none>  Online  Up-to-date  <none>        3 seconds ago  region=eu-west-1,site=factory-berlin
<device2_name>  <none>   <none>  Online  Up-to-date  <none>        1 minute ago   region=eu-west-1,site=factory-madrid

  2. View devices in your inventory with a specific label or set of labels by using the -l <key=value> option: 

    flightctl get devices -l site=factory-berlin -o wide

    See the following example output: 

    NAME            ALIAS    OWNER   SYSTEM  UPDATED     APPLICATIONS  LAST SEEN      LABELS
<device1_name>  <none>   <none>  Online  Up-to-date  <none>        3 seconds ago  region=eu-west-1,site=factory-berlin

1.4.2. Updating labels using the CLI
Copiar o link

Update labels on your devices using the CLI. Complete the following steps:

  1. Export the current definition of the device into a file by running the following command: 

    flightctl get device/<device1_name> -o yaml > my_device.yaml

  2. Use your preferred editor to edit the my_device.yaml file. See the following example: 

    apiVersion: flightctl.io/v1alpha1
kind: Device
metadata:
  labels:
    some_key: some_value
    some_other_key: some_other_value
  name: <device1_name>
spec:
[id="..."]

  3. Save the file and apply the updated device definition by running the following command: 

    flightctl apply -f my_device.yaml

  4. Verify that the changes are applied by running the following command 

    NAME            ALIAS    OWNER   SYSTEM  UPDATED     APPLICATIONS  LAST SEEN      LABELS
<device1_name>  <none>   <none>  Online  Up-to-date  <none>        3 minutes ago  some_key=some_value,some_other_key=some_other_value
<device2_name>  <none>   <none>  Online  Up-to-date  <none>        4 minutes ago  region=eu-west-1,site=factory-madrid

1.5. Field selectors
Copiar o link

Field selectors filter a list of Red Hat Edge Manager resources, including individual devices, fleets and any other resources, based on specific resource field values.

Field selectors follow the same syntax, principles, and operators as Kubernetes field and label selectors with additional operators available for more advanced search use cases.

1.5.1. Supported fields
Copiar o link

The Red Hat Edge Manager resources give a set of metadata fields that you can select.

Each resource supports the following metadata fields:

  • metadata.name
  • metadata.owner
  • metadata.creationTimestamp

Note: To query labels, use label selectors for advanced and flexible label filtering.

For more information, see Labels and label selectors.

1.5.2. List of additional supported fields
Copiar o link

In addition to the metadata fields, each resource has its own unique set of fields that you can select, offering further flexibility in filtering and selection based on resource-specific attributes.

The following table lists the fields supported for filtering for each resource kind:

Expand

Kind

Fields

Certificate Signing Request

status.certificate

Device

status.summary.status

status.applicationsSummary.status

status.updated.status

status.lifecycle.status

Enrollment Request

status.approval.approved

status.certificate

Fleet

spec.template.spec.os.image

Repository

spec.type

spec.url

Resource Sync

spec.repository

For Device resources, status.updated.status can be one of: UpToDate, Updating, OutOfDate, or Unknown. After a failed OS update and rollback, a device is typically OutOfDate (running the previous version). For more information, see Device update status and update state.

1.5.3. Field discovery
Copiar o link

Some Red Hat Edge Manager resources might expose additional supported fields. You can discover the supported fields by using the flightctl command with the --field-selector option. If you try to use an unsupported field, the error message lists the available supported fields.

See the following examples: 

flightctl get device --field-selector='text'
 
Error: listing devices: 400, message: unknown or unsupported selector: unable to resolve selector name "text". Supported selectors are: [metadata.alias metadata.creationTimestamp metadata.name metadata.nameOrAlias metadata.owner status.applicationsSummary.status status.lifecycle.status status.summary.status status.updated.status]

The field text is not a valid field for filtering. The error message provides a list of supported fields that you can use with --field-selector for the Device resource.

You can then use one of the supported fields: 

flightctl get devices --field-selector 'metadata.alias contains cluster'

The metadata.alias field is checked with the containment operator contains to see if it has the value cluster.

1.5.3.1. Examples
Copiar o link

Excluding a specific device by name

The following command filters out a specific device by its name: 

flightctl get devices --field-selector 'metadata.name!=<device_name>'

Filter by owner, labels, and creation timestamp

The following command retrieves devices that are owned by Fleet/pos-fleet, are located in the us region, and are created in 2024: 

flightctl get devices --field-selector 'metadata.owner=Fleet/pos-fleet, metadata.creationTimestamp >= 2024-01-01T00:00:00Z, metadata.creationTimestamp < 2025-01-01T00:00:00Z' -l 'region=us'

Filter by owner, labels, and device status

The following command retrieves devices that are owned by Fleet/pos-fleet, are located in the us region, and have a status.updated.status of either Unknown or OutOfDate: 

flightctl get devices --field-selector 'metadata.owner=Fleet/pos-fleet, status.updated.status in (Unknown, OutOfDate)' -l 'region=us'

1.5.4. Supported operators
Copiar o link

Expand

Operator

Symbol

Description

Exists

--field-selector <field>

Checks if a field exists. For example, the --field-selector 'metadata.owner' field selector returns resources that have the metadata.owner field.

DoesNotExist

!

Checks if a field does not exist.

Equals

=

Checks if a field is equal to a value.

DoubleEquals

==

Another form of equality check.

NotEquals

!=

Checks if a field is not equal to a value.

GreaterThan

>

Checks if a field is greater than a value.

GreaterThanOrEquals

>=

Checks if a field is greater than or equal to a value.

LessThan

<

Checks if a field is less than a value.

LessThanOrEquals

⇐

Checks if a field is less than or equal to a value.

In

in

Checks if a field is within a list of values.

NotIn

notin

Checks if a field is not in a list of values.

Contains

contains

Checks if a field has a value.

NotContains

notcontains

Checks if a field does not contain a value.

1.5.5. Operators usage by field type
Copiar o link

Each field type supports a specific subset of operators:

Expand

Field Type

Supported Operators

Value

String

Equals: Matches if the field value is an exact match to the specified string.

DoubleEquals: Matches if the field value is an exact match to the specified string. Alternative to Equals.

NotEquals: Matches if the field value is not an exact match to the specified string.

In: Matches if the field value matches at least one string in the list.

NotIn: Matches if the field value does not match any of the strings in the list.

Contains: Matches if the field value has the specified substring.

NotContains: Matches if the field value does not contain the specified substring.

Exists: Matches if the field is present.

DoesNotExist: Matches if the field is not present.

Text string

Timestamp

Equals: Matches if the field value is an exact match to the specified timestamp.

DoubleEquals: Matches if the field value is an exact match to the specified timestamp. Alternative to Equals.

NotEquals: Matches if the field value is not an exact match to the specified timestamp.

GreaterThan: Matches if the field value is after the specified timestamp.

GreaterThanOrEquals: Matches if the field value is after or equal to the specified timestamp.

LessThan: Matches if the field value is before the specified timestamp.

LessThanOrEquals: Matches if the field value is before or equal to the specified timestamp.

In: Matches if the field value matches at least one timestamp in the list.

NotIn: Matches if the field value does not match any of the timestamps in the list.

Exists: Matches if the field is present.

DoesNotExist: Matches if the field is not present.

RFC 3339 format

Number

Equals: Matches if the field value equals the specified number.

DoubleEquals: Matches if the field value equals the specified number. Alternative to Equals.

NotEquals: Matches if the field value does not equal to the specified number.

GreaterThan: Matches if the field value is greater than the specified number.

GreaterThanOrEquals: Matches if the field value is greater than or equal to the specified number.

LessThan: Matches if the field value is less than the specified number.

LessThanOrEquals: Matches if the field value is less than or equal to the specified number.

In: Matches if the field value equals at least one number in the list.

NotIn: Matches if the field value does not equal any numbers in the list.

Exists: Matches if the field is present.

DoesNotExist: Matches if the field is not present.

Number format

Boolean

Equals: Matches if the value is true or false.

DoubleEquals: Matches if the value is true or false. Alternative to Equals.

NotEquals: Matches if the value is the opposite of the specified value.

In: Matches if the value, true or false, is in the list. The list can only contain true or false, so this operator is limited in use.

NotIn: Matches if the value is not in the list.

Exists: Matches if the field is present.

DoesNotExist: Matches if the field is not present.

Boolean format (true, false)

Array

Contains: Matches if the array has the specified value.

NotContains: Matches if the array does not contain the specified value.

In: Matches if the array overlaps with the specified values.

NotIn: Matches if the array does not overlap with the specified values. Exists: Matches if the field is present.

DoesNotExist: Matches if the field is not present.

Array element

1.6. Updating the operating system
Copiar o link

You can update the operating system of a device by updating the target operating system image name or version in the device specification. Alternatively, you can choose an OS image from the Software Catalog in the Flight Control web console and install or update from there without entering an OCI image reference manually.

Catalog-driven OS updates follow the upgrade graph that your administrator publishes for that image (allowed versions and transitions), as described in Validated upgrade paths and compatibility.

When the Red Hat Edge Manager agent communicates with the service, the agent detects the requested update. Then, the agent automatically starts downloading and verifying the new operating system version in the background.

The Red Hat Edge Manager agent schedules the actual system update according to the update policy. At the scheduled update time, the agent installs the new version without disrupting the currently running operating system.

Finally, the device reboots into the new version.

If the new OS version fails health checks after reboot, the device automatically rolls back to the previous working version. During a failed update, the device may reboot several times (greenboot retries) before the rollback completes; multiple reboots in quick succession are expected and do not indicate a separate problem. No manual intervention is required. For more information, see Automatic rollback when an OS update fails and Troubleshooting OS update rollback.

The Red Hat Edge Manager currently supports the following image type and image reference format:

Expand

Image Type

Image Reference

bootc

An OCI image reference to a container registry. Example: quay.io/flightctl-example/rhel:9.5

During the process, the agent sends status updates to the service. You can monitor the update process by viewing the device status. For more information, see Viewing devices.

1.6.1. Updating the operating system of a device using the Flight Control CLI
Copiar o link

To update the operating system of a device using the flightctl, complete the following steps:

  1. Get the current resource manifest of the device by running the following command: 

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

  2. Edit the Device resource to specify the new operating system name and version target. 

    apiVersion: flightctl.io/v1alpha1
kind: Device
metadata:
  name: <device_name>
spec:
[id="..."]
  os:
    image: quay.io/flightctl/rhel:9.5
[id="..."]

  3. Apply the updated Device resource by running the following command: 

    flightctl apply -f <device_name>.yaml

1.7. Automatic rollback when an OS update fails
Copiar o link

Red Hat Edge Manager uses greenboot integration to provide autonomous failed upgrade recovery. When an OS update fails after reboot (for example, the new OS image fails health checks—such as the agent not becoming active in time or entering a crash loop), the device automatically rolls back to the previous working OS version. No manual intervention is required.

1.7.1. greenboot rollback operations
Copiar o link

When an OS update fails health checks after reboot, greenboot performs rollback through the following sequence:

  1. Deployment and reboot: The agent deploys the new OS image to the device and triggers a reboot.
  2. Health check initiation: After the device comes back up, greenboot runs the flightctl health check. This check has two phases: it waits up to 150 seconds for flightctl-agent.service to become active, then monitors service stability for 60 seconds to detect crash loops. A rollback is triggered if the agent does not become active in time or if it restarts (crash-loops) during the stability window.
  3. Retries and configuration: If health checks fail, greenboot reboots and retries. By default, three retries occur before a rollback is performed. To change this threshold, update the GREENBOOT_MAX_BOOTS value in /etc/greenboot/greenboot.conf.
  4. Triggering the rollback: Once all retry attempts are exhausted, greenboot reverts to the previous OS deployment and reboots the device.
  5. Reporting: The device starts on the previous OS version, and the agent reports the rollback to the Red Hat Edge Manager service.
  6. Version exclusion: That specific OS version is recorded as failed, ensuring the agent skips it during all future reconciliations.
Note

Red Hat Edge Manager automatically disables third-party greenboot health check scripts to ensure that only the Red Hat Edge Manager agent health check controls rollback decisions. The flightctl-configure-greenboot service runs before greenboot-healthcheck on every boot and disables scripts such as MicroShift’s 40_microshift_running_check.sh; only core greenboot scripts and the flightctl health check are preserved. Do not manually edit DISABLED_HEALTHCHECKS in /etc/greenboot/greenboot.conf; it is replaced on every boot.

Note

On systems not using a bootc or OSTree-based image, health checks still run on each boot, but rollback is not possible if an update fails. The device does not revert to a previous OS version in that case.

During the retry phase, the device may reboot multiple times before the final rollback. This is expected behavior, not a separate problem.

This keeps devices operational and avoids repeated failed update attempts.

1.7.2. When automatic rollback applies
Copiar o link

Automatic rollback is available for devices that use image-based operating systems (such as bootc images) with greenboot enabled. For more information about image-based OS and transactional updates, see Operating system images for the Red Hat Edge Manager.

1.7.3. Observing rollback and update status
Copiar o link

You can see whether a device rolled back or is in a failed-update state by viewing the device status. The status.updated.status field indicates whether the device is up to date, updating, or out of date. When an update fails and rollback completes, the update state is reported as Error and the device returns to the previous OS version. For details, see Device update status and update state.

If a device has rolled back or you need to diagnose a failed update, see Troubleshooting OS update rollback.

1.8. Operating system configuration for edge devices
Copiar o link

You can include an operating system-level host configuration in the image to provide maximum consistency and repeatability.

To update the configuration, you create a new operating system image and update devices with the new image.

However, updating devices with a new image can be impractical in the following cases:

  • The configuration is missing in the image.
  • The configuration needs to be specific to a device.
  • The configuration needs to be updateable at runtime without updating the operating system image and rebooting.

For these cases, you can declare a set of configuration files that is present on the file system of the device. The Red Hat Edge Manager agent applies updates to the configuration files while ensuring that either all files are successfully updated in the file system, or rolled back to their pre-update state. If the user updates both an operating system and configuration set of a device at the same time, the Red Hat Edge Manager agent updates the operating system first, then applies the specified set of configuration files.

You can also specify a list of configuration sets that the Red Hat Edge Manager agent applies in sequence. In case of a conflict, the last applied configuration set is valid.

Important: After the Red Hat Edge Manager agent updates the configuration on the disk, the running applications need to reload the new configuration into memory for the configuration to become effective. If the update involves a reboot, systemd automatically restarts the applications with the new configuration and in the correct order. If the update does not involve a reboot, many application can detect changes to their configuration files and automatically reload the files. When an application does not support change detection, you can use device lifecycle hooks to run scripts or commands if certain conditions are met.

1.8.1. Configuration providers
Copiar o link

You can provide configuration from multiple sources, called configuration providers, in Red Hat Edge Manager. The Red Hat Edge Manager currently supports the following configuration providers: A repository used by a provider must be set up once and can then be used for multiple devices or fleets.

Git Config Provider
Fetches device configuration files from a Git repository.
Kubernetes Secret Provider
Fetches a secret from a Kubernetes cluster and writes the content to the file system of the device.
HTTP Config Provider
Fetches device configuration files from an HTTP(S) endpoint.
Inline Config Provider
Allows specifying device configuration files inline in the device manifest without querying external systems.

Read more about the configuration providers in the following sections:

1.8.1.1. Configuration from a Git repository
Copiar o link

You can store device configuration in a Git repository such as GitHub or GitLab. You can then add a Git Config Provider so that the Red Hat Edge Manager synchronizes the configuration from the repository to the file system of the device.

The Git Config Provider takes the following parameters:

Expand

Parameter

Description

Repository

The name of a Repository resource defined in the Red Hat Edge Manager.

TargetRevision

The branch, tag, or commit of the repository to checkout.

Path

The absolute path to the directory in the repository from which files and subdirectories are synchronized to the file system of the device. The Path directory corresponds to the root directory (/) on the device, unless the MountPath parameter is specified.

MountPath

Optional. The absolute path to the directory in the file system of the device to write the content of the repository to. By default, the value is the file system root (/).

The Repository resource defines the Git repository, the protocol and access credentials that the Red Hat Edge Manager must use. After the repository is set up, you can use it to configure individual devices or device fleets.

1.8.1.2. Secrets from a Kubernetes cluster
Copiar o link

The Red Hat Edge Manager can query only the Kubernetes cluster that the Red Hat Edge Manager is running on for a Kubernetes secret. The content of that secret can be written to a path on the device file system.

Note

You can manage Kubernetes Secret Provider configurations via the CLI or API. Kubernetes Secret Provider configurations are displayed in the UI as read-only.

The Kubernetes Secret Provider takes the following parameters:

Expand

Parameter

Description

Name

The name of the secret.

Namespace

The namespace of the secret.

MountPath

The directory in the file system of the device to write the secret contents to.

To apply a Kubernetes secret to a device, add a config entry with secretRef to the device specification and apply it with the CLI (or API):

Example: Device spec with secretRef

spec:
  config:
    - name: my-secret
      secretRef:
        name: my-secret-name
1 

        namespace: my-secret-namespace
2 

        mountPath: /etc/my-secret
3

1
The name of your Kubernetes secret.
2
The namespace where the secret is stored.
3
The target path on the device to write the secret contents to.

Run flightctl apply -f <file>.yaml to apply the device or fleet manifest.

The Red Hat Edge Manager worker needs permission to read secrets from the cluster. You can either allow cluster-wide access at install time or grant namespace-scoped access with RBAC (least-privilege):

  • Cluster-wide access: Set global.worker.clusterLevelSecretAccess to true in the Helm values when installing Red Hat Edge Manager on OpenShift. See Installing Red Hat Edge Manager on OpenShift.
  • Namespace-scoped access: Create a Role and RoleBinding in the namespace where the secrets are stored so the flightctl-worker service account can get secrets in that namespace only. For details, see the OpenShift RBAC documentation.

Example: Role and RoleBinding for flightctl-worker secret access

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: <secret_namespace>
1 

  name: flightctl-worker-secret-reader
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: <secret_namespace>
2 

  name: flightctl-worker-secret-reader
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: flightctl-worker-secret-reader
subjects:
- kind: ServiceAccount
  name: flightctl-worker
  namespace: <worker_namespace>
3

1
The namespace for the Role (where your secrets are stored; same as in the device secretRef).
2
The namespace for the RoleBinding (same as the Role — the namespace where your secrets are stored).
3
The namespace where the Red Hat Edge Manager worker runs (for example, rhem-chart-namespace — use your installation’s project name).

Apply the manifest with oc apply -f <file>.yaml.

1.8.1.3. Configuration from an HTTP server
Copiar o link

The Red Hat Edge Manager can query an HTTP server for configuration. The HTTP server can serve static or dynamically generated configuration for a device.

The HTTP Config Provider takes the following parameters:

Expand

Parameter

Description

Repository

The name of a Repository resource defined in the Red Hat Edge Manager.

Suffix

The suffix to append to the base URL defined in the Repository resource. The suffix can include path and query parameters, for example /path/to/endpoint?query=param.

FilePath

The absolute path to the file in the file system of the device to write the response of the HTTP server to.

The Repository resource specifies the HTTP server for the Red Hat Edge Manager to connect to, and the protocol and access credentials to use. After the repository is set up, you can use it to configure multiple devices or device fleets.

1.8.1.4. Configuration inline in the device specification
Copiar o link

You can specify configuration inline in a device specification. When using the inline device specification, the Red Hat Edge Manager does not need to connect to external systems to fetch the configuration.

The Inline Config Provider takes a list of file specifications, where each file specification takes the following parameters:

Expand

Parameter

Description

Path

The absolute path to the file in the file system of the device to write the content to. If a file already exists in the specified path, the file is overwritten.

Content

The UTF-8 or base64-encoded content of the file.

ContentEncoding

Defines how the contents are encoded. Must be either plain or base64. Default value is set to plain.

Mode

Optional. The permission mode of the file. You can specify the octal with a leading zero, for example 0644, or as a decimal without a leading zero, for example 420. The setuid, setgid, and sticky bits are supported. If not specified, the permission mode for files defaults to 0644.

User

Optional. The owner of the file. Specified either as a name or numeric ID. Default value is set to root.

Group

Optional. The group of the file. Specified either as a name or numeric ID.

1.8.2. Additional resources
Copiar o link

  • For more information about device lifecycle hooks and the default rules used by the Red Hat Edge Manager agent, see Device lifecycle hooks.

1.9. Configuring a device to auto-register MicroShift clusters
Copiar o link

If you have a device that runs an operating system image that includes MicroShift, you can configure the device to fetch Red Hat Advanced Cluster Management registration manifests with the HTTP Config Provider and auto-register the MicroShift cluster with Red Hat Advanced Cluster Management.

For the HTTP Config Provider parameters, see Configuration from an HTTP server.

To apply the same configuration across many devices by using a fleet device template, see Configuring fleets to auto-register MicroShift clusters.

1.9.1. Configuring your device
Copiar o link

Complete the following steps:

  1. Create a file, for example acm-registration-repo.yaml, that contains an HTTP Repository resource for the Red Hat Advanced Cluster Management agent registration API. Replace the placeholders in the following example. For Role-Based Access Control and how to obtain values such as the token, follow Importing a managed cluster by using agent registration in the Red Hat Advanced Cluster Management documentation up to, but not including, applying the import manifests on a cluster. 

    apiVersion: flightctl.io/v1beta1
kind: Repository
metadata:
  name: acm-registration
spec:
  type: http
  url: https://<agent_registration_host>
    1 
    
  validationSuffix: /agent-registration/crds/v1
    2 
    
  httpConfig:
    ca.crt: <base64_encoded_ca_bundle>
    3 
    
    token: <bearer_token>
    4
    1
    Root URL of the agent registration HTTPS endpoint only; do not add path suffixes. The device HTTP configuration providers supply paths such as /agent-registration/crds/v1 and /agent-registration/manifests/.
    2
    Suffix Red Hat Edge Manager uses to confirm the endpoint is reachable before the repository is used.
    3
    Base64-encoded PEM CA bundle for the certificate chain that the route presents.
    4
    Bearer token for a principal that can access agent registration (for example, the managed-cluster-import agent registration ServiceAccount on your hub cluster).

  2. Create the Repository resource by running the following command: 

    flightctl apply -f acm-registration-repo.yaml

  3. Verify that the resource has been created and is accessible by Red Hat Edge Manager by running the following command: 

    flightctl get repository/acm-registration

  4. Create or update a Device resource so that its specification matches the same config order as a fleet device template: acm-crd, acm-import, pull-secret, and apply-acm-manifests. 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), omit the pull-secret item from the config list. The apply-acm-manifests hook in the following example waits until the kubeadmin kubeconfig file exists and MicroShift pods are ready before it runs kubectl apply. Use those wait steps when MicroShift might not be running when the hook runs, for example if you apply an operating system image update and this registration configuration together in a single device update. See the following example: 

    apiVersion: flightctl.io/v1alpha1
kind: Device
metadata:
  name: <device_name>
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
    - name: acm-import
      httpRef:
        filePath: /var/local/acm-import/import.yaml
        repository: acm-registration
        suffix: /agent-registration/manifests/{{.metadata.name}}
    - name: pull-secret
      inline:
        - path: "/etc/crio/openshift-pull-secret"
          content: "{\"auths\":{...}}"
    - 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

    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 config entries in the previous example 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 the 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. Apply the device by running the following command: 

    flightctl apply -f <device_file>.yaml
  6. If the device is not yet enrolled, approve the enrollment request in the Flight Control web console or CLI. For more information, see Enrolling devices.

1.10. Managing the device configuration from a Git repository on the CLI
Copiar o link

Create and apply a device configuration in a Git repository.

Complete the following steps:

  1. Create a file, for example site-settings-repo.yaml, that contains the following definition for a Repository resource, named site-settings: 

    apiVersion: flightctl.io/v1alpha1
kind: Repository
metadata:
  name: site-settings
spec:
  type: git
  url: https://github.com/<your_org>/<your_repo>.git

  2. Create the Repository resource by running the following command: 

    flightctl apply -f site-settings-repo.yaml

  3. Verify that the resource has been correctly created and is accessible by Red Hat Edge Manager by running the following command: 

    flightctl get repository/site-settings

    See the following example output: 

    NAME           TYPE  REPOSITORY URL                                 ACCESSIBLE
site-settings  git   https://github.com/<your_org>/<your_repo>.git  True

  4. Apply the example-site configuration to a device by update the device specification: 

    apiVersion: flightctl.io/v1alpha1
kind: Device
metadata:
  name: <device_name>
spec:
[id="..."]
  config:
    1 
    
    - name: example-site
      gitRef:
        repository: site-settings
        targetRevision: production
        path: /etc/example-site
    2 
    
[...]
    1
    The example configuration takes all the files from the example-site directory from the production branch of the site-settings repository and places the files in the root directory (/).
    2
    Ensure that the target path is writeable by creating your directory structure. The root directory (/) is not writeable in bootc systems.

1.11. Managing a catalog repository on the CLI
Copiar o link

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. The Flight Control web console then displays the curated list of OS images, application images, and application data for discovery and deployment.

Complete the following steps:

  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>

1.11.1. Defining catalogs and catalog items in Git
Copiar o link

Your Git repository must contain Catalog and CatalogItem resources that describe what appears in the Software Catalog after synchronization. Store them under the directory (or file path) that you set in the ResourceSync spec.path field.

Important

A ResourceSync with spec.type set to catalog accepts only Catalog and CatalogItem definitions in the synchronized path. If that path includes other resource kinds, synchronization reports an error.

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.

1.11.1.1. Catalog resource
Copiar o link

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>

1.11.1.2. CatalogItem versions, channels, and artifacts
Copiar o link

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"

1.11.1.3. Defining upgrade paths
Copiar o link

Flight Control models relationships between versions 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 may 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 may 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.

1.11.1.4. API version for catalog resources
Copiar o link

Important

Catalog and CatalogItem use the flightctl.io/v1alpha1 API version. Treat them as alpha-stage resources; fields and behavior can change in future Red Hat Edge Manager releases.

1.11.1.5. Verifying synchronized catalogs on the CLI
Copiar o link

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

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

The catalog contents from the synchronized repository will be available in the Software Catalog in the Flight Control web console. For operator tasks in the console, see Using the Software Catalog.

1.12. Device lifecycle hooks
Copiar o link

The Red Hat Edge Manager agent can run user-defined commands at specific points in the device lifecycle by using device lifecycle hooks. For example, you can add a shell script to your operating system images that backs up your application data. You can then specify that the script must run and complete successfully before the agent can start updating the operating system.

As another example, certain applications or system services do not automatically reload their configuration file when the file changes on the disk. You can manually reload the configuration file by specifying a command as another hook, which is called after the agent completes the update process.

The Red Hat Edge Manager agent discovers hook rules only in subdirectories of /etc/flightctl/hooks.d/ and /usr/lib/flightctl/hooks.d/. Those subdirectory names are case-sensitive and must be all lowercase. For example, afterUpdating is not valid; use afterupdating.

The following subdirectories are supported:

Expand

hooks.d subdirectory

Description

beforeupdating

The hook is called after the agent completes preparing for the update, but before changing the operating system. If an action in this hook returns with a failure, the agent cancels the update.

afterupdating

The hook is called after the agent writes the update to disk. If an action in this hook returns with a failure, the agent cancels and rolls back the update.

beforerebooting

The hook is called before the system reboots. The agent blocks the reboot until the action completes or times out. If any action in this hook returns with a failure, the agent cancels and rolls back the update.

afterrebooting

The hook is called when the agent first starts after a reboot. If any action in this hook returns with a failure, the agent reports the failure but continues starting up.

1.12.1. Rule files
Copiar o link

You can define device lifecycle hooks by adding rule files under one of the following directory trees on the device:

  • /usr/lib/flightctl/hooks.d/<hook_directory>/ — read-only from the running system; add rules here by baking them into the operating system image.
  • /etc/flightctl/hooks.d/<hook_directory>/ — read-writable at runtime; you can update these rules by several methods.

In both paths, replace <hook_directory> with one of beforeupdating, afterupdating, beforerebooting, or afterrebooting. For example, a custom rule that runs after the update is written to disk belongs in a file such as /etc/flightctl/hooks.d/afterupdating/50-my-hook.yaml.

When creating and placing the files, you must consider the following practices:

  • The name of the rule must be all lower case.
  • The hook subdirectory name under hooks.d/ must be one of the lowercase names in the table; mixed case or camelCase names are ignored by the agent.
  • If you define rules in both locations, the rules are merged.
  • If you add more than one rule files to a lifecycle hook directory, the files are processed in lexical order of the file names.
  • If you define files with identical file names in both locations, the file in the /etc folder takes precedence over the file of the same name in the /usr folder.

A rule file is written in YAML format and contains a list of one or more actions. An action can be an instruction to run an external command.

When you specify many actions for a hook, the actions are performed in sequence, finishing one action before starting the next.

If an action returns with a failure, the following actions are skipped.

A run action takes the following parameters:

Expand

Parameter

Description

Run

The command to run, including any flags or arguments. Specify the full path to the executable (for example /usr/bin/nmcli connection reload) or an executable name that resolves through the PATH environment variable of the agent (for example nmcli conn reload), consistent with the built-in rules under /usr/lib/flightctl/hooks.d/. The agent uses the PATH from its runtime environment (for example, as set when the agent runs as a systemd service). The command is not run in a shell: the rule value is not shell-expanded, so you cannot use shell parameter expansion such as $HOME or chain commands with | or ; in the rule text. To use shell features, invoke a shell explicitly, for example /usr/bin/bash -c 'echo $SHELL $HOME $USER'.

EnvVars

Optional. A list of key-value pairs to set as environment variables for the command.

WorkDir

Optional. The directory the command is run from.

Timeout

Optional. The maximum duration that is allowed for the action to complete. Specify the duration as a single positive integer followed by a time unit. The s, m, and h units are supported for seconds, minutes, and hours, respectively.

If

Optional. A list of conditions that must be true for the action to be run. If not provided, actions run unconditionally.

By default, actions are performed every time the hook is triggered. However, for the afterupdating hook, you can use the If parameter to add conditions that must be true for an action to be performed. Otherwise, the action is skipped.

For example, to run an action only if a given file or directory changes during the update, you can define a path condition that takes the following parameters:

Expand

Parameter

Description

Path

An absolute path to a file or directory that must change during the update as condition for the action to be performed. Specify paths by using forward slashes (/). If the path is to a directory, it must end with a forward slash (/). If you specify a path to a file, the file must have changed to satisfy the condition. If you specify a path to a directory, a file in that directory or any of its subdirectories must have changed to satisfy the condition.

Op

A list of file operations, such as created, updated, and removed, to limit the type of changes to the specified path as condition for the action to be performed.

If you specify a path condition for an action in the afterupdating hook, you have the following variables that you can include in arguments to your command and are replaced with the absolute paths to the changed files:

Expand

Variable

Description

${ Path }

The absolute path to the file or directory specified in the path condition.

${ Files }

A space-separated list of absolute paths of the files that changed during the update and are covered by the path condition.

${ CreatedFiles }

A space-separated list of absolute paths of the files that were created during the update and are covered by the path condition.

${ UpdatedFiles }

A space-separated list of absolute paths of the files that were updated during the update and are covered by the path condition.

${ RemovedFiles }

A space-separated list of absolute paths of the files that were removed during the update and are covered by the path condition.

The Red Hat Edge Manager agent includes a built-in set of rules defined in /usr/lib/flightctl/hooks.d/afterupdating/00-default.yaml. The following commands are executed if certain files are changed:

Expand

File

Command

Description

/etc/systemd/system/

systemctl daemon-reload

Changes to systemd units are activated by signaling the systemd daemon to reload the systemd manager configuration. This reruns all generators, reloads all unit files, and re-creates the entire dependency tree.

/etc/NetworkManager/system-connections/

nmcli conn reload

Changes to NetworkManager system connections are activated by signaling the NetworkManager daemon to reload all connections. For more information, see the Additional resources section.

/etc/firewalld/

firewall-cmd --reload

Changes to the permanent configuration of firewalld are activated by signaling firewalld to reload firewall rules as new runtime configuration.

1.12.2. Additional resources
Copiar o link

See Configuring and managing networking.

1.13. Using the Software Catalog
Copiar o link

The Red Hat Edge Manager Software Catalog provides a curated list of operating system images, application images, and application data (for example, AI models) that you can discover and deploy from the Flight Control web console. Using the catalog, you can install or update software on a device, or apply catalog software through a fleet device template so that every device selected into the fleet receives the configuration, without entering Open Container Initiative (OCI) image references manually.

1.13.1. Catalog contents
Copiar o link

The catalog can include:

  • Operating system images: Bootable container (bootc) images that you can deploy or update on edge devices.
  • Application images: Containerized applications (Compose, Quadlet, Container, or Helm) that you can deploy to devices.
  • Application data: OCI artifacts such as AI models that applications might require.

Catalog contents are provided by catalog endpoints configured by your administrator. The catalog surface in the web console is analogous to the Software Catalog in the Red Hat OpenShift Container Platform web console.

1.13.2. Configuring catalog endpoints (administrators)
Copiar o link

Administrators configure one or more catalog endpoints in Flight Control so that operators see a curated list of software. Access to the catalog is controlled by permissions; operators either have access to view the catalog or they do not. The same catalog content is available to every operator who has access, regardless of which devices or fleets they manage; fleet-specific or environment-specific catalog visibility is not supported.

1.13.2.1. Catalog repository type
Copiar o link

Flight Control supports a catalog resource sync in addition to fleet resource syncs. A catalog resource sync points to a catalog endpoint and can use optional authentication. For details, see Managing a catalog repository.

1.13.3. Using the Software Catalog (operators)
Copiar o link

1.13.3.1. Browsing the catalog
Copiar o link

In the Flight Control web console, open the Software Catalog to browse available OS images, application images, and application data. Published catalog definitions can organize versions into channels (for example, stable or candidate) when your administrator configures them that way. A version can belong to more than one channel. The catalog shows eligible versions and, where applicable, validated upgrade paths so you can choose appropriate updates.

1.13.3.2. Update availability and release information
Copiar o link

When a device runs catalog software, or devices in a fleet run catalog software that is defined in the fleet device template, and a newer version exists along an allowed update path, the Flight Control web console surfaces that an update is available—for example from the Catalog tab when you open a device or the details for a fleet.

If the catalog publisher includes release notes or change highlights for a version, that information can appear when you review an update so you can decide whether and when to apply it. Which details you see depends on what your administrator publishes in the catalog definitions.

1.13.3.3. Validated upgrade paths and compatibility
Copiar o link

Catalog items can define an upgrade graph. Each published version is a node, and each allowed upgrade path (an edge in the graph) connects one version to the next. That model follows the Cincinnati update protocol, which Red Hat OpenShift Container Platform uses for cluster updates. The graph lets your organization expose tested transitions instead of every tag in a registry.

You might not be offered every newer tag as a direct update from your current version. When the graph does not define a jump, apply the intermediate versions that the console offers first, or ask your administrator to extend the catalog definitions. The console guides you toward allowed targets and avoids disallowed jumps when those guardrails are enforced.

1.13.3.4. Installing from the catalog
Copiar o link

You can install an OS image or application on a single device, or add it to a fleet device template so that all devices in the fleet receive it, directly from the catalog:

  1. In the Flight Control web console, open the Software Catalog.
  2. Select the item you want to deploy (OS image or application).
  3. Choose Deploy and select the target device or fleet (for a fleet, the catalog updates the fleet device template for devices that match the fleet label selector).
  4. For applications, follow the on-screen guidance to provide required parameters. The UI can validate parameters and show help text so you do not need to know the application format or technical details.
  5. Confirm the deployment. The Red Hat Edge Manager agent on the target device or devices will apply the change when it checks in.

1.13.3.5. Updating from the catalog
Copiar o link

When a newer version of an OS image or application is available along an allowed path in the catalog, you can update an individual device or update catalog software configured in a fleet device template from the catalog. Installed catalog software is compared to published versions and upgrade edges; see Validated upgrade paths and compatibility. For what you might see before you choose to update, see Update availability and release information.

Updates are visible in the Catalog tab of the device details view, or of the fleet details view for fleets whose device template includes catalog-defined software.

  1. In the Flight Control web console, open the details for the device you want to update, or open the fleet whose device template configures the catalog software, then open the Catalog tab.
  2. When an update is available, use the Update action for the relevant device or for the fleet whose device template defines the catalog software.
  3. Confirm the update. The agent will download and apply the new version according to the applicable update policy.

1.13.3.6. Provisioning guidance when installing a bootc image to a new device
Copiar o link

When you choose to install a bootc image from the catalog to a device that is not yet enrolled, the Flight Control web console can provide scenario-specific provisioning guidance, for example:

  • For a physical device: Steps and a link to download the required artifact (ISO or disk image) for bare-metal installation.
  • For a virtual device on OpenShift Virtualization: Steps and a link to download the artifact (for example, QCow2) and guidance for provisioning the virtual machine.

Use that guidance together with the procedures in Provisioning devices to complete enrollment.

1.14. Image and artifact pruning
Copiar o link

The Red Hat Edge Manager agent can automatically remove unused container images and OCI artifacts from devices to free disk space. This helps prevent storage exhaustion on edge devices with limited capacity.

1.14.1. How pruning works
Copiar o link

Image and artifact pruning uses a "lost reference" model:

  1. Reference tracking: Before each device update, the agent records all images and artifacts referenced in the current and desired device specifications to a file (/var/lib/flightctl/image-artifact-references.json).
  2. Pruning execution: After a successful spec update, the agent compares the previously recorded references with the current device specifications. Any images or artifacts that were previously referenced but are no longer needed are eligible for removal.

  3. Safe pruning: The agent only removes items that:

    • Were previously recorded in the references file
    • Are no longer referenced in the current or desired device specifications
    • Exist locally on the device
  4. Preservation: Images and artifacts required for current operations or potential rollback (desired state) are always preserved, even if they appear in the references file.
Note

Pruning runs automatically after successful device spec updates. The references file is maintained even when pruning is disabled, so pruning behavior is accurate when you enable the feature later.

1.14.2. What gets pruned
Copiar o link

The pruning process considers the following types of OCI targets:

  • Application images: Container images referenced by Compose, Quadlet, Container, or Helm applications
  • OS images: Operating system images specified in the device OS configuration
  • Helm charts: Charts referenced by Helm applications

1.14.3. Configuring pruning
Copiar o link

Image and artifact pruning is disabled by default. To enable it, configure the agent pruning settings.

1.14.3.1. Base configuration
Copiar o link

Add the pruning configuration to the main agent configuration file at /etc/flightctl/config.yaml: 

image-pruning:
  enabled: true

1.14.3.2. Drop-in configuration
Copiar o link

You can also configure pruning using drop-in files in /etc/flightctl/conf.d/. This allows you to enable or disable pruning for specific devices or fleets without changing the base configuration.

Create a drop-in file (for example, /etc/flightctl/conf.d/enable-pruning.yaml): 

image-pruning:
  enabled: true

Drop-in files are processed in lexical order and override the base configuration. For example, to disable pruning via a drop-in file: 

image-pruning:
  enabled: false
Note

When you use drop-in files in /etc/flightctl/conf.d/, the agent reloads its configuration automatically when those files change. When you change the base configuration file (/etc/flightctl/config.yaml) or need to apply changes immediately, send the flightctl-agent process a SIGHUP signal (for example, run kill -HUP $(pgrep flightctl-agent)) or restart the agent service.

Tip

Consider disabling pruning when you are experimenting with many images that were previously pruned because their references were lost and are now present again. This prevents the agent from immediately pruning images you are actively testing, so you can iterate on configurations without repeatedly re-downloading images.

1.14.4. Pruning behavior
Copiar o link

  • Automatic execution: Pruning runs automatically after successful device spec updates. No manual intervention is required.
  • Non-blocking: Pruning errors do not block device reconciliation. If pruning fails, the agent logs a warning and continues normal operation.
  • Reference accumulation: The references file accumulates references over time, even when pruning is disabled. If you enable pruning later, the agent has accurate historical data about what was previously referenced.
  • Incremental updates: The references file is updated before each upgrade to include all currently referenced images and artifacts, so tracking stays current.

1.14.5. Example scenarios
Copiar o link

Scenario 1: Application update * Device initially runs application quay.io/myorg/app:v1.0 * Application is updated to quay.io/myorg/app:v2.0 * After successful update, the v1.0 image is pruned (if it was previously recorded)

Scenario 2: Application removal * Device runs multiple applications * One application is removed from the device specification * After successful update, images and artifacts used only by the removed application are pruned

Scenario 3: OS image update * Device OS is updated from quay.io/flightctl/rhel:9.4 to quay.io/flightctl/rhel:9.5 * After successful update, the old OS image (9.4) is pruned (if it was previously recorded)

1.14.6. Monitoring pruning
Copiar o link

Pruning operations are logged by the agent. You can monitor pruning activity as follows:

  • Agent logs: Check the agent systemd journal for pruning messages: 

    journalctl -u flightctl-agent -f | grep -i pruning

  • Log messages: The agent logs messages such as:

    • "Starting pruning of X eligible images and Y eligible artifacts"
    • "Pruning complete: removed X of Y eligible images, Z of W eligible artifacts"

1.15. Monitoring device resources
Copiar o link

You can set up resource monitors for device resources and create alerts when the utilization of resources crosses a defined threshold. When the agent alerts the Red Hat Edge Manager service, the service sets the device status to degraded or error, depending on the severity level.

Resource monitors take the following parameters:

Expand

Parameter

Description

MonitorType

The resource to monitor. The CPU, Memory, and Disk resources are currently supported.

SamplingInterval

The interval in which the monitor samples usage, specified as a positive integer followed by a time unit: s for seconds, m for minutes, h for hours.

AlertRules

A list of alert rules.

Path

For Disk monitor only. The absolute path to the directory to monitor. Utilization reflects the file system that contains the path, even if the defined path is not a mount point.

Alert rules take the following parameters:

Expand

Parameter

Description

Severity

The severity of the alert rule can be Info, Warning, or Critical. Only one alert rule is allowed for each severity level and monitor.

Duration

The duration that resource usage is measured and averaged over when sampling, specified as a positive integer followed by a time unit: s for seconds, m for minutes, h for hours. The duration must be smaller than the sampling interval.

Percentage

The usage threshold that triggers the alert, as percentage value. The value ranges from 0 to 100 without the % sign.

Description

A human-readable description of the alert. Add details about the alert to help with debugging. By default, the alert description is load is above >% for more than.

1.15.1. Monitoring device resources using the CLI
Copiar o link

Monitor the resources of your device through the CLI, providing you with the tools and commands to track performance and troubleshoot issues.

Complete the following steps:

  • Add resource monitors in the spec.resources section of the device specification. For example, add the following monitor for your disk: 

    apiVersion: flightctl.io/v1alpha1
kind: Device
metadata:
  name: <device_name>
spec:
[id="..."]
  resources:
  - monitorType: Disk
    samplingInterval: 5s
    1 
    
    path: /application_data
    2 
    
    alertRules:
    - severity: Warning
    3 
    
      duration: 30m
      percentage: 75
      description: Disk space for application data is >75% full for over 30m.
    - severity: Critical
    4 
    
      duration: 10m
      percentage: 90
      description: Disk space for application data is >90% full over 10m.
[id="..."]
    1
    Samples usage every 5 seconds.
    2
    Checks disk usage on the file system that is associated with the /applications_data path.
    3
    Initiates a warning if the average usage exceeds 75% for more than 30 minutes.
    4
    Initiates a critical alert if the average usage exceeds 90% for over 10 minutes.
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Legal Notice

Theme

© 2026 Red HatVoltar ao topo