Procedure

1. Request a new Red Hat Edge Manager agent enrollment configuration and store it in a file called config.yaml. Run the following command:

   flightctl certificate request --signer=enrollment --expiration=365d --output=embedded > config.yaml

   Copy code to clipboard

2. Create a cloud configuration user data file called cloud-config.yaml that places the agent configuration in the correct location during the first boot. Run the following command:

   cat <<EOF > cloud-config.yaml
   #cloud-config
   write_files:
   - path: /etc/flightctl/config.yaml
     content: $(cat config.yaml | base64 -w0)
     encoding: b64
     permissions: '0600'
   EOF

   Copy code to clipboard

3. Create a Kubernetes Secret that contains the cloud configuration user data file:

   oc create secret generic enrollment-secret --from-file=userdata=cloud-config.yaml

   Copy code to clipboard

4. Create a file that contains the VirtualMachine resource manifest. Replace <your_registry>/<your_repo>:<your_tag> with the location of your QCow2 container disk image. Run the following command:

   cat <<'EOF' > my-bootc-vm.yaml
   apiVersion: kubevirt.io/v1
   kind: VirtualMachine
   metadata:
     name: my-bootc-vm
   spec:
     runStrategy: RerunOnFailure
     template:
       spec:
         domain:
           cpu:
             cores: 1
           memory:
             guest: 1024M
           devices:
             disks:
               - name: containerdisk
                 disk:
                   bus: virtio
               - name: cloudinitdisk
                 disk:
                   bus: virtio
         volumes:
           - name: containerdisk
             containerDisk:
               image: <your_registry>/<your_repo>:<your_tag>
           - name: cloudinitdisk
             cloudInitConfigDrive:
               secretRef:
                 name: enrollment-secret
   EOF

   Copy code to clipboard

5. Apply the resource manifest to your cluster by running the following command:

   oc apply -f my-bootc-vm.yaml

   Copy code to clipboard

Procedure

1. Choose one of the following access methods and complete the associated steps:

   Note

   WiFi and wired access methods use http:// (plain HTTP), while local console access uses https://. Cockpit listens on port 9090 in all cases, but the setup interfaces use IP addresses that do not have browser-trusted TLS certificates. Using HTTP on these interfaces avoids certificate warnings in the browser. Local console access uses Content from localhost is not included.https://localhost:9090 because Cockpit generates a self-signed certificate that browsers accept for localhost.

   Accessing the wizard over WiFi

   When the device has a WiFi interface and the required access-point packages are installed, the onboarding service advertises a temporary WiFi network with a captive portal. This network exists only so you can reach the onboarding wizard. You configure production WiFi connectivity to your site router in a separate wizard step.

   1. On your phone or laptop, open the WiFi settings and connect to the temporary network whose name starts with flightctl- followed by a device-specific suffix. The default WiFi password is onboarding.
   2. When your operating system detects a captive portal, accept the network sign-in prompt. Your browser automatically redirects to the onboarding wizard.
   3. If your browser does not open automatically, open a browser manually and navigate to Content from 10.42.0.1 is not included.http://10.42.0.1:9090 while you are still connected to the temporary network.
   4. If you still cannot reach the wizard over WiFi, use a wired or local-console access method instead. See Troubleshoot device onboarding in the Additional resources section.
   5. Log in to Cockpit with the username onboarding.
   Note

   If hostapd or dnsmasq is not installed on the device, the WiFi access point is unavailable. Use a wired or local-console access method instead.

   Accessing the wizard over wired ethernet

   When the device exposes a setup IP address on an ethernet interface, connect a laptop directly or through a provisioning switch.

   1. Connect your laptop to the same ethernet segment as the device setup interface.
   2. Open a browser and navigate to Content from 192.168.100.1 is not included.http://192.168.100.1:9090. If the image uses a custom static IP for the setup interface, use that address instead.
   3. Log in to Cockpit with the username onboarding.

   Accessing the wizard from the local console

   When the device has a display, keyboard, mouse, and browser, or when you have out-of-band console access:

   1. On the device, open a browser and navigate to Content from localhost is not included.https://localhost:9090.
   2. Log in to Cockpit with the username onboarding.

Procedure

1. Configure the production network interface:

   • Select the interface the device uses to reach the Red Hat Edge Manager service.
   • Configure IPv4 with DHCP or static addressing.
   • Configure IPv6 when your deployment site requires it.
   • Set DNS servers, gateway, and related settings when you use static addressing.
   • Select a VLAN when your deployment site requires VLAN tagging.
   • When the production interface uses WiFi, configure connection to the site access point or router. This step is separate from the temporary WiFi network you use to access the wizard.
2. Optional: Configure NTP servers when your deployment site requires time synchronization before enrollment.
3. Optional: Configure an HTTP proxy for system-wide use when your deployment site requires it.
4. In the onboarding wizard, set the device hostname.

5. Optional: Add device labels as key/value pairs.

   Labels that you enter in the wizard are written to /etc/flightctl/conf.d/50-cockpit-labels.yaml and included in the enrollment request. Use labels to identify the device during enrollment approval. For example, add site, rack, or alias labels. For more information about how the agent processes label drop-ins during enrollment, see Device alias and enrollment labels in the Additional resources section.

6. When the image does not already include enrollment credentials, configure late binding in the wizard. Enter operator credentials so the wizard can request an enrollment certificate from the Red Hat Edge Manager service; you do not enter the enrollment certificate manually.

   • Enter the Red Hat Edge Manager enrollment endpoint URL.
   • Enter operator credentials to authenticate to the Red Hat Edge Manager service.
7. Review all settings on the summary screen.

8. Select Apply to commit the configuration.

   The onboarding service applies your settings, enables production network connectivity, and runs validation checks. When validation succeeds, the service cleans up temporary resources, disables itself, and the Red Hat Edge Manager agent enrolls the device automatically. Approve the enrollment request in the Red Hat Edge Manager web console or by using the Flight Control CLI, or configure an enrollment approval policy to auto-approve requests that match conditions such as labels or region. See Enrolling devices in the Additional resources section.

   When provisioning and production traffic share one physical interface, the wizard warns you before it applies production settings. After you select Apply, the wizard delegates cleanup to a background process so that it completes even when the browser connection is lost during the network change.

   Additional resources

   • Enrolling devices
   • Device alias and enrollment labels
   • Troubleshoot device onboarding

1. /etc/cockpit/system-onboarding/config.json — operator override that survives package upgrades. Only include the keys you want to change; unset keys fall back to the package defaults.
2. /usr/share/cockpit/system-onboarding/config.json — package default installed by the RPM.

Procedure

1. Verify that onboarding is still active:

   systemctl status flightctl-onboarding-setup.service
   ls /var/lib/flightctl-onboarding/.onboarding-complete

   Copy code to clipboard

   When the marker file exists, onboarding has already completed and the wizard is no longer available.

2. Inspect onboarding service logs:

   journalctl -u flightctl-onboarding-setup.service
   journalctl -u flightctl-onboarding-dnsmasq@*.service
   journalctl -u flightctl-onboarding-captive-portal@*.service
   journalctl -u flightctl-onboarding-mask-greenboot.service
   journalctl -u flightctl-agent.service

   Copy code to clipboard
3. When WiFi access is unavailable, confirm that the required packages are installed or use a wired or local-console access method. See Access the onboarding wizard.

4. When network configuration fails, inspect the saved failure logs and reconnect to the wizard by using a supported access method. Correct the interface, IP address, gateway, DNS, VLAN, or enrollment settings.

   Re-entering onboarding mode

   To run the wizard again on a device that already completed onboarding:

5. Remove the completion marker:

   rm -f /var/lib/flightctl-onboarding/.onboarding-complete

   Copy code to clipboard

6. Re-enable and start the onboarding service:

   systemctl enable flightctl-onboarding-setup.service
   systemctl start flightctl-onboarding-setup.service

   Copy code to clipboard
   Warning

   Re-entering onboarding mode is intended for lab recovery and field troubleshooting. Removing the marker on a managed production device can interrupt agent operation until onboarding completes again.

   Additional resources

   • Access the onboarding wizard
   • Enrolling devices
   • Troubleshooting