When a factory-imaged physical edge device boots for the first time, an optional onboarding wizard lets onsite personnel supply per-device settings before the device enrolls into Red Hat Edge Manager. The wizard runs as a Cockpit plugin and is delivered by the flightctl-onboarding RPM.

Image requirement

The flightctl-onboarding RPM is required in the device operating system image only when you use first-boot onboarding. Include this package when you build images for devices that need per-site configuration before they can enroll into Red Hat Edge Manager. You do not need this package when the image already provides working network connectivity, enrollment credentials, and agent configuration at deploy time. In that case, the device can enroll through the standard flow without the wizard. To include the package when you build an image, see Optional: Include first-boot onboarding (flightctl-onboarding) in the Additional resources section.

When to use first-boot onboarding

Use first-boot onboarding when the following apply:

• The device is a physical system with a factory-installed operating system image that includes the flightctl-onboarding RPM.
• The device requires per-site configuration before it can enroll. Examples include:
  • The device cannot obtain network settings through DHCP or platform metadata services such as cloud-init or Ignition.
  • The device needs a site-specific hostname, labels, or enrollment credentials that are not baked into the image.
  • Onsite personnel must configure a production network interface, proxy, or NTP server before the device can reach the Red Hat Edge Manager service.
• Onsite personnel can access the device through at least one of the following:
  • A local console with a keyboard, mouse, and browser
  • Wired ethernet to a setup IP address on the device
  • A laptop or phone connected to the temporary WiFi access point the device advertises for wizard access

The onboarding wizard collects per-device configuration such as hostname, labels, production network settings, and enrollment credentials. These settings let the device reach the Red Hat Edge Manager service and complete enrollment.

Onboarding workflow

The end-to-end workflow inserts an optional onsite customization step between image deployment and normal device management:

1. The device boots and the flightctl-onboarding service starts.
2. Onsite personnel connect to the onboarding wizard and provide per-device configuration.
3. The onboarding service applies hostname, labels, network, and other settings required at the deployment site. It provisions enrollment credentials through late binding or certificate generation when the image does not include them. It then runs validation checks.
4. The onboarding service removes the temporary onboarding user, tears down the WiFi access point if active, disables itself, and does not run again on subsequent boots.
5. The Red Hat Edge Manager agent enrolls the device automatically using the standard enrollment flow.
6. An authorized user approves the enrollment request in the Red Hat Edge Manager web console or by using the Flight Control CLI. When an enrollment approval policy matches the device request — for example, based on labels or region — the service can auto-approve the request without manual intervention.

Note

When a device already has working network connectivity and agent configuration, the wizard step can be skipped and the agent enrolls through the standard enrollment flow.

For approval steps and CLI commands, see Enrolling devices in the Additional resources section.

Provisioning and production interfaces

The onboarding system distinguishes between two logical network interfaces:

• Provisioning interface: The network path through which onsite personnel reach the Cockpit onboarding wizard. This interface can be a temporary WiFi access point, a setup IP on an ethernet port, or local console access through Cockpit at port 9090. The temporary WiFi access point exists only to reach the wizard; it is not the production network. For connection details, see Access the onboarding wizard in the Additional resources section.
• Production interface: The network interface that the device uses for internet connectivity and for the Red Hat Edge Manager agent to reach the service after onboarding completes. When the device uses WiFi for production connectivity, you configure connection to the site access point or router in a separate wizard step.

On some devices, both logical interfaces map to the same physical network port. On others, provisioning and production traffic use separate physical interfaces. When provisioning and production share one interface, the wizard warns you before it applies production settings. After you confirm, the wizard delegates cleanup to a background process so that it completes even when the browser connection is lost during the network change.

Before you begin onsite

When a device with the flightctl-onboarding RPM boots for the first time, confirm that you can reach the device. Use at least one supported access method before onsite personnel start the wizard; for details, see Access the onboarding wizard in the Additional resources section.

You do not need to bake enrollment credentials into the image in advance. The wizard supports full late binding: onsite personnel enter the enrollment endpoint and operator credentials, and the wizard generates an enrollment certificate for the device agent. Operator credentials are separate from the temporary onboarding user on the device. The enrollment certificate secures the agent’s initial connection to the Red Hat Edge Manager service; you do not enter it manually. For more information, see Enrollment methods and Enrolling devices in the Additional resources section.