Enroll and view 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:

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:

Enroll devices on the CLI
Copy link

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

Before you begin
Copy link

About this task
Copy link

Procedure
Copy link

  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:

    NAME           APPROVAL  APPROVER  APPROVED LABELS
<device_name>  Pending   <none>    <none>
    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

    See the following example output:

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

What to do next
Copy link

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.

View devices
Copy link

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

View device inventory and device details on the web UI
Copy link

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

Before you begin
Copy link

About this task
Copy link

Procedure
Copy link

  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.

View device inventory and device details on the CLI
Copy link

View the device inventory and retrieve detailed information by using the flightctl command.

About this task
Copy link

Procedure
Copy link

  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:
    region: eu-west-1
    site: factory-berlin
spec:
  os:
    image: quay.io/flightctl/rhel:9.5
  config:
  - name: my-os-configuration
    configType: GitConfigProviderSpec
    gitRef:
      path: /configuration
      repository: my-configuration-repo
      targetRevision: production
status:
  os:
    image: quay.io/flightctl/rhel:9.5
  config:
    renderedVersion: "1"
  applications:
    data: {}
    summary:
      status: Unknown
  resources:
    cpu: Healthy
    disk: Healthy
    memory: Healthy
  systemInfo:
    architecture: amd64
    bootID: 037750f7-f293-4c5b-b06e-481eef4e883f
    operatingSystem: linux
  summary:
    info: ""
    status: Online
  updated:
    status: UpToDate
  lastSeen: "2024-08-28T11:45:34.812851905Z"
# [...]
    labels
    User-defined labels assigned to the device.
    spec:os:image
    The target operating system image version of the device.
    spec:config
    The target operating system configuration of the device.
    status:os:image
    The current operating system image version of the device.
    status:config:renderedVersion
    The current operating system configuration version of the device.
    status:applications:data
    The current list of deployed applications of the device.
    status:applications:summary
    The health status of applications on the device.
    status:resources
    The availability of CPU, disk, and memory resources.
    status:systemInfo
    Basic system information.
    status:summary:status
    The health status of the device.
    status:updated:status
    The update status of the device.
    status:lastSeen
    The last check-in time and date of the device.

Labels and label selectors
Copy link

You can organize resources by assigning labels for location, hardware, or purpose. The Red Hat Edge Manager labels follow the same syntax, principles, and operators as Kubernetes labels and label selectors. Use these labels to select devices or apply operations to devices in the inventory.

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 selector Selected 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.

View devices and their labels on the web UI
Copy link

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

About this task
Copy link

Procedure
Copy link

  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 labels on the CLI
Copy link

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

About this task
Copy link

Complete the following steps:

Procedure
Copy link

  1. View devices in your inventory with their labels 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

Update labels on the CLI
Copy link

You can update the labels on your devices by using the Red Hat Edge Manager CLI.

About this task
Copy link

Complete the following steps:

Procedure
Copy link

  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:
[...]
  3. Save the file and apply the updated device definition by running the following command: 
    flightctl apply -f my_device.yaml
  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