Skip to content

[Nexthop] Distro CLI device update skeleton#980

Draft
raghav-nexthop wants to merge 3 commits intofacebook:mainfrom
nexthop-ai:distro_cli_3.1_device_update
Draft

[Nexthop] Distro CLI device update skeleton#980
raghav-nexthop wants to merge 3 commits intofacebook:mainfrom
nexthop-ai:distro_cli_3.1_device_update

Conversation

@raghav-nexthop
Copy link
Contributor

@raghav-nexthop raghav-nexthop commented Mar 6, 2026

Pre-submission checklist

  • I've ran the linters locally and fixed lint errors related to the files I modified in this PR. You can install the linters by running pip install -r requirements-dev.txt && pre-commit install
  • pre-commit run

Summary

This PR introduces DeviceUpdater skeleton in order to provide device update functionality in the FBOSS distro CLI, to update FBOSS components on deployed devices. Specifically, this PR includes:

  • DeviceUpdater class with validation logic for update manifests
  • Component validation (kernel, platform-stack, forwarding-stack)
  • Update manifest schema and validation
  • Unit tests for validation logic

Test Plan

$ python3 -m pytest fboss-image/distro_cli/tests/device_test.py::TestDeviceUpdater -v

fboss-image/distro_cli/tests/device_test.py::TestDeviceUpdater::test_get_services_from_component_services PASSED
fboss-image/distro_cli/tests/device_test.py::TestDeviceUpdater::test_validate_component_not_in_manifest PASSED
fboss-image/distro_cli/tests/device_test.py::TestDeviceUpdater::test_validate_component_with_no_services PASSED
fboss-image/distro_cli/tests/device_test.py::TestDeviceUpdater::test_validate_component_without_download_or_execute PASSED
fboss-image/distro_cli/tests/device_test.py::TestDeviceUpdater::test_validate_non_updatable_component PASSED
fboss-image/distro_cli/tests/device_test.py::TestDeviceUpdater::test_validate_success PASSED

================================================================ 6 passed in 0.03s =================================================================

@travisb-nexthop
[Nexthop] Distro CLI: Add getip and ssh commands
bf4be96 
The Distro CLI getip and ssh commands make a best-effort attempt to
determine an IP for the given switch based on its MAC address and then
either return that IP or directly ssh to it.

It does so by connecting to the Distro Infra container and checking on
the configured interface for pre-existing IP neighbor/ARP entries. If
no such entries are found it will attempt a subnet ping to refresh the
Linux kernel neighbor entries.

In most cases this is sufficient after the system has PXE booted and
therefore the neighbor cache is filled.

Testing is as easy as starting the Distro Infra container:
```
$ ./distro_infra.sh --intf eth1 --persist-dir data
```

Then running the fboss-image device getip command with the appropriate
MAC address:
```
$ ./fboss-image device dc:da:4d:fc:ad:2d getip
[0.00s] Getting IP for device dc:da:4d:fc:ad:2d
10.250.33.2
```
@travisb-nexthop
Distro CLI image command
0b14af0 
The fboss-image device image command configures the Distro
Infrastructure to PXE boot the given image file for the given device
on the next reboot.

This replaces the manual steps previously necessary with the MVP
Distro Infrastucture.

Testing:

```
$ ./fboss-image device dc:da:4d:fc:ad:2d image nh-fboss-broadcom-xgs.tar
[0.00s] Setting image for device dc:da:4d:fc:ad:2d: nh-fboss-broadcom-xgs.tar
[0.07s] Using persistent directory: /home/travisb/work/upstream/fboss/fboss-image/distro_infra/data
[0.07s] Extracting image tarball to /home/travisb/work/upstream/fboss/fboss-image/distro_infra/data/dc-da-4d-fc-ad-2d...
[1.96s] Image extracted successfully to /home/travisb/work/upstream/fboss/fboss-image/distro_infra/data/dc-da-4d-fc-ad-2d
[1.96s] Enabling PXE boot for MAC address: dc-da-4d-fc-ad-2d
[2.09s] Successfully configured device dc:da:4d:fc:ad:2d with image nh-fboss-broadcom-xgs.tar
[2.09s] Device is ready for PXE boot
```

Then watch the switch PXE boot on the next boot:
```
>>Checking Media Presence......
>>Media Present......
>>Start PXE over IPv6 on MAC: DC-DA-4D-FC-AD-2D. Press ESC key to abort PXE boot..
  Station IP address is FC00:33:0:0:0:FB05:5030:774C
  Server IP address is FC00:33:0:0:0:0:0:1000
  NBP filename is ipxev6.efi
  NBP filesize is 1158144 Bytes

>>Checking Media Presence......
>>Media Present......
 Downloading NBP file...

  NBP file downloaded successfully.
iPXE initialising devices...
```
@raghav-nexthop raghav-nexthop requested a review from a team as a code owner March 6, 2026 01:14
@meta-cla meta-cla bot added the CLA Signed label Mar 6, 2026
@raghav-nexthop raghav-nexthop changed the title Distro cli 3.1 device update Distro CLI device update command skeleton Mar 6, 2026
@raghav-nexthop raghav-nexthop changed the title Distro CLI device update command skeleton Distro CLI device update skeleton Mar 6, 2026
@raghav-nexthop raghav-nexthop changed the title Distro CLI device update skeleton [Nexthop] Distro CLI device update skeleton Mar 6, 2026
@raghav-nexthop raghav-nexthop mentioned this pull request Mar 6, 2026
Draft
2 tasks
@raghav-nexthop raghav-nexthop marked this pull request as draft March 6, 2026 01:33
@raghav-nexthop
Distro CLI: Add DeviceUpdater skeleton with validation logic
ef00567 
- Add DeviceUpdater class with component validation
- Add COMPONENT_SERVICES mapping for updatable components
- Add test manifest and unit tests for validation logic
- Stub implementations for artifact acquisition, package creation, and transfer

This is the first step in implementing device update functionality.
@raghav-nexthop raghav-nexthop force-pushed the distro_cli_3.1_device_update branch from 9b09ced to ef00567 Compare March 6, 2026 01:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

CLA Signed nexthop

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@raghav-nexthop @travisb-nexthop