Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Manage devices

The Red Hat Edge Manager manages the device lifecycle from enrollment to decommissioning of a device. The device lifecycle also includes device management, such as organizing, monitoring, and updating your devices with the Red Hat Edge Manager.

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

You only need to specify the required 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 different configurations.
  • If you use external automation for updating the device.

The following sections focus on managing individual devices:

6.1. Enroll devices
Copy link

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

The first time the Red Hat Edge Manager agent runs on a device, the agent prepares for the enrollment process by generating a cryptographic key pair. The cryptographic key pair serves as the unique cryptographic identity of the device. The key pair consists of a public and a private key. The private key never leaves the device, so that the device cannot be duplicated or impersonated.

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, see the following sections:

6.1.1. Enrolling devices on the CLI
Copy link

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

Prerequisites

Procedure

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

    flightctl get enrollmentrequests --field-selector="status.approval.approved != true"
    Copy to Clipboard Toggle word wrap

    See the following example: 

    NAME           APPROVAL  APPROVER  APPROVED LABELS
<device_name>  Pending   <none>    <none>
    Copy to Clipboard Toggle word wrap
    Note

    The unique device name is generated by the agent and you cannot change it. The agent chooses a base32-encoded hash of its public key as the 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
    Copy to Clipboard Toggle word wrap

    See the following example output: 

    NAME           APPROVAL  APPROVER  APPROVED LABELS
<device_name>  Approved  user      region=eu-west-1,site=factory-berlin
    Copy to Clipboard Toggle word wrap

After you approve the enrollment request, the service issues the management certificate for the device and registers the device in the device inventory. You can then manage the device.

6.2. View devices
Copy link

To get more information about the devices in your inventory, you can use the Red Hat Edge Manager CLI.

You can view details for enrolled devices, including their status and health, on the Red Hat Edge Manager web UI

Prerequisites

Procedure

  1. From the navigation panel, select Application Links Edge Manager. This opens the external Edge Manager instance.
  2. From the navigation panel, select Devices where you can view your device inventory, details, and decommission devices.

Complete the following steps:

Procedure

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

    flightctl get devices
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

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

    flightctl get device/<device_name> -o yaml
    Copy to Clipboard Toggle word wrap

    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 
    
    configType: GitConfigProviderSpec
    gitRef:
      path: /configuration
      repository: my-configuration-repo
      targetRevision: production
status:
  os:
    image: quay.io/flightctl/rhel:9.5
    4 
    
  config:
    renderedVersion: "1"
    5 
    
  applications:
    data: {}
    6 
    
    summary:
      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 
    
  lastSeen: "2024-08-28T11:45:34.812851905Z"
    12 
    
[...]
    Copy to Clipboard Toggle word wrap
    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 of the device.
    7
    The health status of 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.
    12
    The last check-in time and date of the device.

6.2.3. Labels and label selectors
Copy link

You can organize your resources by assigning them labels, for example, to record their 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. You can 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 devices 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 devices by creating a label selector. A label selector is a comma-separated list of labels for selecting devices 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 about labels and selectors, see Labels and Selectors in the Kubernetes documentation.

View devices and their associated labels on the web UI. You can use labels to organize your devices and device fleets.

Complete the following steps:

  1. From the navigation panel, select Application Links Edge Manager. This opens the external Edge Manager instance.
  2. From the navigation panel, select Devices.
  3. Select the device you want to manage. In the Details tab you can view the associated labels under Labels.

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

Complete the following steps:

Procedure

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

    flightctl get devices -o wide
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

    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
    Copy to Clipboard Toggle word wrap

6.2.3.3. Updating labels on the CLI
Copy link

Update labels on your devices by using the CLI.

Complete the following steps:

Procedure

  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
    Copy to Clipboard Toggle word wrap

  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:
[...]
    Copy to Clipboard Toggle word wrap

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

    flightctl apply -f my_device.yaml
    Copy to Clipboard Toggle word wrap

  4. Verify your changes by running the following example output: 

    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
    Copy to Clipboard Toggle word wrap

6.2.4. Field selectors
Copy link

Field selectors filter a list of Red Hat Edge Manager resources based on specific resource field values. They follow the same syntax, principles, and operators as Kubernetes Field and Label selectors, with additional operators available for more advanced search use cases.

6.2.4.1. Supported fields
Copy link

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.

6.2.4.2. List of additional supported fields
Copy 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
KindFields

Certificate Signing Request

status.certificate

Device

status.summary.status

status.applicationsSummary.status

status.updated.status

status.lastSeen

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

6.2.4.3. Fields discovery
Copy link

Some Red Hat Edge Manager resources might expose additional supported fields. You can discover the supported fields by using flightctl 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'
Copy to Clipboard Toggle word wrap 
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.lastSeen status.summary.status status.updated.status]
Copy to Clipboard Toggle word wrap

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'
Copy to Clipboard Toggle word wrap

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

Examples

Example 1: Excluding a specific device by name

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

flightctl get devices --field-selector 'metadata.name!=c3tkb18x9fw32fzx5l556n0p0dracwbl4uiojxu19g2'
Copy to Clipboard Toggle word wrap

Example 2: Filter by owner, labels, and creation timestamp

This command retrieves devices owned by Fleet/pos-fleet, located in the us region, and 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'
Copy to Clipboard Toggle word wrap

Example 3: Filter by Owner, Labels, and Device Status

This command retrieves devices owned by Fleet/pos-fleet, located in the us region, and with 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'
Copy to Clipboard Toggle word wrap

6.2.4.4. Supported operators
Copy link

Expand
OperatorSymbolDescription

Exists

exists

Checks if a field exists

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

6.2.4.4.1. Operators usage by field type
Copy link

Each field type supports a specific subset of operators:

Expand
Field TypeSupported OperatorsValue

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.

Note

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.

Note

Using Array[Index] treats the element as the type defined for the array elements. For example string, timestamp, number, or boolean.

Array element

6.3. Update the operating system
Copy link

You can update the operating system of a device by updating the target operating system image name or version in the device specification. When the agent communicates with the server, 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 that is performed 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.

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

Expand
Image TypeImage 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 check the update process by viewing the device status.

For more information, see View devices.

6.3.1. Updating the operating system on the CLI
Copy link

Update a device using the CLI.

Complete the following steps:

Procedure

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

    flightctl get device/<device_name> -o yaml > my_device.yaml
    Copy to Clipboard Toggle word wrap

  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:
[...]
  os:
    image: quay.io/flightctl/rhel:9.5
[...]
    Copy to Clipboard Toggle word wrap

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

    flightctl apply -f <device_name>.yaml
    Copy to Clipboard Toggle word wrap

You can include an operating system-level host configuration in the image to give maximum consistency and repeatability. To update the configuration, 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 are 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. It 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 applications 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.

6.4.1. Configuration providers
Copy link

You can provide configuration from many sources, called configuration providers, in Red Hat Edge Manager. The Red Hat Edge Manager currently supports the following configuration providers:

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:

6.4.1.1. Configuration from a Git repository
Copy 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 you specify the MountPath parameter.

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 the access credentials that the Red Hat Edge Manager must use. You only need to set up the repository once. After setting up, you can use the repository to configure individual devices or device fleets.

6.4.1.2. Secrets from a Kubernetes cluster
Copy 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. You can write the content of that secret to a path on the device file system.

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.

Note

The Red Hat Edge Manager needs permission to access secrets in the defined namespace. For example, creating a ClusterRole and ClusterRoleBinding allows the flightctl-worker service account to get and list secrets in that namespace.

6.4.1.3. Configuration from an HTTP server
Copy 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. You must set up the repository needs once, and then you can use the repository to configure many devices or device fleets.

You can specify configuration inline in a device specification. When you use 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.

Additional resources

Create and apply a device configuration in a Git repository.

Complete the following steps:

Procedure

  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
    Copy to Clipboard Toggle word wrap

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

    flightctl apply -f site-settings-repo.yaml
    Copy to Clipboard Toggle word wrap

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

    flightctl get repository/site-settings
    Copy to Clipboard Toggle word wrap

    See the following example output: 

    NAME           TYPE  REPOSITORY URL                                 ACCESSIBLE
site-settings  git   https://github.com/<your_org>/<your_repo>.git  True
    Copy to Clipboard Toggle word wrap

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

    apiVersion: flightctl.io/v1alpha1
kind: Device
metadata:
  name: <device_name>
spec:
[...]
  config:
    1 
    
  - name: example-site
    configType: GitConfigProviderSpec
    gitRef:
      repository: site-settings
      targetRevision: production
      path: /etc/example-site
    2 
    
[...]
    Copy to Clipboard Toggle word wrap
    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.

6.5. Use device lifecycle hooks
Copy 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 following device lifecycle hooks are supported:

Expand
Lifecycle HookDescription

beforeUpdating

This hook is called after the agent completed preparing for the update and before actually making changes to the system. If an action in this hook returns with failure, the agent cancels the update.

afterUpdating

This hook is called after the agent has written the update to disk. If an action in this hook returns with failure,the agent cancels and rolls back the update.

beforeRebooting

This hook is called before the system reboots. The agent blocks the reboot until running the action has completed or timed out. If any action in this hook returns with failure, the agent cancels and rolls back the update.

afterRebooting

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

6.5.1. Rule files
Copy link

You can define device lifecycle hooks by adding rule files to one of the following locations in the device file system:

  • Rules in the /usr/lib/flightctl/hooks.d/<lifecycle_hook_name>/ drop-in directory are read-only. To add rules to the /usr directory, you must add them to the operating system image during image building.
  • Rules in the /etc/flightctl/hooks.d/<lifecycle_hook_name>/ drop-in directory are read-writable. You can update the rules at runtime by using several methods.

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

  • The name of the rule must be all lower case.
  • 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 has 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 absolute path to the command to run, followed by any flags or arguments, for example /usr/bin/nmcli connection reload. The command is not executed in a shell, so you cannot use shell variables, such as $PATH or $HOME, or chain commands, such as | or ;. If necessary, you can start a shell by specifying the shell as command to run, 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.

If

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

By default, the system performs actions 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

Job type

An absolute path to a file or directory that must change during the update as a 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 a 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.

Additional resources

6.6. Monitor device resources
Copy link

You can set up monitors for device resources and define alerts when the use of these 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
ParameterDescription

MonitorType

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

SamplingInterval

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

AlertRules

A list of alert rules.

Path

(Disk monitor only) The absolute path to the directory to monitor. Utilization reflects the filesystem containing the path, similar to df, even if it’s not a mount point.

Alert rules take the following parameters:

Expand
ParameterDescription

Severity

The alert rule’s severity level out of "Info", "Warning", or "Critical". Only one alert rule is allowed per severity level and monitor.

Duration

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

Percentage

The use threshold that triggers the alert, as percentage value (range 0 to 100 without the "%" sign).

Description

A human-readable description of the alert. This is useful for adding details about the alert that might help with debugging. By default it populates the alert as : load is above >% for more than.

6.6.1. Monitoring device resources on the CLI
Copy link

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

Procedure

  • Add resource monitors in the resources: section of the device’s specification.

    For example, add the following monitor for your disk: 

    apiVersion: flightctl.io/v1alpha1
kind: Device
metadata:
  name: <device_name>
spec:
[...]
  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.
[...]
    Copy to Clipboard Toggle word wrap
    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.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat